@czi-sds/data-viz 2.4.3 → 2.5.0

package/dist/shared/ProteinStructureViewer.esm.js

@@ -1,27 +1,28 @@
 "use client";
 import { n as _objectWithoutProperties, t as _objectSpread2 } from "./objectSpread2.esm.js";
-import { i as toCssGradient, n as sampleColorScale, r as sampleSteppedScale, t as PLASMA_COLOR_SCALE } from "./colorScales.esm.js";
+import { A as isEmptySelection, C as resolveSelectionAddresses, D as lociForResidueRange, E as readCameraState, M as selectionKey, N as selectionLabel, O as lociForSelection, P as selectionResidues, S as residueAddressesKey, T as camerasEqual, _ as chainColorMap, b as _asyncToGenerator, c as resolveColorBy, g as themeColor, h as highlightsKey, i as AXES_ON, j as meanOverResidues, k as lociOutsideChains, l as PLDDT_BAND_COLORS, n as exportStructureImage, o as StructureScene, r as AXES_OFF, s as chainSetKey, u as PLDDT_COLOR_SCALE, v as NOTHING_LOADED, w as chainsEqual, y as loadInfo } from "./renderStructureImage.esm.js";
+import { i as toCssGradient, t as PLASMA_COLOR_SCALE } from "./colorScales.esm.js";
 import { Fragment, createContext, forwardRef, memo, useCallback, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
 import styled from "@emotion/styled";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Vec3 } from "molstar/lib/mol-math/linear-algebra";
+import { EmptyLoci, EveryLoci, Loci } from "molstar/lib/mol-model/loci";
+import { OrderedSet } from "molstar/lib/mol-data/int";
+import { Structure, StructureElement, StructureProperties, Unit } from "molstar/lib/mol-model/structure";
 import { Button, Theme, Tooltip, defaultTheme, fontBodyXs, fontBodyXxxs, fontCodeXs, fontHeaderM, getMode, getSemanticColors, getSpaces } from "@czi-sds/components";
 import { ThemeProvider, useTheme } from "@mui/material/styles";
 import { ApertureIcon, ArrowCounterClockwiseIcon, CheckIcon, CopyIcon, EyeIcon, EyeSlashIcon, QuestionIcon } from "@phosphor-icons/react";
-import { Structure, StructureElement, StructureProperties, Unit } from "molstar/lib/mol-model/structure";
 import { clearStructureTransparency, setStructureTransparency } from "molstar/lib/mol-plugin-state/helpers/structure-transparency";
 import { createPluginUI } from "molstar/lib/mol-plugin-ui";
 import { renderReact18 } from "molstar/lib/mol-plugin-ui/react18";
 import { DefaultPluginUISpec } from "molstar/lib/mol-plugin-ui/spec";
 import { PluginBehaviors } from "molstar/lib/mol-plugin/behavior";
-import { setSubtreeVisibility } from "molstar/lib/mol-plugin/behavior/static/state";
 import { PluginConfig } from "molstar/lib/mol-plugin/config";
 import { Representation } from "molstar/lib/mol-repr/representation";
 import { BehaviorSubject, Subject } from "rxjs";
-import { EveryLoci, Loci } from "molstar/lib/mol-model/loci";
 import { PluginReactContext } from "molstar/lib/mol-plugin-ui/base";
 import { ButtonsType, getButton, getButtons, getModifiers } from "molstar/lib/mol-util/input/input-observer";
 import { throttleTime } from "rxjs/operators";
-import { OrderedSet } from "molstar/lib/mol-data/int";
 import { useTheme as useTheme$1 } from "@mui/material";
 import { PluginStateObject } from "molstar/lib/mol-plugin-state/objects";
 import { getChainOptions, getModelEntityOptions, getOperatorOptions, getSequenceWrapper, getStructureOptions } from "molstar/lib/mol-plugin-ui/sequence";
@@ -30,13 +31,7 @@ import { arrayEqual } from "molstar/lib/mol-util";
 import { ParamDefinition } from "molstar/lib/mol-util/param-definition";
 import { Toasts } from "molstar/lib/mol-plugin-ui/toast";
 import { Viewport } from "molstar/lib/mol-plugin-ui/viewport";
-import { Color } from "molstar/lib/mol-util/color";
 import { PluginCommands } from "molstar/lib/mol-plugin/commands";
-import { Vec3 } from "molstar/lib/mol-math/linear-algebra";
-import { BondType } from "molstar/lib/mol-model/structure/model/types";
-import { elementLabel } from "molstar/lib/mol-theme/label";
-import { MolScriptBuilder } from "molstar/lib/mol-script/language/builder";
-import { CustomElementProperty } from "molstar/lib/mol-model-props/common/custom-element-property";
 import { StructureFocusRepresentation } from "molstar/lib/mol-plugin/behavior/dynamic/selection/structure-focus-representation";
 //#region src/core/ProteinStructureViewer/components/ChainLegend/style.ts
 /** Opacity applied to a hidden chain's row, so it reads as off but reachable. */
@@ -689,30 +684,71 @@ function StructureLegend({ chainBandColors, chainColors, chains = [], hiddenChai
 	});
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.134.0/helpers/esm/asyncToGenerator.js
-function asyncGeneratorStep(n, t, e, r, o, a, c) {
-	try {
-		var i = n[a](c), u = i.value;
-	} catch (n) {
-		e(n);
-		return;
-	}
-	i.done ? t(u) : Promise.resolve(u).then(r, o);
-}
-function _asyncToGenerator(n) {
-	return function() {
-		var t = this, e = arguments;
-		return new Promise(function(r, o) {
-			var a = n.apply(t, e);
-			function _next(n) {
-				asyncGeneratorStep(a, r, o, _next, _throw, "next", n);
-			}
-			function _throw(n) {
-				asyncGeneratorStep(a, r, o, _next, _throw, "throw", n);
-			}
-			_next(void 0);
+//#region src/core/ProteinStructureViewer/hooks/useCamera.ts
+/**
+* How long the camera has to stay put before it counts as having come to
+* rest, in ms. Mol* draws on demand, so a camera that has stopped stops the
+* draws, and a trackball still coasting after a drag keeps pushing this back.
+*/
+const CAMERA_SETTLE_MS = 150;
+/**
+* Keeps the camera in step with the camera props after a structure is up:
+* the projection, the orientation, and reporting where the camera comes to
+* rest. Where the camera starts on a structure is decided by the load, which
+* knows when there is something drawn to place it against.
+*/
+function useCamera({ framedOrientationRef, highlights, isReady, onCameraChange, orientation, pluginRef, projection, sceneRef }) {
+	const highlightsRef = useRef(highlights);
+	highlightsRef.current = highlights;
+	const onCameraChangeRef = useRef(onCameraChange);
+	onCameraChangeRef.current = onCameraChange;
+	useEffect(() => {
+		var _pluginRef$current;
+		const canvas3d = (_pluginRef$current = pluginRef.current) === null || _pluginRef$current === void 0 ? void 0 : _pluginRef$current.canvas3d;
+		if (!canvas3d || !isReady || !projection) return;
+		if (canvas3d.props.camera.mode === projection) return;
+		canvas3d.setProps({ camera: { mode: projection } });
+	}, [
+		isReady,
+		pluginRef,
+		projection
+	]);
+	useEffect(() => {
+		const scene = sceneRef.current;
+		if (!scene || !isReady) return;
+		if (orientation === framedOrientationRef.current) return;
+		framedOrientationRef.current = orientation;
+		if (!orientation) return;
+		scene.orient(orientation, highlightsRef.current, 250);
+	}, [
+		framedOrientationRef,
+		isReady,
+		orientation,
+		sceneRef
+	]);
+	useEffect(() => {
+		var _pluginRef$current2;
+		const canvas3d = (_pluginRef$current2 = pluginRef.current) === null || _pluginRef$current2 === void 0 ? void 0 : _pluginRef$current2.canvas3d;
+		if (!canvas3d || !isReady) return;
+		let timer;
+		let reported = null;
+		const subscription = canvas3d.didDraw.subscribe(() => {
+			if (!onCameraChangeRef.current) return;
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				var _onCameraChangeRef$cu;
+				if (canvas3d.camera.transition.inTransition) return;
+				const state = readCameraState(canvas3d);
+				if (reported && camerasEqual(reported, state)) return;
+				reported = state;
+				(_onCameraChangeRef$cu = onCameraChangeRef.current) === null || _onCameraChangeRef$cu === void 0 || _onCameraChangeRef$cu.call(onCameraChangeRef, state);
+			}, CAMERA_SETTLE_MS);
 		});
-	};
+		return () => {
+			subscription.unsubscribe();
+			clearTimeout(timer);
+		};
+	}, [isReady, pluginRef]);
 }
 //#endregion
 //#region src/core/ProteinStructureViewer/hooks/useChainHighlight.ts
@@ -732,13 +768,20 @@ const CHAIN_DIM_TRANSPARENCY = .65;
 * part name and stopping at the comma is what keeps `A` from also matching the
 * chain named `AA`.
 */
-const COMPONENT_CHAIN_ID = /structure-component-(?:polymer|ligand)-([^,]+)/;
+const COMPONENT_CHAIN_ID = /structure-component-(?:polymer|ligand|highlight)-([^,]+)/;
+/** The one component spanning chains: the surface over the visible ones. */
+const SURFACE_COMPONENT = /structure-component-surface(?:,|$)/;
 /** The chain a component was built for, or undefined if it is not a chain's. */
 function componentChainId(component) {
 	var _component$key, _COMPONENT_CHAIN_ID$e;
 	const key = (_component$key = component.key) !== null && _component$key !== void 0 ? _component$key : component.cell.transform.ref;
 	return (_COMPONENT_CHAIN_ID$e = COMPONENT_CHAIN_ID.exec(key)) === null || _COMPONENT_CHAIN_ID$e === void 0 ? void 0 : _COMPONENT_CHAIN_ID$e[1];
 }
+/** True for the surface, which draws every visible chain in one component. */
+function isSurfaceComponent(component) {
+	var _component$key2;
+	return SURFACE_COMPONENT.test((_component$key2 = component.key) !== null && _component$key2 !== void 0 ? _component$key2 : component.cell.transform.ref);
+}
 /** Every chain component of every loaded structure, polymers and ligands. */
 function structureComponents(plugin) {
 	return plugin.managers.structure.hierarchy.current.structures.flatMap((entry) => entry.components);
@@ -759,7 +802,7 @@ function chainsKey(chains) {
 * arriving before the first load looks like. It is applied again after the load
 * rather than being taken as done.
 */
-function dimChainsOutside(_x2, _x3) {
+function dimChainsOutside(_x3, _x4) {
 	return _dimChainsOutside.apply(this, arguments);
 }
 function _dimChainsOutside() {
@@ -772,8 +815,7 @@ function _dimChainsOutside() {
 			const chainId = componentChainId(component);
 			return chainId !== void 0 && !lit.has(chainId);
 		});
-		if (dimmed.length === 0) return true;
-		yield setStructureTransparency(plugin, dimmed, CHAIN_DIM_TRANSPARENCY, function() {
+		if (dimmed.length > 0) yield setStructureTransparency(plugin, dimmed, CHAIN_DIM_TRANSPARENCY, function() {
 			var _ref = _asyncToGenerator(function* (structure) {
 				return Structure.toStructureElementLoci(structure);
 			});
@@ -781,6 +823,16 @@ function _dimChainsOutside() {
 				return _ref.apply(this, arguments);
 			};
 		}());
+		const surfaces = components.filter(isSurfaceComponent);
+		if (surfaces.length > 0) yield setStructureTransparency(plugin, surfaces, CHAIN_DIM_TRANSPARENCY, function() {
+			var _ref2 = _asyncToGenerator(function* (structure) {
+				var _lociOutsideChains;
+				return (_lociOutsideChains = lociOutsideChains(structure, lit)) !== null && _lociOutsideChains !== void 0 ? _lociOutsideChains : EmptyLoci;
+			});
+			return function(_x2) {
+				return _ref2.apply(this, arguments);
+			};
+		}());
 		return true;
 	});
 	return _dimChainsOutside.apply(this, arguments);
@@ -805,7 +857,7 @@ function _dimChainsOutside() {
 * came to rest on, instead of working through a queue of hovers that have
 * already been left.
 */
-function useChainHighlight({ disabled, hiddenChains, loadCount, pluginRef, selectedChains }) {
+function useChainHighlight({ disabled, hiddenChains, loadCount, pluginRef, sceneVersion, selectedChains }) {
 	const hoveredRef = useRef(null);
 	/**
 	* The chains left lit on the canvas as it stands. A freshly loaded structure
@@ -865,51 +917,14 @@ function useChainHighlight({ disabled, hiddenChains, loadCount, pluginRef, selec
 	useEffect(() => {
 		shownRef.current = chainsKey(/* @__PURE__ */ new Set());
 		settle();
-	}, [loadCount, settle]);
+	}, [
+		loadCount,
+		sceneVersion,
+		settle
+	]);
 	return highlightChain;
 }
 //#endregion
-//#region src/common/chainColors.ts
-/**
-* Default colors for telling chains apart, in assignment order.
-*
-* The Okabe-Ito qualitative palette, which is built to stay distinguishable
-* under every common form of color blindness - the reason to prefer it over a
-* hand-picked set, since a complex is read by which chain is which and a
-* viewer that collapses two of them into one color stops answering that.
-*
-* Its black is left out: the canvas inverts with the theme, so a chain painted
-* black would vanish against the dark background. The rest carry enough
-* lightness to hold up against both.
-*
-* Chains past the end of the palette wrap around to the start.
-*/
-const CHAIN_COLOR_PALETTE = [
-	"#009E73",
-	"#0072B2",
-	"#E69F00",
-	"#CC79A7",
-	"#56B4E9",
-	"#D55E00",
-	"#F0E442"
-];
-/**
-* Assigns each chain a color, in the order given, with `overrides` taking
-* precedence by `chainId`.
-*
-* Palette positions are spent on every chain whether or not it is overridden,
-* so overriding one chain does not shift the colors of the others.
-*/
-function chainColorMap(chainIds, overrides) {
-	const colors = /* @__PURE__ */ new Map();
-	chainIds.forEach((chainId, i) => {
-		var _overrides$chainId;
-		const fallback = CHAIN_COLOR_PALETTE[i % CHAIN_COLOR_PALETTE.length];
-		colors.set(chainId, (_overrides$chainId = overrides === null || overrides === void 0 ? void 0 : overrides[chainId]) !== null && _overrides$chainId !== void 0 ? _overrides$chainId : fallback);
-	});
-	return colors;
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/hooks/useChains.ts
 /**
 * Reconciles the chains found in the structure with the visibility and coloring
@@ -1577,159 +1592,6 @@ function useResidueMarkers({ containerRef, residueColors, sequenceWrapper }) {
 	});
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/selection.ts
-/**
-* A stable string for a selection, for comparing one against another.
-*
-* A consumer holding the selection in state hands back a new object on every
-* render, so identity says nothing about whether the selection changed. Order
-* is normalized too: `{ residues: [2, 1] }` and `{ residues: [1, 2] }` select
-* the same residues and must not read as a change.
-*/
-function selectionKey(selection) {
-	var _selection$residues, _selection$chains;
-	const residues = [...new Set((_selection$residues = selection.residues) !== null && _selection$residues !== void 0 ? _selection$residues : [])].sort((a, b) => a - b);
-	return `${[...new Set((_selection$chains = selection.chains) !== null && _selection$chains !== void 0 ? _selection$chains : [])].sort().join(",")}|${residues.join(",")}`;
-}
-/** True when the selection names nothing at all. */
-function isEmptySelection(selection) {
-	var _selection$residues2, _selection$chains2;
-	if (!selection) return true;
-	return !((_selection$residues2 = selection.residues) === null || _selection$residues2 === void 0 ? void 0 : _selection$residues2.length) && !((_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length);
-}
-/**
-* The residues a selection covers, ascending and without repeats.
-*
-* Chains are expanded through `residuesByChain`, which was read off the loaded
-* structure, so a chain contributes exactly the residues it holds rather than
-* the span between its ends. A residue named directly and also carried by a
-* selected chain is counted once.
-*/
-function selectionResidues(selection, residuesByChain) {
-	var _selection$residues3, _selection$chains3;
-	const residues = new Set((_selection$residues3 = selection.residues) !== null && _selection$residues3 !== void 0 ? _selection$residues3 : []);
-	for (const chainId of (_selection$chains3 = selection.chains) !== null && _selection$chains3 !== void 0 ? _selection$chains3 : []) {
-		var _residuesByChain$get;
-		for (const index of (_residuesByChain$get = residuesByChain.get(chainId)) !== null && _residuesByChain$get !== void 0 ? _residuesByChain$get : []) residues.add(index);
-	}
-	return [...residues].sort((a, b) => a - b);
-}
-/**
-* Names a selection for the legend's readout.
-*
-* A single chain is named as one, since "Chain A" says more than the number of
-* residues it happens to hold. Anything else is reported as a count, which is
-* the only thing true of every shape a selection can take. A lone residue is
-* named by the caller instead, which reads it back off the structure to get its
-* three-letter code and the number the file gives it.
-*/
-function selectionLabel(selection, residueCount) {
-	var _selection$chains4, _selection$residues4;
-	const chains = (_selection$chains4 = selection.chains) !== null && _selection$chains4 !== void 0 ? _selection$chains4 : [];
-	if (chains.length === 1 && !((_selection$residues4 = selection.residues) === null || _selection$residues4 === void 0 ? void 0 : _selection$residues4.length)) return `Chain ${chains[0]}`;
-	return `${residueCount} residues`;
-}
-/** The mean of the values `read` returns, ignoring residues without one. */
-function meanOverResidues(residues, read) {
-	let sum = 0;
-	let count = 0;
-	for (const index of residues) {
-		const value = read(index);
-		if (value === null || value === void 0) continue;
-		sum += value;
-		count++;
-	}
-	return count === 0 ? null : sum / count;
-}
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/residueLoci.ts
-/**
-* Every atom the predicate accepts, as geometry Mol* can focus, frame and mark,
-* or undefined when it accepts none.
-*
-* One pass over the structure rather than a pass per residue: a whole-chain
-* selection names hundreds of residues, and resolving them one at a time would
-* walk the structure once for each.
-*
-* Atoms are bucketed by the unit they belong to because element indices are
-* unit-local. That bucketing is also what lets a result span a chain break: it
-* carries an entry per unit, which is what a range across two chains needs and
-* what a single unit-local entry cannot express.
-*
-* Whole residues are collected rather than one atom each, since the caller
-* frames the camera on the loci's bounding sphere and a lone atom would zoom
-* far closer than the residue warrants.
-*/
-function lociMatching(structure, matches) {
-	const location = StructureElement.Location.create(structure);
-	const elements = [];
-	for (const unit of structure.units) {
-		location.unit = unit;
-		const indices = [];
-		for (let i = 0; i < unit.elements.length; i++) {
-			location.element = unit.elements[i];
-			if (matches(location)) indices.push(i);
-		}
-		if (indices.length > 0) elements.push({
-			indices,
-			unit
-		});
-	}
-	if (elements.length === 0) return void 0;
-	return StructureElement.Loci(structure, elements.map(({ indices, unit }) => ({
-		indices: OrderedSet.ofSortedArray(indices),
-		unit
-	})));
-}
-/**
-* Every atom of the residues a selection covers, within one structure.
-*
-* `hiddenChains` is subtracted from the result. A hidden chain is not drawn, so
-* geometry built from it would have nothing to sit on: Mol*'s focus
-* representation draws its own ball-and-stick from whatever is focused, in a
-* part of the state tree the chain's own visibility does not reach, and a
-* hidden chain left in the loci would keep showing up there after its cartoon
-* had gone.
-*/
-function lociForSelectionInStructure(structure, selection, hiddenChains) {
-	var _selection$residues, _selection$chains;
-	if (isEmptySelection(selection)) return void 0;
-	const residues = new Set((_selection$residues = selection.residues) !== null && _selection$residues !== void 0 ? _selection$residues : []);
-	const chains = new Set((_selection$chains = selection.chains) !== null && _selection$chains !== void 0 ? _selection$chains : []);
-	return lociMatching(structure, (location) => {
-		const chainId = StructureProperties.chain.auth_asym_id(location);
-		if (hiddenChains === null || hiddenChains === void 0 ? void 0 : hiddenChains.has(chainId)) return false;
-		return residues.has(StructureProperties.residue.key(location)) || chains.has(chainId);
-	});
-}
-/**
-* Every atom of the residues between two 0-based indices, inclusive.
-*
-* A contiguous span is tested by comparison rather than by expanding it into a
-* set of indices: this runs on every residue a drag crosses, and a drag can
-* span the whole structure.
-*/
-function lociForResidueRange(structure, min, max) {
-	return lociMatching(structure, (location) => {
-		const index = StructureProperties.residue.key(location);
-		return index >= min && index <= max;
-	});
-}
-/**
-* The same, across every structure loaded into a plugin. Results are merged
-* into the first structure that matched: a loci belongs to one structure, and
-* the residue index space already spans them as though they were one.
-*/
-function lociForSelection(plugin, selection, hiddenChains) {
-	for (const entry of plugin.managers.structure.hierarchy.current.structures) {
-		var _entry$cell$obj;
-		const structure = (_entry$cell$obj = entry.cell.obj) === null || _entry$cell$obj === void 0 ? void 0 : _entry$cell$obj.data;
-		if (!structure) continue;
-		const loci = lociForSelectionInStructure(structure, selection, hiddenChains);
-		if (loci) return loci;
-	}
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/utils/residueRef.ts
 /**
 * Reads the residue a loci points at, or null when it points at nothing the
@@ -2458,138 +2320,6 @@ function createSequenceView(viewSettings) {
 	};
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/axes.ts
-/**
-* The orientation axes widget, as Mol* parameterizes it.
-*
-* Shared rather than declared where it is used, because two different parts of
-* Mol* take the same shape: the live canvas takes it as
-* `camera.helper.axes`, and the screenshot helper takes it as its own `axes`,
-* so an image can carry the widget or leave it out independently of the view
-* it was captured from.
-*/
-const AXES_ON = {
-	name: "on",
-	params: {
-		alpha: .51,
-		colorX: 16711680,
-		colorY: 32768,
-		colorZ: 255,
-		labelColorX: 8421504,
-		labelColorY: 8421504,
-		labelColorZ: 8421504,
-		labelOpacity: 1,
-		labelScale: .25,
-		labelX: "X",
-		labelY: "Y",
-		labelZ: "Z",
-		location: "bottom-left",
-		locationOffsetX: 0,
-		locationOffsetY: 0,
-		originColor: 8421504,
-		planeColorXY: 8421504,
-		planeColorXZ: 8421504,
-		planeColorYZ: 8421504,
-		radiusScale: .075,
-		scale: .15,
-		showLabels: false,
-		showPlanes: true
-	}
-};
-const AXES_OFF = {
-	name: "off",
-	params: {}
-};
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/color.ts
-/** Parses `#RRGGBB` (or `RRGGBB`) into a Mol* `Color`. */
-function parseHexColor(hex) {
-	const h = hex.replace("#", "");
-	return Color.fromRgb(parseInt(h.substring(0, 2), 16), parseInt(h.substring(2, 4), 16), parseInt(h.substring(4, 6), 16));
-}
-/**
-* Parses a theme color into a Mol* `Color`, falling back when the token is
-* missing or is a format Mol* cannot consume (theme values are hex in practice,
-* but the palette types allow any CSS color string).
-*/
-function themeColor(value, fallback) {
-	const candidate = value === null || value === void 0 ? void 0 : value.trim();
-	return parseHexColor(candidate !== void 0 && /^#?[0-9a-f]{6}$/i.test(candidate) ? candidate : fallback);
-}
-/**
-* Neutral fill for residues with no overlay value. Sits between the light and
-* dark backgrounds so unhighlighted geometry stays legible in both modes.
-*/
-function neutralResidueColor(mode) {
-	const g = mode === "dark" ? 100 : 180;
-	return Color.fromRgb(g, g, g);
-}
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/screenshot.ts
-/**
-* Each resolution as the Mol* preset that produces it: 1280x720, 1920x1080,
-* 3840x2160, 7680x4320. Named here rather than given as dimensions so the
-* aspect stays Mol*'s to choose.
-*
-* Mol*'s own `viewport` preset - the canvas at its current size - is left out
-* deliberately: it makes the image depend on how big the viewer happens to be
-* on screen, which is not something a caller asking for "high" is asking for.
-*/
-const RESOLUTION_PRESETS = {
-	high: "ultra-hd",
-	low: "hd",
-	maximum: "8k-ultra-hd",
-	medium: "full-hd"
-};
-/** Painted behind the structure when a background is asked for but unreadable. */
-const FALLBACK_BACKGROUND = "#ffffff";
-/**
-* Downloads the structure as a PNG.
-*
-* Mol*'s screenshot helper renders its own pass rather than reading the canvas
-* back, so the image is drawn fresh at the requested size and carries its own
-* transparency and axes settings - none of which disturb the view on screen.
-*
-* A named background is the one exception. The helper only chooses between
-* transparent and whatever the renderer is already painting, so a color has to
-* be put on the canvas for the length of the capture and taken off afterwards.
-* `finally` is what guarantees the second half: leaving a figure's background
-* behind on the viewer would be a worse bug than a failed download.
-*/
-function downloadStructureImage(_x) {
-	return _downloadStructureImage.apply(this, arguments);
-}
-function _downloadStructureImage() {
-	_downloadStructureImage = _asyncToGenerator(function* (plugin, options = {}) {
-		const helper = plugin.helpers.viewportScreenshot;
-		if (!helper) return;
-		const { backgroundColor, filename, resolution = "medium", showAxes } = options;
-		const transparent = backgroundColor === void 0;
-		helper.behaviors.values.next(_objectSpread2(_objectSpread2({}, helper.behaviors.values.value), {}, {
-			axes: showAxes ? AXES_ON : AXES_OFF,
-			format: {
-				name: "png",
-				params: {}
-			},
-			resolution: {
-				name: RESOLUTION_PRESETS[resolution],
-				params: {}
-			},
-			transparent
-		}));
-		const canvas3d = plugin.canvas3d;
-		const painted = canvas3d === null || canvas3d === void 0 ? void 0 : canvas3d.props.renderer.backgroundColor;
-		const overrideBackground = !transparent && canvas3d !== void 0;
-		if (overrideBackground) canvas3d === null || canvas3d === void 0 || canvas3d.setProps({ renderer: { backgroundColor: themeColor(backgroundColor, FALLBACK_BACKGROUND) } });
-		try {
-			yield helper.download(filename);
-		} finally {
-			if (overrideBackground && painted !== void 0) canvas3d === null || canvas3d === void 0 || canvas3d.setProps({ renderer: { backgroundColor: painted } });
-		}
-	});
-	return _downloadStructureImage.apply(this, arguments);
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/components/Viewport/constants.ts
 /**
 * Fraction of the bounding sphere radius within which the camera still counts
@@ -2752,6 +2482,11 @@ function createViewportView(viewSettings) {
 			return (_s$showAxes = s.showAxes) !== null && _s$showAxes !== void 0 ? _s$showAxes : true;
 		});
 		const download = useViewSetting(viewSettings, (s) => s.download);
+		const onError = useViewSetting(viewSettings, (s) => s.onError);
+		const sceneBusy = useViewSetting(viewSettings, (s) => {
+			var _s$sceneBusy;
+			return (_s$sceneBusy = s.sceneBusy) !== null && _s$sceneBusy !== void 0 ? _s$sceneBusy : false;
+		});
 		/**
 		* Disabled while a capture is in flight. A high resolution takes long
 		* enough to click twice through, and each click renders its own pass.
@@ -2761,13 +2496,18 @@ function createViewportView(viewSettings) {
 			if (!download) return;
 			setDownloading(true);
 			try {
-				yield downloadStructureImage(plugin, download);
+				yield exportStructureImage(plugin, download);
 			} catch (error) {
-				console.error("Failed to download the structure image:", error);
+				if (onError) onError(error, "capture");
+				else console.error("Failed to download the structure image:", error);
 			} finally {
 				setDownloading(false);
 			}
-		}), [download, plugin]);
+		}), [
+			download,
+			onError,
+			plugin
+		]);
 		return /* @__PURE__ */ jsxs(Fragment$1, { children: [
 			/* @__PURE__ */ jsx(Viewport, {}),
 			/* @__PURE__ */ jsx("div", {
@@ -2801,7 +2541,7 @@ function createViewportView(viewSettings) {
 						textAlign: "left",
 						children: /* @__PURE__ */ jsx(Button, {
 							"aria-label": "Download image of the structure",
-							disabled: downloading,
+							disabled: downloading || sceneBusy,
 							onClick: captureImage,
 							sdsStyle: "minimal",
 							sdsType: "secondary",
@@ -2908,150 +2648,6 @@ function syncClipToZoom(plugin, getClipRatio) {
 	}
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/chains.ts
-/**
-* The polymer of one chain, as named in the file. What each chain's cartoon is
-* built from, and so what makes a chain a thing Mol* can hide on its own.
-*
-* Paired with `chainLigandExpression`: between them they cover everything on a
-* chain the viewer draws, split by what it draws it as. The polymer
-* restriction is the one Mol*'s `polymer-cartoon` preset applied, and is what
-* keeps a heme from being handed to a representation that can only trace a
-* backbone.
-*/
-function chainPolymerExpression(chainId) {
-	return MolScriptBuilder.struct.generator.atomGroups({
-		"chain-test": MolScriptBuilder.core.rel.eq([MolScriptBuilder.ammp("auth_asym_id"), chainId]),
-		"entity-test": MolScriptBuilder.core.rel.eq([MolScriptBuilder.ammp("entityType"), "polymer"])
-	});
-}
-/**
-* Bonds worth following out of a ligand: the ones holding it to the protein.
-*
-* Mol*'s own pair, and metallic coordination is the half that matters most -
-* a heme's iron is held to its histidine by a coordination bond and not a
-* covalent one, so covalent alone would leave every metalloprotein's cofactor
-* looking dropped in rather than bound.
-*/
-const CONNECTING_BOND = MolScriptBuilder.core.flags.hasAny([MolScriptBuilder.struct.bondProperty.flags(), MolScriptBuilder.core.type.bitflags([BondType.fromNames(["covalent", "metal-coordination"])])]);
-/**
-* The heteroatoms of one chain - ligands, ions, glycans, lipids - along with
-* the residues holding them, which is what its ball-and-stick is built from.
-*
-* `non-polymer` is the one entity type a PDB's HETATM records land under,
-* ligands and ions alike, so there is nothing finer to test here: the
-* distinction Mol*'s presets draw between their `ligand`, `ion` and `lipid`
-* components is a residue-name lookup made to give each a slightly different
-* style, and all three are sticks. `branched` is the separate type glycans
-* arrive as.
-*
-* Water is the third type and is left out of the seed. Every solvent molecule
-* drawn as sticks buries the structure they surround, which is why Mol* draws
-* them at 60% alpha rather than plain, and none of them is what "show the
-* ligands" asks for.
-*
-* One layer of bonds out from there, taken as whole residues, is what brings
-* the binding residue along - myoglobin's His93, say. Without it the heme
-* floats unattached in the middle of a cartoon it is visibly bonded to, and
-* the bond drawn to its iron ends in mid-air. One layer and no more: the
-* residue that holds the ligand, not that residue's own neighbours.
-*
-* Intersected back with the chain, so everything a chain is drawn with belongs
-* to that chain. A ligand bonded across an interface would otherwise leave the
-* partner chain's residue in this chain's component, somewhere hiding the
-* partner chain could not reach.
-*/
-function chainLigandExpression(chainId) {
-	const onThisChain = MolScriptBuilder.core.rel.eq([MolScriptBuilder.ammp("auth_asym_id"), chainId]);
-	return MolScriptBuilder.struct.modifier.union([MolScriptBuilder.struct.modifier.intersectBy({
-		0: MolScriptBuilder.struct.modifier.includeConnected({
-			0: MolScriptBuilder.struct.generator.atomGroups({
-				"chain-test": onThisChain,
-				"entity-test": MolScriptBuilder.core.set.has([MolScriptBuilder.set("non-polymer", "branched"), MolScriptBuilder.ammp("entityType")])
-			}),
-			"as-whole-residues": true,
-			"bond-test": CONNECTING_BOND,
-			"layer-count": 1
-		}),
-		by: MolScriptBuilder.struct.generator.atomGroups({ "chain-test": onThisChain })
-	})]);
-}
-/**
-* Matches how the sequence panel captions its chains, which reaches the same
-* label through Mol*'s own `getChainOptions`. Deriving it the same way is what
-* keeps a chain from going by one name in the legend and another in the panel.
-*/
-const CHAIN_LABEL_OPTIONS = {
-	granularity: "chain",
-	hidePrefix: true,
-	htmlStyling: false
-};
-/**
-* Reads the chains of a structure and the polymer residues on each.
-*
-* Residue indices are Mol*'s residue keys, counting residues in file order
-* across the whole structure, so what is reported here addresses the same
-* residues as `plddt`, `residueOverlay` and `selection`.
-*
-* Heteroatoms are drawn (see `chainLigandExpression`) but are not counted
-* here. A heme is a residue to the file and not to a reader: it is no part of
-* the sequence the panel lists, and averaging a confidence score over it would
-* divide by a residue that has none.
-*
-* Residues are gathered into a set rather than inferred from the ends: a chain
-* carrying several symmetry operators repeats each of its residues once per
-* operator, and a structure whose chains interleave leaves a chain's indices
-* non-contiguous. Neither is what a predicted complex looks like, but a range
-* would misread both.
-*/
-function scanChains(structure) {
-	const accumulators = /* @__PURE__ */ new Map();
-	const location = StructureElement.Location.create(structure);
-	for (const unit of structure.units) {
-		location.unit = unit;
-		for (let i = 0; i < unit.elements.length; i++) {
-			location.element = unit.elements[i];
-			const chainId = StructureProperties.chain.auth_asym_id(location);
-			let chain = accumulators.get(chainId);
-			if (!chain) {
-				chain = {
-					chainId,
-					label: elementLabel(location, CHAIN_LABEL_OPTIONS),
-					residues: /* @__PURE__ */ new Set()
-				};
-				accumulators.set(chainId, chain);
-			}
-			if (StructureProperties.entity.type(location) !== "polymer") continue;
-			chain.residues.add(StructureProperties.residue.key(location));
-		}
-	}
-	const ordered = [...accumulators.values()].filter((chain) => chain.residues.size > 0).map((chain) => _objectSpread2(_objectSpread2({}, chain), {}, { residues: [...chain.residues].sort((a, b) => a - b) })).sort((a, b) => {
-		var _a$residues$, _b$residues$;
-		return ((_a$residues$ = a.residues[0]) !== null && _a$residues$ !== void 0 ? _a$residues$ : 0) - ((_b$residues$ = b.residues[0]) !== null && _b$residues$ !== void 0 ? _b$residues$ : 0);
-	});
-	return {
-		chainLabels: new Map([...accumulators.values()].map(({ chainId, label }) => [chainId, label])),
-		chains: ordered.map(({ chainId, label, residues }) => {
-			var _residues, _residues$;
-			return {
-				chainId,
-				endIndex: (_residues = residues[residues.length - 1]) !== null && _residues !== void 0 ? _residues : 0,
-				label,
-				residueCount: residues.length,
-				startIndex: (_residues$ = residues[0]) !== null && _residues$ !== void 0 ? _residues$ : 0
-			};
-		}),
-		residuesByChain: new Map(ordered.map(({ chainId, residues }) => [chainId, residues]))
-	};
-}
-/** True when the two lists name the same chains, in the same order. */
-function chainsEqual(a, b) {
-	return a.length === b.length && a.every((chain, i) => {
-		const other = b[i];
-		return other !== void 0 && chain.chainId === other.chainId && chain.startIndex === other.startIndex && chain.endIndex === other.endIndex && chain.residueCount === other.residueCount;
-	});
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/utils/molstarSpec.ts
 /**
 * The spec's list-valued keys. These are appended rather than merged: Mol*
@@ -3119,421 +2715,16 @@ function mergeMolstarSpec(base, override) {
 	return merged;
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/structureFormat.ts
-/** How much of the file to inspect when guessing the format. */
-const DETECT_SAMPLE = 16384;
-/**
-* Infers whether `text` is PDB or mmCIF (PDBx).
-*
-* mmCIF documents start with a `data_` block and name their coordinates
-* `_atom_site.`. PDB never does either, so either marker is enough. A leading
-* comment (`# ...`) before `data_` is still mmCIF.
-*/
-function detectStructureFormat(text) {
-	const sample = text.slice(0, DETECT_SAMPLE);
-	if (/(?:^|\n)\s*data_/.test(sample) || /_atom_site\./.test(sample)) return "mmcif";
-	return "pdb";
-}
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/chainColorTheme.ts
-/** Mol* color theme name under which per-chain coloring is registered. */
-const CHAIN_COLOR_THEME_NAME = "chain-color";
-/** Painted for a chain with no color assigned, or one assigned a bad value. */
-const DEFAULT_CHAIN_COLOR_HEX = "#808080";
-const DEFAULT_CHAIN_COLOR = Color.fromRgb(128, 128, 128);
-/**
-* Builds a Mol* color theme that paints each chain its own color.
-*
-* This stands in for Mol*'s built-in `chain-id` theme, which picks its own
-* colors from a palette we cannot read back. Owning the assignment is what
-* lets the chain legend show a swatch that matches the structure, rather than
-* a key for colors it has to guess at.
-*
-* Created per plugin instance, and its state read live inside `color()`, for
-* the same reasons as the residue value theme beside it: several viewers can
-* color chains differently on one page, and recoloring does not rebuild the
-* structure.
-*/
-function createChainColorTheme() {
-	const state = {
-		colors: /* @__PURE__ */ new Map(),
-		version: 0
-	};
-	const provider = {
-		category: "chain property",
-		defaultValues: {},
-		factory() {
-			const { colors } = state;
-			const parsed = /* @__PURE__ */ new Map();
-			for (const [chainId, hex] of colors) parsed.set(chainId, themeColor(hex, DEFAULT_CHAIN_COLOR_HEX));
-			return {
-				color(location) {
-					var _parsed$get;
-					if (!StructureElement.Location.is(location)) return DEFAULT_CHAIN_COLOR;
-					const chainId = StructureProperties.chain.auth_asym_id(location);
-					return (_parsed$get = parsed.get(chainId)) !== null && _parsed$get !== void 0 ? _parsed$get : DEFAULT_CHAIN_COLOR;
-				},
-				contextHash: state.version,
-				description: "Color residues by the chain they sit on",
-				factory: provider.factory,
-				granularity: "group",
-				props: {}
-			};
-		},
-		getParams: () => ({}),
-		isApplicable: () => true,
-		label: "Chain Color",
-		name: CHAIN_COLOR_THEME_NAME
-	};
-	return {
-		provider,
-		setState(colors) {
-			state.colors = colors;
-			state.version++;
-		}
-	};
-}
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/plddt.ts
-/** Mol* color theme name under which pLDDT coloring is registered. */
-const PLDDT_THEME_NAME = "plddt-bfactor";
-/**
-* AlphaFold's pLDDT confidence bands. Thresholds are on the 0-1 scale that
-* `plddt` values use, ascending from lowest to highest confidence.
-*/
-const PLDDT_COLOR_SCALE = {
-	kind: "stepped",
-	stops: [
-		{
-			color: "#FF7C45",
-			label: "0.5",
-			threshold: .5
-		},
-		{
-			color: "#FFDB11",
-			label: "0.7",
-			threshold: .7
-		},
-		{
-			color: "#64CBF3",
-			label: "0.9",
-			threshold: .9
-		},
-		{
-			color: "#0053D5",
-			label: "1.0",
-			threshold: 1
-		}
-	]
-};
-const PLDDT_BANDS = PLDDT_COLOR_SCALE.kind === "stepped" ? PLDDT_COLOR_SCALE.stops : [];
-/**
-* The band colors alone, ascending from least to most confident.
-*
-* What the chain legend shows in place of a single color while pLDDT is
-* painting the structure: no one color stands for a chain then, so the swatch
-* carries the whole key instead.
-*/
-const PLDDT_BAND_COLORS = PLDDT_BANDS.map((stop) => stop.color);
-const DEFAULT_PLDDT_COLOR = Color.fromRgb(128, 128, 128);
-/**
-* Maps a pLDDT confidence score on the 0-100 B-factor scale to its band color.
-* `PLDDT_COLOR_SCALE` thresholds are on the 0-1 scale, so the score is
-* normalized before it is sampled.
-*/
-function plddtToColor(value) {
-	const [r, g, b] = sampleSteppedScale(PLDDT_BANDS, value / 100);
-	return Color.fromRgb(r, g, b);
-}
-/**
-* Rewrites a PDB file's B-factor column with pLDDT scores so Mol* can read them
-* off the parsed model. B-factors occupy columns 60-66 of ATOM/HETATM lines;
-* scores arrive on a 0-1 scale and are stored on the conventional 0-100 one.
-* Residues past the end of `plddtValues` fall back to a mid-confidence 50.
-*
-* A residue is identified by chain, sequence number and insertion code. The
-* code has to be part of that: `10` and `10A` are two residues, Mol* counts
-* them as two, and treating them as one here would hand every residue after
-* them its neighbour's score.
-*/
-function injectPlddtIntoPdb(pdbData, plddtValues) {
-	const lines = pdbData.split("\n");
-	let residueIndex = -1;
-	let lastResidue = "";
-	return lines.map((line) => {
-		var _plddtValues$residueI;
-		if (!line.startsWith("ATOM") && !line.startsWith("HETATM")) return line;
-		const residue = line.substring(21, 27);
-		if (residue !== lastResidue) {
-			residueIndex++;
-			lastResidue = residue;
-		}
-		const bfactorStr = (residueIndex < plddtValues.length ? ((_plddtValues$residueI = plddtValues[residueIndex]) !== null && _plddtValues$residueI !== void 0 ? _plddtValues$residueI : 0) * 100 : 50).toFixed(2).padStart(6, " ");
-		const paddedLine = line.padEnd(66, " ");
-		return paddedLine.substring(0, 60) + bfactorStr + paddedLine.substring(66);
-	}).join("\n");
-}
-const ATOM_SITE_PREFIX = "_atom_site.";
-const B_FACTOR_COLUMN = "B_iso_or_equiv";
-function skipCifWhitespace(line, index) {
-	let i = index;
-	while (i < line.length && /\s/.test(line.charAt(i))) i += 1;
-	return i;
-}
-function readCifToken(line, start) {
-	const quote = line.charAt(start);
-	if (quote === "'" || quote === "\"") {
-		const end = line.indexOf(quote, start + 1);
-		if (end < 0) return {
-			next: line.length,
-			token: line.slice(start + 1)
-		};
-		return {
-			next: end + 1,
-			token: line.slice(start + 1, end)
-		};
-	}
-	let i = start;
-	while (i < line.length && !/\s/.test(line.charAt(i))) i += 1;
-	return {
-		next: i,
-		token: line.slice(start, i)
-	};
-}
-/**
-* Splits one CIF line into tokens, honouring `'quoted'` and `"quoted"` values.
-* Atom-site rows are one line each in practice; multiline `;text;` fields are
-* not used there and are not handled.
-*/
-function tokenizeCifLine(line) {
-	const tokens = [];
-	let i = skipCifWhitespace(line, 0);
-	while (i < line.length) {
-		const { next, token } = readCifToken(line, i);
-		tokens.push(token);
-		i = skipCifWhitespace(line, next);
-	}
-	return tokens;
-}
-function isCifNull(value) {
-	return value === void 0 || value === "." || value === "?";
-}
-function columnIndex(columns, name) {
-	return columns.indexOf(name);
-}
-/**
-* Residue identity matching `injectPlddtIntoPdb`: chain + sequence number +
-* insertion code. Prefers the `auth_*` columns Mol* reports on the parsed
-* model, falling back to `label_*` when a file omitted them. `.` / `?`
-* insertion codes count as empty, the way a blank PDB column 27 does.
-*/
-function mmcifResidueKey(tokens, columns) {
-	var _ref, _ref2, _ref3, _ref4;
-	const authAsym = columnIndex(columns, "auth_asym_id");
-	const labelAsym = columnIndex(columns, "label_asym_id");
-	const authSeq = columnIndex(columns, "auth_seq_id");
-	const labelSeq = columnIndex(columns, "label_seq_id");
-	const ins = columnIndex(columns, "pdbx_PDB_ins_code");
-	return `${(_ref = (_ref2 = authAsym >= 0 ? tokens[authAsym] : void 0) !== null && _ref2 !== void 0 ? _ref2 : labelAsym >= 0 ? tokens[labelAsym] : void 0) !== null && _ref !== void 0 ? _ref : ""}|${(_ref3 = (_ref4 = authSeq >= 0 ? tokens[authSeq] : void 0) !== null && _ref4 !== void 0 ? _ref4 : labelSeq >= 0 ? tokens[labelSeq] : void 0) !== null && _ref3 !== void 0 ? _ref3 : ""}|${isCifNull(ins >= 0 ? tokens[ins] : void 0) ? "" : tokens[ins]}`;
-}
-function isAtomSiteRow(tokens, columns) {
-	const group = columnIndex(columns, "group_PDB");
-	if (group < 0) return true;
-	const value = tokens[group];
-	return value === "ATOM" || value === "HETATM";
-}
-function plddtBFactor(residueIndex, plddtValues) {
-	var _plddtValues$residueI2;
-	return (residueIndex < plddtValues.length ? ((_plddtValues$residueI2 = plddtValues[residueIndex]) !== null && _plddtValues$residueI2 !== void 0 ? _plddtValues$residueI2 : 0) * 100 : 50).toFixed(2);
-}
-function isLoopStart(line) {
-	return line.trim() === "loop_" || line.trim().startsWith("loop_");
-}
-function isAtomSiteColumn(line) {
-	return line.trim().startsWith(ATOM_SITE_PREFIX);
-}
-function endsAtomSiteLoop(line) {
-	const trimmed = line.trim();
-	if (trimmed === "") return false;
-	if (trimmed.startsWith("#")) return true;
-	if (isLoopStart(trimmed)) return true;
-	if (trimmed.startsWith("data_") || trimmed.startsWith("save_")) return true;
-	return trimmed.startsWith("_") && !trimmed.startsWith(ATOM_SITE_PREFIX);
-}
-function isAtomSiteLoop(lines, loopIndex) {
-	let peek = loopIndex + 1;
-	while (peek < lines.length && lines[peek].trim() === "") peek += 1;
-	return peek < lines.length && isAtomSiteColumn(lines[peek]);
-}
-function ensureBFactorColumn(columns, headerLines) {
-	const existing = columnIndex(columns, B_FACTOR_COLUMN);
-	if (existing >= 0) return existing;
-	columns.push(B_FACTOR_COLUMN);
-	headerLines.push(`${ATOM_SITE_PREFIX}${B_FACTOR_COLUMN}`);
-	return columns.length - 1;
-}
-function rewriteAtomSiteRow(dataLine, columns, bIndex, plddtValues, walk) {
-	if (dataLine.trim() === "") return dataLine;
-	const tokens = tokenizeCifLine(dataLine);
-	if (tokens.length === 0) return dataLine;
-	while (tokens.length < columns.length) tokens.push(".");
-	if (isAtomSiteRow(tokens, columns)) {
-		const residue = mmcifResidueKey(tokens, columns);
-		if (residue !== walk.lastResidue) {
-			walk.residueIndex += 1;
-			walk.lastResidue = residue;
-		}
-		tokens[bIndex] = plddtBFactor(walk.residueIndex, plddtValues);
-	}
-	return tokens.join(" ");
-}
-function rewriteAtomSiteLoop(lines, loopIndex, plddtValues, walk) {
-	const rows = [lines[loopIndex]];
-	let i = loopIndex + 1;
-	const columns = [];
-	while (i < lines.length && isAtomSiteColumn(lines[i])) {
-		columns.push(lines[i].trim().slice(11));
-		rows.push(lines[i]);
-		i += 1;
-	}
-	const bIndex = ensureBFactorColumn(columns, rows);
-	while (i < lines.length && !endsAtomSiteLoop(lines[i])) {
-		rows.push(rewriteAtomSiteRow(lines[i], columns, bIndex, plddtValues, walk));
-		i += 1;
-	}
-	return {
-		next: i,
-		rows
-	};
-}
-/**
-* Rewrites an mmCIF (PDBx) file's `_atom_site.B_iso_or_equiv` column with
-* pLDDT scores so Mol* can read them off the parsed model, the same way
-* `injectPlddtIntoPdb` rewrites the PDB B-factor column. Scores arrive on a
-* 0-1 scale and are stored on the conventional 0-100 one. Residues past the
-* end of `plddtValues` fall back to a mid-confidence 50.
-*
-* If the file has no B-factor column, one is appended to the atom-site loop
-* rather than leaving the scores behind.
-*/
-function injectPlddtIntoMmcif(mmcifData, plddtValues) {
-	const lines = mmcifData.split("\n");
-	const result = [];
-	const walk = {
-		lastResidue: "",
-		residueIndex: -1
-	};
-	let i = 0;
-	let rewrittenLoop = false;
-	while (i < lines.length) {
-		const line = lines[i];
-		if (!rewrittenLoop && isLoopStart(line) && isAtomSiteLoop(lines, i)) {
-			const rewritten = rewriteAtomSiteLoop(lines, i, plddtValues, walk);
-			result.push(...rewritten.rows);
-			i = rewritten.next;
-			rewrittenLoop = true;
-			continue;
-		}
-		result.push(line);
-		i += 1;
-	}
-	return result.join("\n");
-}
-/**
-* Rewrites a structure file's B-factors with pLDDT scores. Dispatches to
-* `injectPlddtIntoPdb` or `injectPlddtIntoMmcif` from `format`, or from
-* detecting the format of `data` when `format` is omitted.
-*/
-function injectPlddt(data, plddtValues, format = detectStructureFormat(data)) {
-	return format === "mmcif" ? injectPlddtIntoMmcif(data, plddtValues) : injectPlddtIntoPdb(data, plddtValues);
-}
-/**
-* Mol* color theme that reads pLDDT scores out of the B-factor column, paired
-* with `injectPlddt`. Registered per plugin instance.
-*/
-const PlddtColoring = CustomElementProperty.create({
-	coloring: {
-		defaultColor: DEFAULT_PLDDT_COLOR,
-		getColor(e) {
-			return plddtToColor(e);
-		}
-	},
-	getData(model) {
-		const map = /* @__PURE__ */ new Map();
-		const atomCount = model.atomicHierarchy.atoms._rowCount;
-		for (let i = 0; i < atomCount; i++) map.set(i, model.atomicConformation.B_iso_or_equiv.value(i));
-		return { value: map };
-	},
-	label: "pLDDT",
-	name: PLDDT_THEME_NAME
-});
-//#endregion
-//#region src/core/ProteinStructureViewer/utils/residueValueTheme.ts
-/** Mol* color theme name under which residue value overlays are registered. */
-const RESIDUE_VALUE_THEME_NAME = "residue-value";
-/**
-* Builds a Mol* color theme that paints residues by an arbitrary per-residue
-* value.
-*
-* The theme is created per plugin instance rather than shared at module scope,
-* so several viewers can render different overlays on the same page. Its state
-* lives in the closure below and is read live inside `color()`, which is what
-* lets an overlay update recolor the structure without rebuilding it.
-*/
-function createResidueValueTheme(mode) {
-	const state = {
-		colorScale: PLASMA_COLOR_SCALE,
-		max: 1,
-		min: 0,
-		mode,
-		values: /* @__PURE__ */ new Map(),
-		version: 0
-	};
-	const provider = {
-		category: "residue property",
-		defaultValues: {},
-		factory() {
-			const { colorScale, max, min, mode: currentMode, values } = state;
-			const neutral = neutralResidueColor(currentMode);
-			return {
-				color(location) {
-					if (!StructureElement.Location.is(location)) return neutral;
-					const value = values.get(StructureProperties.residue.key(location));
-					if (value === void 0) return neutral;
-					const rgb = sampleColorScale(colorScale, value, max, min);
-					return rgb ? Color.fromRgb(rgb[0], rgb[1], rgb[2]) : neutral;
-				},
-				contextHash: state.version,
-				description: "Color residues by a per-residue value",
-				factory: provider.factory,
-				granularity: "group",
-				props: {}
-			};
-		},
-		getParams: () => ({}),
-		isApplicable: () => true,
-		label: "Residue Value",
-		name: RESIDUE_VALUE_THEME_NAME
-	};
-	return {
-		provider,
-		setState(next) {
-			Object.assign(state, next);
-			state.version++;
-		}
-	};
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/hooks/useMolstarPlugin.ts
-/**
-* Theme used when neither pLDDT scores nor an overlay are supplied. Our own
-* per-chain theme rather than Mol*'s built-in `chain-id`, so the chain legend
-* can show swatches that match the structure instead of guessing at the colors
-* Mol* picked.
-*/
-const FALLBACK_THEME_NAME = CHAIN_COLOR_THEME_NAME;
 /** Delay before retrying initialization while the container has no size. */
 const LAYOUT_RETRY_MS = 100;
+/** What the viewer logs for a failure when no `onError` is listening. */
+const UNHANDLED_ERROR_MESSAGES = {
+	capture: "Failed to download the structure image:",
+	init: "Failed to initialize Mol* viewer:",
+	load: "Failed to load structure:",
+	representation: "Failed to draw the structure:"
+};
 /** How long to wait for a frame before starting without one. */
 const FRAME_WAIT_MS = 100;
 /**
@@ -3593,7 +2784,7 @@ function createViewer(_x) {
 	return _createViewer.apply(this, arguments);
 }
 function _createViewer() {
-	_createViewer = _asyncToGenerator(function* ({ backgroundColor, chainColorTheme, edgeColor, highlightColor, molstarSpec, residueValueTheme, root, showAxes, showSequenceViewer, viewSettings }) {
+	_createViewer = _asyncToGenerator(function* ({ backgroundColor, edgeColor, highlightColor, molstarSpec, root, showAxes, showSequenceViewer, viewSettings }) {
 		var _spec$config;
 		const spec = DefaultPluginUISpec();
 		const behaviors = spec.behaviors.filter((b) => b.transformer !== PluginBehaviors.Camera.FocusLoci);
@@ -3648,10 +2839,6 @@ function _createViewer() {
 			}), molstarSpec),
 			target: root
 		});
-		const registry = plugin.representation.structure.themes.colorThemeRegistry;
-		if (PlddtColoring.colorThemeProvider) registry.add(PlddtColoring.colorThemeProvider);
-		registry.add(residueValueTheme.provider);
-		registry.add(chainColorTheme.provider);
 		for (const p of [...plugin.managers.lociLabels.providers]) plugin.managers.lociLabels.removeProvider(p);
 		plugin.managers.structure.focus.behaviors.current.subscribe((entry) => {
 			const select = plugin.managers.interactivity.lociSelects;
@@ -3663,232 +2850,59 @@ function _createViewer() {
 	return _createViewer.apply(this, arguments);
 }
 /**
-* The representation parameters Mol*'s own presets compute, read from the same
-* manager state they read. Ported rather than hardcoded so a chain drawn here
-* looks exactly like the one the preset used to draw. Mol* hands the same set
-* to its cartoons and its ball-and-sticks, and so does this.
-*/
-function representationTypeParams(plugin) {
-	const { hydrogens, ignoreLight, visualQuality } = plugin.managers.structure.component.state.options;
-	return {
-		ignoreHydrogens: hydrogens !== "all",
-		ignoreHydrogensVariant: hydrogens === "only-polar" ? "non-polar" : "all",
-		ignoreLight,
-		quality: visualQuality
-	};
-}
-/**
-* The two halves of a chain the viewer draws. Each names the component its
-* half is built under and tags the representation drawn over it, and it is
-* that tag `applyColorTheme` reads back to tell the two apart.
-*/
-const POLYMER_PART = "polymer";
-const LIGAND_PART = "ligand";
-/**
-* True for the representation drawing a chain's heteroatoms.
-*
-* Read off the tag put on the representation when it was built, rather than
-* off the component's key. Mol* does not store the key as it was given: it
-* files components under `structure-component-<key>`, so a test against the
-* key as written here silently matches nothing, and every ligand quietly takes
-* the structure-wide theme instead. The tag survives untouched.
-*/
-function isLigandRepresentation(representation) {
-	var _representation$cell$;
-	return ((_representation$cell$ = representation.cell.transform.tags) === null || _representation$cell$ === void 0 ? void 0 : _representation$cell$.includes(LIGAND_PART)) === true;
-}
-/**
-* How heteroatoms are colored: the theme Mol* puts on a ball-and-stick when
-* left to itself, with the parameters it chooses too.
-*
-* Named rather than left blank only so that it survives `applyColorTheme`,
-* which would otherwise repaint the ligands along with everything else. The
-* structure-wide theme is the wrong answer for them twice over: a heme reads
-* as a heme because its iron is orange and its nitrogens are blue, which one
-* flat color throws away, and pLDDT and residue overlays have no value for a
-* HETATM to be colored by at all.
-*/
-const ELEMENT_THEME = "element-symbol";
-/**
-* Draws one chain: its polymer as a cartoon, its ligands and ions as
-* ball-and-stick.
-*
-* Two components rather than one, because a component is what a representation
-* attaches to and neither representation suits both halves - a cartoon has no
-* backbone to trace through a heme, and a ball-and-stick over the whole chain
-* would draw every protein atom as a sphere.
-*
-* Hands back the refs of whichever components the chain turned out to have,
-* which is what `setSubtreeVisibility` is later pointed at. Grouping them
-* under the chain is what makes hiding a chain take its ligands with it.
-*/
-function buildChainComponents(_x5, _x6, _x7, _x8) {
-	return _buildChainComponents.apply(this, arguments);
-}
-function _buildChainComponents() {
-	_buildChainComponents = _asyncToGenerator(function* (plugin, structure, chain, typeParams) {
-		const builders = plugin.builders.structure;
-		const refs = [];
-		const addPart = function() {
-			var _ref = _asyncToGenerator(function* (part, expression, props) {
-				const component = yield builders.tryCreateComponentFromExpression(structure, expression, `${part}-${chain.chainId}`, { label: chain.label });
-				if (!component) return;
-				yield builders.representation.addRepresentation(component, props, { tag: part });
-				refs.push(component.ref);
-			});
-			return function addPart(_x2, _x3, _x4) {
-				return _ref.apply(this, arguments);
-			};
-		}();
-		yield addPart(POLYMER_PART, chainPolymerExpression(chain.chainId), {
-			type: "cartoon",
-			typeParams
-		});
-		yield addPart(LIGAND_PART, chainLigandExpression(chain.chainId), {
-			color: ELEMENT_THEME,
-			type: "ball-and-stick",
-			typeParams
-		});
-		return refs;
-	});
-	return _buildChainComponents.apply(this, arguments);
-}
-const NOTHING_LOADED = {
-	chains: [],
-	componentRefs: /* @__PURE__ */ new Map(),
-	residuesByChain: /* @__PURE__ */ new Map()
-};
-/**
-* Parses the structure and draws each chain: a cartoon over its polymer, and
-* ball-and-stick over its ligands and ions.
-*
-* Mol*'s `default` hierarchy preset would be shorter, but it groups every
-* polymer chain into a single component, and a component is the unit Mol* can
-* hide. Building them per chain is what makes a chain individually hideable;
-* the refs handed back are what `setSubtreeVisibility` is later pointed at.
-*
-* The wrapper detects PDB vs mmCIF from the text; this just forwards that
-* guess to Mol*.
-*/
-function loadStructure(_x9, _x10, _x11, _x12) {
-	return _loadStructure.apply(this, arguments);
-}
-function _loadStructure() {
-	_loadStructure = _asyncToGenerator(function* (plugin, structureText, usePlddtColoring, showAxes) {
-		try {
-			var _plugin$canvas3d;
-			yield plugin.clear();
-			const data = yield plugin.builders.data.rawData({
-				data: structureText,
-				label: "Structure"
-			});
-			const trajectory = yield plugin.builders.structure.parseTrajectory(data, detectStructureFormat(structureText));
-			const model = yield plugin.builders.structure.createModel(trajectory);
-			const structure = yield plugin.builders.structure.createStructure(model, {
-				name: "model",
-				params: {}
-			});
-			const data3d = structure.data;
-			if (!data3d) return NOTHING_LOADED;
-			const { chainLabels, chains, residuesByChain } = scanChains(data3d);
-			const typeParams = representationTypeParams(plugin);
-			const componentRefs = /* @__PURE__ */ new Map();
-			for (const [chainId, label] of chainLabels) {
-				const refs = yield buildChainComponents(plugin, structure, {
-					chainId,
-					label
-				}, typeParams);
-				if (refs.length > 0) componentRefs.set(chainId, refs);
-			}
-			if (usePlddtColoring) yield applyColorTheme(plugin, PLDDT_THEME_NAME);
-			(_plugin$canvas3d = plugin.canvas3d) === null || _plugin$canvas3d === void 0 || _plugin$canvas3d.requestCameraReset();
-			setAxes(plugin, showAxes);
-			return {
-				chains,
-				componentRefs,
-				residuesByChain
-			};
-		} catch (error) {
-			console.error("Failed to load structure:", error);
-			return NOTHING_LOADED;
-		}
-	});
-	return _loadStructure.apply(this, arguments);
-}
-/**
-* Shows or hides everything each chain is drawn with, cartoon and sticks
-* alike. Every component under the chain, so hiding it takes its ligands with
-* it rather than leaving a heme floating where its protein used to be.
-*
-* The whole subtree of each, not just the component cell: visibility is
-* per-cell, and it is the representation underneath that actually draws.
-*
-* Set outright rather than through the component manager's `toggleVisibility`,
-* which flips whatever it finds: the hidden set is derived from props on every
-* pass, so it has to be applied as a statement of what should be true and not
-* as a change to what already is.
-*/
-function applyChainVisibility(plugin, componentRefs, hidden) {
-	for (const [chainId, refs] of componentRefs) for (const ref of refs) setSubtreeVisibility(plugin.state.data, ref, hidden.has(chainId));
-}
-/**
-* Recolors every loaded structure's representations with the named theme,
-* leaving the heteroatoms on `ELEMENT_THEME`.
-*
-* The per-representation form of `updateRepresentationsTheme`, so the two can
-* be told apart in one pass; handing it a filtered list instead would leave
-* the ligands on whichever theme happened to be current when they were built.
-*/
-function applyColorTheme(_x13, _x14) {
-	return _applyColorTheme.apply(this, arguments);
-}
-function _applyColorTheme() {
-	_applyColorTheme = _asyncToGenerator(function* (plugin, colorTheme) {
-		yield plugin.dataTransaction(_asyncToGenerator(function* () {
-			for (const s of plugin.managers.structure.hierarchy.current.structures) yield plugin.managers.structure.component.updateRepresentationsTheme(s.components, (_component, representation) => ({ color: isLigandRepresentation(representation) ? ELEMENT_THEME : colorTheme }));
-		}));
-	});
-	return _applyColorTheme.apply(this, arguments);
-}
-/**
 * Owns the Mol* plugin for one viewer: creates it, loads the structure, wires
 * interaction callbacks, and disposes of it on unmount.
 *
 * The plugin is built once and then mutated in place. Creating it is expensive
 * and destroys the camera, so prop changes that Mol* can absorb (background,
-* axes, coloring, new structure) are pushed in through the effects below and in
-* the sibling hooks rather than by rebuilding.
+* axes, coloring, representation, new structure) are pushed in through the
+* effects below and in the sibling hooks rather than by rebuilding.
 */
-function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download, edgeColor, hasPlddt, hiddenChains, highlightColor, mode, molstarSpec, onChainHover, onChainSelect, onChainToggle, onResidueClick, onResidueHover, onSelectionChange, onSelectionClear, selectedChains, sequenceViewerBackgroundColor, showAxes, showSequenceViewer, structure }) {
+function useMolstarPlugin({ backgroundColor, containerRef, download, edgeColor, hiddenChains, highlightColor, mode, molstarSpec, onChainHover, onChainSelect, onChainToggle, onDispose, onError, onReady, onResidueClick, onResidueHover, onSelectionChange, onSelectionClear, onStructureLoad, sceneMode, sceneProps, selectedChains, sequenceViewerBackgroundColor, showAxes, showSequenceViewer, structure }) {
+	var _sceneProps$chainColo;
 	const pluginRef = useRef(null);
-	const residueValueThemeRef = useRef(null);
-	const chainColorThemeRef = useRef(null);
+	const sceneRef = useRef(null);
 	const currentStructureRef = useRef(null);
 	const [isReady, setIsReady] = useState(false);
 	const [chains, setChains] = useState([]);
 	const [loadCount, setLoadCount] = useState(0);
-	/**
-	* Where each chain's components live in the state tree, which is what the
-	* visibility effect points `setSubtreeVisibility` at. Rewritten by every
-	* load, since the refs do not survive `plugin.clear()`.
-	*/
-	const componentRefsRef = useRef(/* @__PURE__ */ new Map());
+	const [sceneVersion, setSceneVersion] = useState(0);
+	const [sceneBusy, setSceneBusy] = useState(false);
 	/**
 	* Which residues sit on each chain, for the readout to average a score over
 	* a whole-chain selection. A ref rather than state: nothing renders from it
 	* directly, and it is rewritten in step with `chains`, which does.
 	*/
 	const residuesByChainRef = useRef(/* @__PURE__ */ new Map());
+	const addressIndexRef = useRef(/* @__PURE__ */ new Map());
+	const framedOrientationRef = useRef(void 0);
 	/**
-	* The visibility and coloring to apply as soon as a structure exists. Read
-	* through refs because both arrive as fresh objects on every render, and a
-	* load has to be able to consult them without the load effect depending on
-	* them - a new Set each render would reload the structure on every pass.
+	* The scene as the props describe it, read by a load when it comes to draw.
+	* Through a ref because a load outlasts renders and has to draw what the
+	* props say when it gets there, not what they said when it began.
 	*/
-	const hiddenChainsRef = useRef(hiddenChains);
-	hiddenChainsRef.current = hiddenChains;
-	const chainColorsRef = useRef(chainColors);
-	chainColorsRef.current = chainColors;
+	const scenePropsRef = useRef(sceneProps);
+	scenePropsRef.current = sceneProps;
+	const initialPropsRef = useRef({
+		backgroundColor,
+		edgeColor,
+		highlightColor,
+		mode,
+		molstarSpec,
+		showAxes,
+		showSequenceViewer,
+		structure
+	});
+	initialPropsRef.current = {
+		backgroundColor,
+		edgeColor,
+		highlightColor,
+		mode,
+		molstarSpec,
+		showAxes,
+		showSequenceViewer,
+		structure
+	};
 	/**
 	* Carries the theme-dependent props into the views Mol* renders in its own
 	* React root. They cannot read them from context, and rebuilding the plugin
@@ -3910,18 +2924,16 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 		clipRatioRef.current = ratio;
 	}, []);
 	/**
-	* Takes up what a load produced: the component refs the chain-keyed props
-	* address, the visibility they were already asking for, and the chain list
-	* the consumer is told about.
+	* Takes up what a load produced: what the chain-keyed props and addresses
+	* are resolved against, and the chain list the consumer is told about.
 	*
 	* Chains are published only when they actually differ, so reloading the same
-	* structure - a theme switch that happens to reload, a parent handing back an
-	* equal PDB string - does not hand every consumer a new array to react to.
+	* structure - a parent handing back an equal PDB string - does not hand every
+	* consumer a new array to react to.
 	*/
-	const adoptLoadedStructure = useCallback((plugin, loaded) => {
-		componentRefsRef.current = loaded.componentRefs;
+	const adoptLoadedStructure = useCallback((loaded) => {
 		residuesByChainRef.current = loaded.residuesByChain;
-		applyChainVisibility(plugin, loaded.componentRefs, hiddenChainsRef.current);
+		addressIndexRef.current = loaded.addressIndex;
 		setChains((prev) => chainsEqual(prev, loaded.chains) ? prev : loaded.chains);
 		setLoadCount((count) => count + 1);
 	}, []);
@@ -3933,30 +2945,113 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 	onSelectionChangeRef.current = onSelectionChange;
 	const onResidueHoverRef = useRef(onResidueHover);
 	onResidueHoverRef.current = onResidueHover;
+	const onReadyRef = useRef(onReady);
+	onReadyRef.current = onReady;
+	const onErrorRef = useRef(onError);
+	onErrorRef.current = onError;
+	const onDisposeRef = useRef(onDispose);
+	onDisposeRef.current = onDispose;
+	const onStructureLoadRef = useRef(onStructureLoad);
+	onStructureLoadRef.current = onStructureLoad;
+	/**
+	* Fixed at the first render: the load path draws or declines to draw by it,
+	* so a mode that changed under a live plugin would leave its scene half one
+	* and half the other.
+	*/
+	const sceneModeRef = useRef(sceneMode);
+	/**
+	* The plugin last handed to `onReady`, so that `onDispose` is only called for
+	* one a consumer has actually been given - and is called for it even while
+	* its `onReady` is still running.
+	*/
+	const handedOverRef = useRef(null);
 	/** Last residue reported to `onResidueHover`, to suppress repeats. */
 	const lastHoverRef = useRef(null);
-	const initialPropsRef = useRef({
-		backgroundColor,
-		edgeColor,
-		hasPlddt,
-		highlightColor,
-		mode,
-		molstarSpec,
-		showAxes,
-		showSequenceViewer,
-		structure
-	});
-	initialPropsRef.current = {
-		backgroundColor,
-		edgeColor,
-		hasPlddt,
-		highlightColor,
-		mode,
-		molstarSpec,
-		showAxes,
-		showSequenceViewer,
-		structure
-	};
+	const reportError = useCallback((error, phase) => {
+		const handler = onErrorRef.current;
+		if (handler) handler(error, phase);
+		else console.error(UNHANDLED_ERROR_MESSAGES[phase], error);
+	}, []);
+	/**
+	* Hands a loaded structure to `onReady` and waits for it.
+	*
+	* `isCurrent` says whether the plugin is still the viewer's own by the time
+	* the consumer is done with it. A failure after that is not reported: the
+	* plugin it happened on is gone, and the consumer has been told so through
+	* `onDispose` already.
+	*/
+	const handOver = useCallback(function() {
+		var _ref = _asyncToGenerator(function* (plugin, loaded, isCurrent) {
+			const ready = onReadyRef.current;
+			const { atomCount, chains: loadedChains, structure: parsed } = loaded;
+			if (!ready || !parsed) return;
+			handedOverRef.current = plugin;
+			try {
+				yield ready(plugin, {
+					atomCount,
+					chains: loadedChains,
+					structure: parsed
+				});
+			} catch (error) {
+				if (isCurrent()) reportError(error, "load");
+			}
+		});
+		return function(_x2, _x3, _x4) {
+			return _ref.apply(this, arguments);
+		};
+	}(), [reportError]);
+	/**
+	* Takes up whatever a load produced. A failed load leaves the viewer holding
+	* nothing, as a structure with no chains would, and is reported rather than
+	* handed to `onReady`.
+	*/
+	const takeUpLoad = useCallback(function() {
+		var _ref2 = _asyncToGenerator(function* (plugin, outcome, isCurrent) {
+			var _onStructureLoadRef$c;
+			if (!isCurrent()) return;
+			if (!outcome.ok) {
+				adoptLoadedStructure(NOTHING_LOADED);
+				reportError(outcome.error, "load");
+				return;
+			}
+			const { loaded } = outcome;
+			adoptLoadedStructure(loaded);
+			(_onStructureLoadRef$c = onStructureLoadRef.current) === null || _onStructureLoadRef$c === void 0 || _onStructureLoadRef$c.call(onStructureLoadRef, loadInfo(loaded));
+			yield handOver(plugin, loaded, isCurrent);
+		});
+		return function(_x5, _x6, _x7) {
+			return _ref2.apply(this, arguments);
+		};
+	}(), [
+		adoptLoadedStructure,
+		handOver,
+		reportError
+	]);
+	/**
+	* Loads a structure and brings everything up on it: parses it, draws the
+	* scene when the viewer is the one drawing it, places the camera, and hands
+	* it over. Runs inside the scene's queue, so it never interleaves with an
+	* update to the structure it is replacing.
+	*
+	* The camera is placed once something is drawn: Mol* settles a reset on the
+	* next frame, and one settled against an empty scene is lost. So it follows
+	* the viewer's own scene when there is one, and the consumer's `onReady`
+	* when the consumer draws.
+	*/
+	const loadAndDraw = useCallback(function() {
+		var _ref3 = _asyncToGenerator(function* (plugin, scene, text, isCurrent) {
+			const outcome = yield scene.load(text, scenePropsRef.current);
+			if (!isCurrent()) return;
+			const managed = sceneModeRef.current === "managed";
+			if (outcome.ok) setAxes(plugin, initialPropsRef.current.showAxes);
+			if (managed && outcome.ok) framedOrientationRef.current = scene.frame(scenePropsRef.current, true);
+			yield takeUpLoad(plugin, outcome, isCurrent);
+			if (!managed && outcome.ok && isCurrent()) framedOrientationRef.current = scene.frame(scenePropsRef.current, false);
+		});
+		return function(_x8, _x9, _x10, _x11) {
+			return _ref3.apply(this, arguments);
+		};
+	}(), [takeUpLoad]);
 	/**
 	* The consumer's `canvas3d` overrides, keyed by content. Unlike the rest of
 	* the spec these are re-applied when they change, and they commonly arrive
@@ -3977,7 +3072,7 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 		let cancelled = false;
 		let clipSubscription;
 		const init = function() {
-			var _ref2 = _asyncToGenerator(function* () {
+			var _ref4 = _asyncToGenerator(function* () {
 				yield nextFrame();
 				if (cancelled) return;
 				const rect = container.getBoundingClientRect();
@@ -3987,16 +3082,12 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 				}
 				const initial = initialPropsRef.current;
 				try {
-					var _plugin$canvas3d2;
-					const residueValueTheme = createResidueValueTheme(initial.mode);
-					const chainColorTheme = createChainColorTheme();
+					var _plugin$canvas3d;
 					const plugin = yield createViewer({
 						backgroundColor: initial.backgroundColor,
-						chainColorTheme,
 						edgeColor: initial.edgeColor,
 						highlightColor: initial.highlightColor,
 						molstarSpec: initial.molstarSpec,
-						residueValueTheme,
 						root: container,
 						showAxes: initial.showAxes,
 						showSequenceViewer: initial.showSequenceViewer,
@@ -4007,12 +3098,18 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 						return;
 					}
 					pluginRef.current = plugin;
-					residueValueThemeRef.current = residueValueTheme;
-					chainColorThemeRef.current = chainColorTheme;
+					const scene = new StructureScene(plugin, {
+						draw: sceneModeRef.current === "managed",
+						mode: initial.mode,
+						onBusyChange: setSceneBusy,
+						onRebuild: () => setSceneVersion((version) => version + 1),
+						reportError
+					});
+					sceneRef.current = scene;
 					const latest = initialPropsRef.current;
-					const loaded = yield loadStructure(plugin, latest.structure, latest.hasPlddt, latest.showAxes);
 					currentStructureRef.current = latest.structure;
-					adoptLoadedStructure(plugin, loaded);
+					yield scene.enqueue(() => loadAndDraw(plugin, scene, latest.structure, () => !cancelled));
+					if (cancelled) return;
 					/**
 					* Mol*'s click behavior is a BehaviorSubject, so subscribing replays
 					* whatever it is currently holding - which, before anything has been
@@ -4050,37 +3147,46 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 						lastHoverRef.current = residue;
 						(_onResidueHoverRef$cu = onResidueHoverRef.current) === null || _onResidueHoverRef$cu === void 0 || _onResidueHoverRef$cu.call(onResidueHoverRef, residue);
 					});
-					clipSubscription = (_plugin$canvas3d2 = plugin.canvas3d) === null || _plugin$canvas3d2 === void 0 ? void 0 : _plugin$canvas3d2.didDraw.subscribe(() => {
+					clipSubscription = (_plugin$canvas3d = plugin.canvas3d) === null || _plugin$canvas3d === void 0 ? void 0 : _plugin$canvas3d.didDraw.subscribe(() => {
 						syncClipToZoom(plugin, () => clipRatioRef.current);
 					});
 					if (!cancelled) setIsReady(true);
 				} catch (error) {
-					console.error("Failed to initialize Mol* viewer:", error);
+					if (!cancelled) reportError(error, "init");
 				}
 			});
 			return function init() {
-				return _ref2.apply(this, arguments);
+				return _ref4.apply(this, arguments);
 			};
 		}();
 		init();
 		return () => {
-			var _pluginRef$current;
+			var _sceneRef$current;
 			cancelled = true;
 			clipSubscription === null || clipSubscription === void 0 || clipSubscription.unsubscribe();
-			(_pluginRef$current = pluginRef.current) === null || _pluginRef$current === void 0 || _pluginRef$current.dispose();
+			(_sceneRef$current = sceneRef.current) === null || _sceneRef$current === void 0 || _sceneRef$current.dispose();
+			sceneRef.current = null;
+			const plugin = pluginRef.current;
+			try {
+				if (plugin && handedOverRef.current === plugin) {
+					var _onDisposeRef$current;
+					handedOverRef.current = null;
+					(_onDisposeRef$current = onDisposeRef.current) === null || _onDisposeRef$current === void 0 || _onDisposeRef$current.call(onDisposeRef);
+				}
+			} finally {
+				plugin === null || plugin === void 0 || plugin.dispose();
+			}
 			pluginRef.current = null;
-			residueValueThemeRef.current = null;
-			chainColorThemeRef.current = null;
-			componentRefsRef.current = /* @__PURE__ */ new Map();
 			residuesByChainRef.current = /* @__PURE__ */ new Map();
+			addressIndexRef.current = /* @__PURE__ */ new Map();
 			currentStructureRef.current = null;
 			clipRatioRef.current = null;
 			setIsReady(false);
 		};
 	}, []);
 	useEffect(() => {
-		var _pluginRef$current2, _initialPropsRef$curr;
-		const canvas3d = (_pluginRef$current2 = pluginRef.current) === null || _pluginRef$current2 === void 0 ? void 0 : _pluginRef$current2.canvas3d;
+		var _pluginRef$current, _initialPropsRef$curr;
+		const canvas3d = (_pluginRef$current = pluginRef.current) === null || _pluginRef$current === void 0 ? void 0 : _pluginRef$current.canvas3d;
 		if (!canvas3d || !isReady) return;
 		canvas3d.setProps({
 			marking: {
@@ -4109,6 +3215,8 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 			onChainHover,
 			onChainSelect,
 			onChainToggle,
+			onError: reportError,
+			sceneBusy,
 			selectedChains,
 			sequenceViewerBackgroundColor,
 			showAxes
@@ -4120,6 +3228,8 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 		onChainHover,
 		onChainSelect,
 		onChainToggle,
+		reportError,
+		sceneBusy,
 		selectedChains,
 		sequenceViewerBackgroundColor,
 		showAxes,
@@ -4131,34 +3241,55 @@ function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download
 	}, [showAxes, isReady]);
 	useEffect(() => {
 		const plugin = pluginRef.current;
-		if (!plugin || !isReady) return;
+		const scene = sceneRef.current;
+		if (!plugin || !scene || !isReady) return;
 		if (structure === currentStructureRef.current) return;
 		currentStructureRef.current = structure;
 		clipRatioRef.current = null;
 		lastHoverRef.current = null;
-		loadStructure(plugin, structure, hasPlddt, showAxes).then((loaded) => {
-			if (pluginRef.current !== plugin) return;
-			adoptLoadedStructure(plugin, loaded);
+		scene.enqueue(() => loadAndDraw(plugin, scene, structure, () => pluginRef.current === plugin)).catch((error) => {
+			if (pluginRef.current === plugin) reportError(error, "load");
 		});
 	}, [
 		structure,
-		hasPlddt,
 		isReady,
-		adoptLoadedStructure
+		loadAndDraw,
+		reportError
 	]);
+	/**
+	* Keys for the scene props that arrive as fresh objects on every render, so
+	* the update below turns on what they say rather than on their identity.
+	* `plddt` and the overlay are compared by identity, as they are elsewhere.
+	*/
+	const hiddenKey = chainSetKey(sceneProps.hiddenChains);
+	const sceneHighlightsKey = highlightsKey(sceneProps.highlights);
+	const chainColorsKey = JSON.stringify((_sceneProps$chainColo = sceneProps.chainColors) !== null && _sceneProps$chainColo !== void 0 ? _sceneProps$chainColo : null);
 	useEffect(() => {
-		const plugin = pluginRef.current;
-		if (!plugin || !isReady) return;
-		applyChainVisibility(plugin, componentRefsRef.current, hiddenChains);
-	}, [hiddenChains, isReady]);
+		const scene = sceneRef.current;
+		if (!scene || !isReady || sceneModeRef.current !== "managed") return;
+		scene.update(scenePropsRef.current);
+	}, [
+		isReady,
+		sceneProps.representation,
+		hiddenKey,
+		sceneHighlightsKey,
+		sceneProps.colorBy,
+		chainColorsKey,
+		sceneProps.plddt,
+		sceneProps.overlay,
+		sceneProps.mode
+	]);
 	return {
-		chainColorThemeRef,
+		addressIndexRef,
 		chains,
+		framedOrientationRef,
 		isReady,
 		loadCount,
 		pluginRef,
 		residuesByChainRef,
-		residueValueThemeRef,
+		sceneMode: sceneModeRef.current,
+		sceneRef,
+		sceneVersion,
 		setClipRatio
 	};
 }
@@ -4466,52 +3597,6 @@ function useSelectionReadout({ hoveredResidue, isReady, plddt, pluginRef, residu
 	};
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/hooks/useStructureColoring.ts
-/**
-* Decides what is coloring the structure and keeps that theme's data current.
-*
-* Three themes compete for the same representations, in a fixed order: a
-* residue value overlay, then pLDDT scores, then per-chain colors. Only one
-* can be applied, so the precedence lives here rather than being spread across
-* the hooks that own each theme's data - and the legend resolves what to
-* describe the same way, so the two cannot disagree about what is on screen.
-*
-* Recoloring happens in place: the camera is left where it is, so selecting or
-* switching an overlay does not zoom back out to the default view.
-*/
-function useStructureColoring({ chainColorThemeRef, chainColors, hasPlddt, isReady, mode, overlay, pluginRef, residueValueThemeRef }) {
-	useEffect(() => {
-		const plugin = pluginRef.current;
-		const residueTheme = residueValueThemeRef.current;
-		const chainTheme = chainColorThemeRef.current;
-		if (!plugin || !residueTheme || !chainTheme || !isReady) return;
-		chainTheme.setState(chainColors);
-		if (overlay) {
-			var _overlay$colorScale, _overlay$min;
-			residueTheme.setState({
-				colorScale: (_overlay$colorScale = overlay.colorScale) !== null && _overlay$colorScale !== void 0 ? _overlay$colorScale : PLASMA_COLOR_SCALE,
-				max: overlay.max,
-				min: (_overlay$min = overlay.min) !== null && _overlay$min !== void 0 ? _overlay$min : 0,
-				mode,
-				values: overlay.values
-			});
-			applyColorTheme(plugin, RESIDUE_VALUE_THEME_NAME);
-			return;
-		}
-		residueTheme.setState({
-			mode,
-			values: /* @__PURE__ */ new Map()
-		});
-		applyColorTheme(plugin, hasPlddt ? PLDDT_THEME_NAME : FALLBACK_THEME_NAME);
-	}, [
-		overlay,
-		hasPlddt,
-		isReady,
-		mode,
-		chainColors
-	]);
-}
-//#endregion
 //#region src/core/ProteinStructureViewer/ProteinStructureViewer.types.ts
 /** Pixel dimensions each resolution produces, for documentation and labels. */
 const DOWNLOAD_RESOLUTIONS = {
@@ -4525,18 +3610,30 @@ const DOWNLOAD_RESOLUTIONS = {
 const _excluded = [
 	"backgroundColor",
 	"chainColors",
+	"colorBy",
 	"disableChainHighlightOnHover",
 	"download",
 	"hiddenChains",
+	"highlights",
+	"initialCamera",
+	"onCameraChange",
 	"onChainVisibilityChange",
 	"onChainsChange",
 	"molstarSpec",
+	"onDispose",
+	"onError",
+	"onReady",
 	"onResidueClick",
 	"onResidueHover",
 	"onSelectionChange",
+	"onStructureLoad",
+	"orientation",
+	"projection",
+	"representation",
 	"structure",
 	"plddt",
 	"residueOverlay",
+	"sceneMode",
 	"selection",
 	"sequenceViewerBackgroundColor",
 	"showAxes",
@@ -4563,16 +3660,26 @@ const PLDDT_SCALE_LABEL = "pLDDT";
 const DEFAULT_OVERLAY_LABEL = "Value";
 /** Readout slot label used when an overlay does not name one. */
 const DEFAULT_READOUT_LABEL = "Value";
+const NO_SCALE = {
+	scale: null,
+	scaleLabel: void 0,
+	scaleMax: null,
+	scaleTooltip: void 0,
+	scaleTooltipProps: void 0,
+	valueLabel: void 0
+};
 /**
 * Chooses what the legend describes, following whatever is actually coloring
-* the structure: the overlay when one is set, the pLDDT bands when scores were
-* supplied, and nothing at all otherwise - Mol* falls back to chain coloring
-* there, which no per-residue scale describes, so a key would be labelling
-* colors that are not on screen.
-*/
-function resolveScaleProps(overlay, hasPlddt) {
-	if (overlay) {
+* the structure: the overlay when it is painting, the pLDDT bands when they
+* are, and nothing at all for chain coloring - which no per-residue scale
+* describes, so a key would be labelling colors that are not on screen. An
+* overlay named by `colorBy` but not supplied paints everything neutral, and
+* has no key either.
+*/
+function resolveScaleProps(colorBy, overlay) {
+	if (colorBy === "overlay") {
 		var _overlay$colorScale, _overlay$label, _overlay$min, _overlay$readoutLabel;
+		if (!overlay) return NO_SCALE;
 		return {
 			scale: (_overlay$colorScale = overlay.colorScale) !== null && _overlay$colorScale !== void 0 ? _overlay$colorScale : PLASMA_COLOR_SCALE,
 			scaleLabel: (_overlay$label = overlay.label) !== null && _overlay$label !== void 0 ? _overlay$label : DEFAULT_OVERLAY_LABEL,
@@ -4583,36 +3690,20 @@ function resolveScaleProps(overlay, hasPlddt) {
 			valueLabel: (_overlay$readoutLabel = overlay.readoutLabel) !== null && _overlay$readoutLabel !== void 0 ? _overlay$readoutLabel : DEFAULT_READOUT_LABEL
 		};
 	}
-	if (hasPlddt) return {
+	if (colorBy === "plddt") return _objectSpread2(_objectSpread2({}, NO_SCALE), {}, {
 		scale: PLDDT_COLOR_SCALE,
-		scaleLabel: PLDDT_SCALE_LABEL,
-		scaleMax: null,
-		scaleTooltip: void 0,
-		scaleTooltipProps: void 0,
-		valueLabel: void 0
-	};
-	return {
-		scale: null,
-		scaleLabel: void 0,
-		scaleMax: null,
-		scaleTooltip: void 0,
-		scaleTooltipProps: void 0,
-		valueLabel: void 0
-	};
+		scaleLabel: PLDDT_SCALE_LABEL
+	});
+	return NO_SCALE;
 }
 var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	var _selection$chains;
-	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, structure, plddt, residueOverlay, selection: selectionProp, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded);
+	const { backgroundColor, chainColors: chainColorOverrides, colorBy: colorByProp, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, highlights, initialCamera, onCameraChange, onChainVisibilityChange, onChainsChange, molstarSpec, onDispose, onError, onReady, onResidueClick, onResidueHover, onSelectionChange, onStructureLoad, orientation, projection, representation = "cartoon", structure, plddt, residueOverlay, sceneMode = "managed", selection: selectionProp, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded);
 	const theme = useTheme();
 	const mode = getMode({ theme });
 	const semanticColors = getSemanticColors({ theme });
 	const pluginMountRef = useRef(null);
-	const hasPlddt = Boolean(plddt && plddt.length > 0);
-	const processedStructure = useMemo(() => hasPlddt ? injectPlddt(structure, plddt) : structure, [
-		structure,
-		plddt,
-		hasPlddt
-	]);
+	const colorBy = resolveColorBy(colorByProp, residueOverlay, plddt);
 	const bgColor = useMemo(() => {
 		var _semanticColors$base;
 		return themeColor(backgroundColor !== null && backgroundColor !== void 0 ? backgroundColor : semanticColors === null || semanticColors === void 0 || (_semanticColors$base = semanticColors.base) === null || _semanticColors$base === void 0 ? void 0 : _semanticColors$base.backgroundPrimary, FALLBACK_BACKGROUND_COLOR[mode]);
@@ -4656,8 +3747,8 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	* than undoing itself.
 	*/
 	const handleChainSelect = useCallback((chainId) => {
-		var _selection$chains2, _selection$residues;
-		changeSelection((selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length) ? null : { chains: [chainId] });
+		var _selection$chains2, _selection$residues, _selection$addresses;
+		changeSelection((selection === null || selection === void 0 || (_selection$chains2 = selection.chains) === null || _selection$chains2 === void 0 ? void 0 : _selection$chains2.length) === 1 && selection.chains[0] === chainId && !((_selection$residues = selection.residues) === null || _selection$residues === void 0 ? void 0 : _selection$residues.length) && !((_selection$addresses = selection.addresses) === null || _selection$addresses === void 0 ? void 0 : _selection$addresses.length) ? null : { chains: [chainId] });
 	}, [changeSelection, selection]);
 	/**
 	* Dims every other chain while a chain's name is pointed at, in the legend
@@ -4681,13 +3772,11 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		hiddenChains: hiddenChainsProp,
 		onChainVisibilityChange
 	});
-	const { chainColorThemeRef, chains: loadedChains, isReady, loadCount, pluginRef, residuesByChainRef, residueValueThemeRef, setClipRatio } = useMolstarPlugin({
+	const { addressIndexRef, chains: loadedChains, framedOrientationRef, isReady, loadCount, pluginRef, residuesByChainRef, sceneRef, sceneVersion, setClipRatio } = useMolstarPlugin({
 		backgroundColor: bgColor,
-		chainColors,
 		containerRef: pluginMountRef,
 		download,
 		edgeColor,
-		hasPlddt,
 		hiddenChains,
 		highlightColor,
 		mode,
@@ -4695,23 +3784,52 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		onChainHover: highlightChain,
 		onChainSelect: handleChainSelect,
 		onChainToggle: toggleChain,
+		onDispose,
+		onError,
+		onReady,
 		onResidueClick,
 		onResidueHover: handleResidueHover,
 		onSelectionChange: changeSelection,
 		onSelectionClear: handleSelectionClear,
+		onStructureLoad,
+		sceneProps: {
+			chainColors: chainColorOverrides,
+			colorBy: colorByProp,
+			hiddenChains,
+			highlights,
+			initialCamera,
+			mode,
+			orientation,
+			overlay: residueOverlay,
+			plddt,
+			projection,
+			representation
+		},
+		sceneMode,
 		selectedChains,
 		sequenceViewerBackgroundColor,
 		showAxes,
 		showSequenceViewer,
-		structure: processedStructure
+		structure
 	});
 	highlightChainRef.current = useChainHighlight({
 		disabled: disableChainHighlightOnHover,
 		hiddenChains,
 		loadCount,
 		pluginRef,
+		sceneVersion,
 		selectedChains
 	});
+	useCamera({
+		framedOrientationRef,
+		highlights,
+		isReady,
+		onCameraChange,
+		orientation,
+		pluginRef,
+		projection,
+		sceneRef
+	});
 	useEffect(() => {
 		setChains(loadedChains);
 	}, [loadedChains]);
@@ -4721,21 +3839,19 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		var _onChainsChangeRef$cu;
 		(_onChainsChangeRef$cu = onChainsChangeRef.current) === null || _onChainsChangeRef$cu === void 0 || _onChainsChangeRef$cu.call(onChainsChangeRef, loadedChains);
 	}, [loadedChains]);
-	useStructureColoring({
-		chainColorThemeRef,
-		chainColors,
-		hasPlddt,
-		isReady,
-		mode,
-		overlay: residueOverlay,
-		pluginRef,
-		residueValueThemeRef
-	});
+	const focusedSelection = useMemo(() => {
+		var _addressIndexRef$curr;
+		return resolveSelectionAddresses(selection, (_addressIndexRef$curr = addressIndexRef.current) !== null && _addressIndexRef$curr !== void 0 ? _addressIndexRef$curr : /* @__PURE__ */ new Map());
+	}, [
+		selection,
+		residueAddressesKey(selection === null || selection === void 0 ? void 0 : selection.addresses),
+		loadCount
+	]);
 	useSelectionFocus({
 		hiddenChains,
 		isReady,
 		pluginRef,
-		selection,
+		selection: focusedSelection,
 		setClipRatio
 	});
 	const { hoveredReadout, selectedReadout } = useSelectionReadout({
@@ -4745,9 +3861,9 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		pluginRef,
 		residueOverlay,
 		residuesByChainRef,
-		selection
+		selection: focusedSelection
 	});
-	const scaleProps = useMemo(() => resolveScaleProps(residueOverlay, hasPlddt), [residueOverlay, hasPlddt]);
+	const scaleProps = useMemo(() => resolveScaleProps(colorBy, residueOverlay), [colorBy, residueOverlay]);
 	/**
 	* What a chain's swatch can show follows whatever is painting the
 	* structure, in the same order the color key resolves in.
@@ -4759,8 +3875,8 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	* a swatch at all, so the rows keep their labels and toggles and the color
 	* key beside them does the describing.
 	*/
-	const chainColoringActive = !residueOverlay && !hasPlddt;
-	const plddtColoringActive = !residueOverlay && hasPlddt;
+	const chainColoringActive = colorBy === "chain";
+	const plddtColoringActive = colorBy === "plddt";
 	return /* @__PURE__ */ jsxs(ViewerRoot, _objectSpread2(_objectSpread2({
 		ref,
 		showSequenceViewer
@@ -4780,4 +3896,4 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 	}, scaleProps))] }));
 }));
 //#endregion
-export { injectPlddtIntoMmcif as a, injectPlddt as i, DOWNLOAD_RESOLUTIONS as n, injectPlddtIntoPdb as o, PLDDT_COLOR_SCALE as r, detectStructureFormat as s, ProteinStructureViewer_default as t };
+export { DOWNLOAD_RESOLUTIONS as n, ProteinStructureViewer_default as t };