@czi-sds/data-viz 2.1.1 → 2.2.0

package/dist/index.esm.js

@@ -1,17 +1,20 @@
 "use client";
 import { init } from "echarts";
-import { Fragment, cloneElement, forwardRef, memo, useCallback, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Fragment, cloneElement, createContext, forwardRef, memo, useCallback, useContext, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { throttle } from "lodash";
 import styled from "@emotion/styled";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { Button, Legend, Theme, Tooltip, TooltipTable, defaultTheme, fontBodyXs, fontBodyXxxs, fontCodeXs, fontHeaderM, fontHeaderS, fontTabularSemiboldXxxxs, generateDiscreteColors, getCorners, getMode, getSemanticColors, getSpaces } from "@czi-sds/components";
 import { ThemeProvider, useTheme } from "@mui/material/styles";
-import { ArrowCounterClockwiseIcon, CheckIcon, CopyIcon, QuestionIcon } from "@phosphor-icons/react";
+import { ApertureIcon, ArrowCounterClockwiseIcon, CheckIcon, CopyIcon, EyeIcon, EyeSlashIcon, QuestionIcon } from "@phosphor-icons/react";
+import { Color } from "molstar/lib/mol-util/color";
+import { OrderedSet } from "molstar/lib/mol-data/int";
 import { Structure, StructureElement, StructureProperties, Unit } from "molstar/lib/mol-model/structure";
 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";
@@ -19,7 +22,6 @@ 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,8 +32,11 @@ import { Toasts } from "molstar/lib/mol-plugin-ui/toast";
 import { Viewport } from "molstar/lib/mol-plugin-ui/viewport";
 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 { Color } from "molstar/lib/mol-util/color";
+import { StructureFocusRepresentation } from "molstar/lib/mol-plugin/behavior/dynamic/selection/structure-focus-representation";
 //#region src/common/colorScales.ts
 /**
 * Perceptually uniform sequential scale (matplotlib's plasma), the default for
@@ -549,6 +554,191 @@ var HeatmapChart_default = memo(forwardRef((props, ref) => {
 		else ref.current = element;
 	}
 }));
+//#endregion
+//#region src/core/ProteinStructureViewer/components/ChainLegend/style.ts
+/** Opacity applied to a hidden chain's row, so it reads as off but reachable. */
+const HIDDEN_OPACITY = .4;
+/** Side of the color swatch. */
+const SWATCH_SIZE = 8;
+/**
+* The rows, stacked and right-aligned against the color key beside them.
+*
+* Pointer events are switched back on here: the legend overlay turns them off
+* so drags meant for the structure are not intercepted, and this is one of the
+* two places in it that has to be clickable.
+*/
+const ChainRowList = styled("div")`
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  pointer-events: auto;
+  max-height: 80px;
+  overflow-y: auto;
+`;
+const ChainRow = styled("div")`
+  display: flex;
+  align-items: center;
+
+  ${(props) => {
+	const spaces = getSpaces(props);
+	return `
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xs}px;
+    `;
+}}
+`;
+const ChainSwatch = styled("div")`
+  flex: none;
+  width: ${SWATCH_SIZE}px;
+  height: ${SWATCH_SIZE}px;
+  border-radius: 1px;
+
+  ${(props) => `
+    background-color: ${props.swatchColor};
+    opacity: ${props.isHidden ? HIDDEN_OPACITY : 1};
+  `}
+`;
+/**
+* A swatch quartered into a grid, for a coloring no single color stands for.
+*
+* Occupies the same box as the solid swatch so the rows stay aligned whichever
+* one a chain gets, with a hairline gap between the quadrants to read as four
+* colors rather than one blurred square.
+*/
+const ChainSwatchGrid = styled("div")`
+  flex: none;
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  grid-template-rows: repeat(2, 1fr);
+  gap: 0px;
+  width: ${SWATCH_SIZE}px;
+  height: ${SWATCH_SIZE}px;
+  border-radius: 1px;
+  overflow: hidden;
+
+  ${(props) => `
+    opacity: ${props.isHidden ? HIDDEN_OPACITY : 1};
+  `}
+`;
+const ChainSwatchQuadrant = styled("div")`
+  ${(props) => `
+    background-color: ${props.swatchColor};
+  `}
+`;
+/**
+* Selects the whole chain, or clears it when it is already the selection. A
+* button so it is reachable from the keyboard.
+*/
+const ChainLabel$1 = styled("button")`
+  ${fontBodyXxxs}
+
+  padding: 0;
+  border: none;
+  background: none;
+
+  ${(props) => {
+	var _semanticColors$base, _semanticColors$base2, _semanticColors$base3;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base = semanticColors.base) === null || _semanticColors$base === void 0 ? void 0 : _semanticColors$base.textSecondary};
+      cursor: ${props.isHidden ? "default" : "pointer"};
+      font-weight: ${props.isSelected ? 600 : "inherit"};
+      opacity: ${props.isHidden ? HIDDEN_OPACITY : 1};
+
+      &:hover {
+        color: ${props.isHidden ? semanticColors === null || semanticColors === void 0 || (_semanticColors$base2 = semanticColors.base) === null || _semanticColors$base2 === void 0 ? void 0 : _semanticColors$base2.textSecondary : semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.textPrimary};
+      }
+    `;
+}}
+`;
+const VisibilityToggle = styled("button")`
+  display: flex;
+  align-items: center;
+  padding: 0;
+  border: none;
+  background: none;
+  cursor: pointer;
+  margin-top: 1px;
+
+  ${(props) => {
+	var _semanticColors$base4, _semanticColors$base5;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base4 = semanticColors.base) === null || _semanticColors$base4 === void 0 ? void 0 : _semanticColors$base4.textTertiaryOnDark};
+
+      &:hover {
+        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base5 = semanticColors.base) === null || _semanticColors$base5 === void 0 ? void 0 : _semanticColors$base5.textPrimary};
+      }
+
+      svg {
+        display: block;
+      }
+    `;
+}}
+`;
+//#endregion
+//#region src/core/ProteinStructureViewer/components/ChainLegend/index.tsx
+/**
+* Lists the structure's chains, each with its color and a visibility toggle.
+*
+* Only drawn for a complex: one chain needs no key to tell it from anything,
+* and hiding it would leave an empty canvas with no way back. Its home is the
+* legend rather than the sequence panel so that it survives
+* `showSequenceViewer={false}`, where the chains would otherwise have nowhere
+* to be listed.
+*/
+function ChainLegend({ bandColors, chainColors, chains, hiddenChains, onChainHover, onChainSelect, onChainToggle, selectedChains }) {
+	if (chains.length < 2) return null;
+	return /* @__PURE__ */ jsx(ChainRowList, { children: chains.map((chain) => {
+		var _selectedChains$has;
+		const hidden = hiddenChains.has(chain.chainId);
+		const selected = (_selectedChains$has = selectedChains === null || selectedChains === void 0 ? void 0 : selectedChains.has(chain.chainId)) !== null && _selectedChains$has !== void 0 ? _selectedChains$has : false;
+		const color = chainColors === null || chainColors === void 0 ? void 0 : chainColors.get(chain.chainId);
+		return /* @__PURE__ */ jsxs(ChainRow, {
+			onBlur: () => onChainHover === null || onChainHover === void 0 ? void 0 : onChainHover(null),
+			onFocus: () => onChainHover === null || onChainHover === void 0 ? void 0 : onChainHover(chain.chainId),
+			onMouseEnter: () => onChainHover === null || onChainHover === void 0 ? void 0 : onChainHover(chain.chainId),
+			onMouseLeave: () => onChainHover === null || onChainHover === void 0 ? void 0 : onChainHover(null),
+			children: [
+				/* @__PURE__ */ jsx(Tooltip, {
+					arrow: true,
+					placement: "top",
+					disableInteractive: true,
+					title: hidden ? `Chain ${chain.label} is hidden` : `Click to ${selected ? "deselect" : "select"} Chain ${chain.label}`,
+					children: /* @__PURE__ */ jsxs(ChainLabel$1, {
+						"aria-pressed": selected,
+						disabled: hidden,
+						isHidden: hidden,
+						isSelected: selected,
+						onClick: () => onChainSelect(chain.chainId),
+						type: "button",
+						children: ["Chain ", chain.label]
+					})
+				}),
+				color !== void 0 && /* @__PURE__ */ jsx(ChainSwatch, {
+					isHidden: hidden,
+					swatchColor: color
+				}),
+				color === void 0 && bandColors !== void 0 && /* @__PURE__ */ jsx(ChainSwatchGrid, {
+					isHidden: hidden,
+					children: bandColors.map((band) => /* @__PURE__ */ jsx(ChainSwatchQuadrant, { swatchColor: band }, band))
+				}),
+				/* @__PURE__ */ jsx(Tooltip, {
+					arrow: true,
+					placement: "top",
+					disableInteractive: true,
+					title: hidden ? `Show Chain ${chain.label}` : `Hide Chain ${chain.label}`,
+					children: /* @__PURE__ */ jsx(VisibilityToggle, {
+						"aria-label": `${hidden ? "Show" : "Hide"} chain ${chain.label}`,
+						"aria-pressed": hidden,
+						onClick: () => onChainToggle(chain.chainId),
+						type: "button",
+						children: hidden ? /* @__PURE__ */ jsx(EyeSlashIcon, { size: 12 }) : /* @__PURE__ */ jsx(EyeIcon, { size: 12 })
+					})
+				})
+			]
+		}, chain.chainId);
+	}) });
+}
 /** Height of the color bar itself. */
 const BAR_HEIGHT = 8;
 /**
@@ -673,14 +863,24 @@ const ViewerRoot = styled("div")`
     height: 100% !important;
   }
 
-  /* Mol* chrome that the custom viewport and sequence panel replace. */
-  .msp-plugin .msp-viewport-controls-buttons,
-  .msp-plugin .msp-layout-expanded,
-  .msp-plugin .msp-log,
-  .msp-plugin .msp-left-panel-controls,
-  .msp-plugin .msp-layout-region.msp-layout-left,
-  .msp-plugin .msp-layout-region.msp-layout-right,
-  .msp-plugin .msp-layout-region.msp-layout-bottom {
+  /*
+   * The expanded layout is kept hidden because it is the one piece of Mol*
+   * chrome that would escape this container: it takes the plugin out of the
+   * box it was given and over the page.
+   *
+   * Its neighbours used to be here too - the viewport's icon column, and the
+   * left, right and bottom regions. They are not any more, because hiding them
+   * from here made them unreachable: Mol* already gates each of them behind a
+   * PluginConfig.Viewport flag and behind layout.initial.regionState, both of
+   * which a consumer can set through molstarSpec, and a display:none on top of
+   * that overrode the answer. None of them shows by default - the viewer's own
+   * flags and region state are what keep them away - so this only has to stay
+   * out of their way.
+   *
+   * No backticks in here: this is inside a template literal, and one would end
+   * it.
+   */
+  .msp-plugin .msp-layout-expanded {
     display: none !important;
   }
 
@@ -831,6 +1031,18 @@ const StatsGrid = styled("div")`
     `;
 }}
 `;
+const ChainScaleColumn = styled("div")`
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+
+  ${(props) => {
+	const spaces = getSpaces(props);
+	return `
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.l}px;
+    `;
+}}
+`;
 const StatColumnWrapper = styled("div")`
   display: flex;
   flex-direction: column;
@@ -923,6 +1135,19 @@ function StatColumn({ label, value }) {
 	return /* @__PURE__ */ jsxs(StatColumnWrapper, { children: [/* @__PURE__ */ jsx(StatValue, { children: value }), /* @__PURE__ */ jsx(StatLabel, { children: label })] });
 }
 /**
+* Builds one readout slot.
+*
+* A readout covering several residues reports a mean, and the label says so:
+* calling it "pLDDT" while it averages ninety of them would read as a single
+* residue's score.
+*/
+function readoutSlot(label, value, residueCount) {
+	return {
+		label: residueCount > 1 ? `Mean ${label}` : label,
+		value: value !== null ? value.toFixed(VALUE_PRECISION) : MISSING_VALUE
+	};
+}
+/**
 * Stats and color key overlaid on the structure viewer.
 *
 * When a residue is selected or hovered, the whole-structure stats are replaced
@@ -932,24 +1157,19 @@ function StatColumn({ label, value }) {
 * residue takes priority so the user can inspect others without losing their
 * selection.
 */
-function StructureLegend({ hoveredResidue = null, scale, scaleLabel, scaleMax = null, scaleMin = 0, scaleTooltip, scaleTooltipProps, selectedResidue = null, showSequenceViewer, stats, valueLabel }) {
-	var _stats$, _stats$2, _stats$3;
+function StructureLegend({ chainBandColors, chainColors, chains = [], hiddenChains, hoveredResidue = null, onChainHover, onChainSelect, onChainToggle, scale, scaleLabel, scaleMax = null, scaleMin = 0, scaleTooltip, scaleTooltipProps, selectedChains, selectedResidue = null, showSequenceViewer, stats, valueLabel }) {
+	var _activeResidue$residu, _stats$, _stats$2, _stats$3;
 	const activeResidue = hoveredResidue !== null && hoveredResidue !== void 0 ? hoveredResidue : selectedResidue;
 	const showResidue = activeResidue !== null;
 	const showValue = showResidue && valueLabel !== void 0;
+	const residueCount = (_activeResidue$residu = activeResidue === null || activeResidue === void 0 ? void 0 : activeResidue.residueCount) !== null && _activeResidue$residu !== void 0 ? _activeResidue$residu : 1;
 	const slots = [
 		showResidue ? {
-			label: "Residue",
+			label: residueCount > 1 ? "Selection" : "Residue",
 			value: activeResidue.label
 		} : (_stats$ = stats[0]) !== null && _stats$ !== void 0 ? _stats$ : null,
-		showValue ? {
-			label: valueLabel,
-			value: activeResidue.value !== null ? activeResidue.value.toFixed(VALUE_PRECISION) : MISSING_VALUE
-		} : (_stats$2 = stats[1]) !== null && _stats$2 !== void 0 ? _stats$2 : null,
-		showResidue ? {
-			label: "pLDDT",
-			value: activeResidue.plddt !== null ? activeResidue.plddt.toFixed(VALUE_PRECISION) : MISSING_VALUE
-		} : (_stats$3 = stats[2]) !== null && _stats$3 !== void 0 ? _stats$3 : null
+		showValue ? readoutSlot(valueLabel, activeResidue.value, residueCount) : (_stats$2 = stats[1]) !== null && _stats$2 !== void 0 ? _stats$2 : null,
+		showResidue ? readoutSlot("pLDDT", activeResidue.plddt, residueCount) : (_stats$3 = stats[2]) !== null && _stats$3 !== void 0 ? _stats$3 : null
 	];
 	return /* @__PURE__ */ jsxs(LegendOverlay, {
 		showSequenceViewer,
@@ -960,7 +1180,16 @@ function StructureLegend({ hoveredResidue = null, scale, scaleLabel, scaleMax =
 				label: slot.label,
 				value: slot.value
 			}, i) : /* @__PURE__ */ jsx("div", {}, i);
-		}) }), scale && /* @__PURE__ */ jsxs(ScaleColumn, { children: [/* @__PURE__ */ jsx(ColorScaleLegend, {
+		}) }), /* @__PURE__ */ jsxs(ChainScaleColumn, { children: [onChainToggle && onChainSelect && /* @__PURE__ */ jsx(ChainLegend, {
+			bandColors: chainBandColors,
+			chainColors,
+			chains,
+			hiddenChains: hiddenChains !== null && hiddenChains !== void 0 ? hiddenChains : /* @__PURE__ */ new Set(),
+			onChainHover,
+			onChainSelect,
+			onChainToggle,
+			selectedChains
+		}), scale && /* @__PURE__ */ jsxs(ScaleColumn, { children: [/* @__PURE__ */ jsx(ColorScaleLegend, {
 			max: scaleMax,
 			min: scaleMin,
 			scale
@@ -973,8 +1202,347 @@ function StructureLegend({ hoveredResidue = null, scale, scaleLabel, scaleMax =
 				size: 10,
 				weight: "bold"
 			}) })
-		}))] })] })]
+		}))] })] })] })]
+	});
+}
+//#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 one chain's polymer, in the first structure that has one.
+*
+* The polymer alone, so pointing at a chain's name lights up the cartoon the
+* name is captioning. The ligands sitting on the chain belong to it but are
+* not what it is named for, and they are drawn by a representation of their
+* own.
+*/
+function lociForChainPolymer(plugin, chainId) {
+	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 = lociMatching(structure, (location) => StructureProperties.chain.auth_asym_id(location) === chainId && StructureProperties.entity.type(location) === "polymer");
+		if (loci) return loci;
+	}
+}
+/**
+* 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$obj2;
+		const structure = (_entry$cell$obj2 = entry.cell.obj) === null || _entry$cell$obj2 === void 0 ? void 0 : _entry$cell$obj2.data;
+		if (!structure) continue;
+		const loci = lociForSelectionInStructure(structure, selection, hiddenChains);
+		if (loci) return loci;
+	}
+}
+//#endregion
+//#region src/core/ProteinStructureViewer/hooks/useChainHighlight.ts
+/**
+* What a chain lights up in while its name is under the pointer.
+*
+* Its own color rather than the theme's hover tint, because it answers a
+* different question. Hovering a residue asks "what is this?" and a tint is
+* enough; pointing at a chain's name asks "where is this chain?" of a
+* structure where the answer may be half the screen, and has to carry across
+* a cartoon already painted in the chain palette, in pLDDT bands, or in an
+* overlay. A saturated pink is in none of those, so it cannot be mistaken for
+* the structure's own coloring.
+*/
+const CHAIN_HIGHLIGHT_COLOR = Color.fromRgb(200, 45, 149);
+/**
+* Stronger than the residue hover's tint, for the same reason. A whole chain
+* washed in 20% pink reads as a rendering artifact; at this strength it reads
+* as deliberate.
+*/
+const CHAIN_HIGHLIGHT_STRENGTH = .7;
+/**
+* Lights up a whole chain in the 3D view while its name is pointed at, in the
+* sequence panel's captions or the chain legend's rows.
+*
+* Mol*'s marking system is what draws it, so the chain is tinted and outlined
+* exactly as a hovered residue is, with no geometry added to the state tree
+* and nothing to tear down. Marking colors are a property of the renderer
+* rather than of the loci, though, so the pink is swapped in for the length of
+* the hover and the theme's own colors handed back on the way out.
+*
+* Those colors are read off the canvas at that moment rather than passed in.
+* They are already derived from the theme in two places, and a third copy kept
+* in step by hand would be the one to drift.
+*/
+function useChainHighlight({ disabled, pluginRef }) {
+	const borrowedRef = useRef(null);
+	const highlightChain = useCallback((name) => {
+		var _borrowedRef$current;
+		const plugin = pluginRef.current;
+		const canvas3d = plugin === null || plugin === void 0 ? void 0 : plugin.canvas3d;
+		if (!plugin || !canvas3d) return;
+		const chainId = disabled ? null : name;
+		if (chainId === null) {
+			plugin.managers.interactivity.lociHighlights.clearHighlights();
+			const borrowed = borrowedRef.current;
+			if (borrowed) {
+				canvas3d.setProps({
+					marking: { highlightEdgeColor: borrowed.highlightEdgeColor },
+					renderer: {
+						highlightColor: borrowed.highlightColor,
+						highlightStrength: borrowed.highlightStrength
+					}
+				});
+				borrowedRef.current = null;
+			}
+			return;
+		}
+		const loci = lociForChainPolymer(plugin, chainId);
+		if (!loci) return;
+		(_borrowedRef$current = borrowedRef.current) !== null && _borrowedRef$current !== void 0 || (borrowedRef.current = {
+			highlightColor: canvas3d.props.renderer.highlightColor,
+			highlightEdgeColor: canvas3d.props.marking.highlightEdgeColor,
+			highlightStrength: canvas3d.props.renderer.highlightStrength
+		});
+		canvas3d.setProps({
+			marking: { highlightEdgeColor: CHAIN_HIGHLIGHT_COLOR },
+			renderer: {
+				highlightColor: CHAIN_HIGHLIGHT_COLOR,
+				highlightStrength: CHAIN_HIGHLIGHT_STRENGTH
+			}
+		});
+		plugin.managers.interactivity.lociHighlights.highlightOnly({ loci });
+	}, [disabled, pluginRef]);
+	useEffect(() => () => void (borrowedRef.current = null), []);
+	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
+* the consumer asked for.
+*
+* Visibility is controlled when `hiddenChains` is passed and owned here when it
+* is not, so the legend's toggles work out of the box without taking the
+* decision away from a consumer that wants it. `onChainVisibilityChange` fires
+* either way: a consumer that only wants to follow along should not have to
+* take ownership to hear about it.
+*/
+function useChains({ chainColors, chains, hiddenChains, onChainVisibilityChange }) {
+	const isControlled = hiddenChains !== void 0;
+	const [ownHidden, setOwnHidden] = useState([]);
+	const onChainVisibilityChangeRef = useRef(onChainVisibilityChange);
+	onChainVisibilityChangeRef.current = onChainVisibilityChange;
+	const chainIds = useMemo(() => chains.map((c) => c.chainId), [chains]);
+	/**
+	* Chains the structure no longer has cannot be unhidden through the legend,
+	* since it has no row for them, so a stale id would hide a chain that shares
+	* its name in the next structure. Only the uncontrolled side is pruned; a
+	* controlled consumer owns its own list.
+	*/
+	useEffect(() => {
+		if (isControlled) return;
+		setOwnHidden((prev) => {
+			const kept = prev.filter((id) => chainIds.includes(id));
+			return kept.length === prev.length ? prev : kept;
+		});
+	}, [chainIds, isControlled]);
+	const hiddenKey = [...isControlled ? hiddenChains : ownHidden].sort().join("\0");
+	const hidden = useMemo(() => new Set(hiddenKey === "" ? [] : hiddenKey.split("\0")), [hiddenKey]);
+	return {
+		colors: useMemo(() => chainColorMap(chainIds, chainColors), [chainIds.map((id) => {
+			var _chainColors$id;
+			return `${id}:${(_chainColors$id = chainColors === null || chainColors === void 0 ? void 0 : chainColors[id]) !== null && _chainColors$id !== void 0 ? _chainColors$id : ""}`;
+		}).join("\0")]),
+		hidden,
+		toggleChain: useCallback((chainId) => {
+			var _onChainVisibilityCha;
+			const next = hidden.has(chainId) ? [...hidden].filter((id) => id !== chainId) : [...hidden, chainId];
+			const ordered = chainIds.filter((id) => next.includes(id));
+			if (!isControlled) setOwnHidden(ordered);
+			(_onChainVisibilityCha = onChainVisibilityChangeRef.current) === null || _onChainVisibilityCha === void 0 || _onChainVisibilityCha.call(onChainVisibilityChangeRef, ordered);
+		}, [
+			chainIds,
+			hidden,
+			isControlled
+		])
+	};
 }
 //#endregion
 //#region src/core/ProteinStructureViewer/utils/theme.ts
@@ -1036,7 +1604,7 @@ function useSubscribe(observable, handler) {
 */
 function useViewSetting(settings, select) {
 	const [value, setValue] = useState(() => select(settings.value));
-	useSubscribe(settings, (next) => setValue(select(next)));
+	useSubscribe(settings, (next) => setValue(() => select(next)));
 	return value;
 }
 //#endregion
@@ -1065,63 +1633,418 @@ const HOVER_THROTTLE_MS = 3 * 16.666;
 /** How long the copy button shows its confirmation state. */
 const COPIED_FEEDBACK_MS = 2e3;
 //#endregion
-//#region src/core/ProteinStructureViewer/hooks/usePlugin.ts
-/**
-* The plugin owning the React root this component renders in.
-*
-* Mol* renders its view components inside its own root and provides the plugin
-* through this context, which is what `PluginUIComponent` reads to populate
-* `this.plugin`.
-*/
-function usePlugin() {
-	return useContext(PluginReactContext);
-}
-//#endregion
-//#region src/core/ProteinStructureViewer/components/SequenceView/utils/residue.ts
-/** Reads the sequence index off a residue span, or undefined if it is not one. */
-function readSeqIdx(el) {
-	if (!el || !el.getAttribute) return void 0;
-	return el.hasAttribute("data-seqid") ? +el.getAttribute(SEQ_ID_ATTR) : void 0;
-}
-/**
-* Nearest ancestor that scrolls vertically, or null if none. Used to scope the
-* residue tooltip's hide-on-scroll listener to the sequence's own overflow
-* container instead of a global window listener.
-*/
-function getScrollParent(node) {
-	var _node$parentElement;
-	let el = (_node$parentElement = node === null || node === void 0 ? void 0 : node.parentElement) !== null && _node$parentElement !== void 0 ? _node$parentElement : null;
-	while (el) {
-		const overflowY = getComputedStyle(el).overflowY;
-		if (overflowY === "auto" || overflowY === "scroll") return el;
-		el = el.parentElement;
-	}
-	return null;
-}
-function getResidueClass(sequenceWrapper, seqIdx) {
-	return sequenceWrapper.isHighlighted(seqIdx) || sequenceWrapper.isSelected(seqIdx) || sequenceWrapper.isFocused(seqIdx) ? "msp-sequence-present msp-sequence-residue-active" : "msp-sequence-present msp-sequence-residue";
-}
-/**
-* The label shown above a residue: its author sequence id for atomic units,
-* or a 1-based position for coarse ones.
-*
-* `location` is a scratch object the caller reuses across residues, since this
-* runs once per numbered residue on every render.
-*/
-function getSequenceNumber(sequenceWrapper, seqIdx, location) {
-	let seqNum = "";
-	const loci = sequenceWrapper.getLoci(seqIdx);
-	const l = StructureElement.Loci.getFirstLocation(loci, location);
-	if (l) {
-		if (Unit.isAtomic(l.unit)) {
-			const seqId = StructureProperties.residue.auth_seq_id(l);
-			const insCode = StructureProperties.residue.pdbx_PDB_ins_code(l);
-			seqNum = `${seqId}${insCode ? insCode : ""}`;
-		} else if (Unit.isCoarse(l.unit)) seqNum = `${seqIdx + 1}`;
-	}
-	return seqNum;
-}
-/**
+//#region src/core/ProteinStructureViewer/components/SequenceView/style.ts
+/** Height of the fade that masks residues scrolling under the panel header. */
+const SCROLL_FADE_HEIGHT = 8;
+const SequencePanel = styled("div")`
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+
+  ${(props) => {
+	var _semanticColors$base, _props$backgroundColo, _semanticColors$base2;
+	const spaces = getSpaces(props);
+	const semanticColors = getSemanticColors(props);
+	return `
+      padding: ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px 0;
+      border-top: 1px solid ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base = semanticColors.base) === null || _semanticColors$base === void 0 ? void 0 : _semanticColors$base.divider};
+      background-color: ${(_props$backgroundColo = props.backgroundColor) !== null && _props$backgroundColo !== void 0 ? _props$backgroundColo : semanticColors === null || semanticColors === void 0 || (_semanticColors$base2 = semanticColors.base) === null || _semanticColors$base2 === void 0 ? void 0 : _semanticColors$base2.surfacePrimary};
+    `;
+}}
+`;
+const EmptyState = styled("div")`
+  ${fontBodyXs}
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+
+  ${(props) => {
+	var _props$backgroundColo2, _semanticColors$base3, _semanticColors$base4;
+	const spaces = getSpaces(props);
+	const semanticColors = getSemanticColors(props);
+	return `
+      padding: ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px;
+      background-color: ${(_props$backgroundColo2 = props.backgroundColor) !== null && _props$backgroundColo2 !== void 0 ? _props$backgroundColo2 : semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.surfaceSecondary};
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base4 = semanticColors.base) === null || _semanticColors$base4 === void 0 ? void 0 : _semanticColors$base4.textTertiaryOnDark};
+    `;
+}}
+`;
+const PanelHeader = styled("div")`
+  display: flex;
+  align-items: center;
+
+  ${(props) => {
+	const spaces = getSpaces(props);
+	return `
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xs}px;
+    `;
+}}
+`;
+const PanelTitle = styled("span")`
+  ${fontHeaderM}
+
+  ${(props) => {
+	var _semanticColors$base5;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base5 = semanticColors.base) === null || _semanticColors$base5 === void 0 ? void 0 : _semanticColors$base5.textPrimary};
+    `;
+}}
+`;
+const CopyButton = styled("button")`
+  display: flex;
+  align-items: center;
+  padding: 0;
+  border: none;
+  background: none;
+  cursor: default;
+
+  ${(props) => {
+	var _semanticColors$base6, _semanticColors$base7;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base6 = semanticColors.base) === null || _semanticColors$base6 === void 0 ? void 0 : _semanticColors$base6.ornamentSecondary};
+
+      &:hover {
+        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base7 = semanticColors.base) === null || _semanticColors$base7 === void 0 ? void 0 : _semanticColors$base7.textPrimary};
+      }
+    `;
+}}
+`;
+const ResidueCount = styled("div")`
+  display: flex;
+  align-items: center;
+  margin-left: auto;
+
+  ${(props) => {
+	const spaces = getSpaces(props);
+	return `
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxs}px;
+    `;
+}}
+`;
+const ResidueCountLabel = styled("span")`
+  ${fontBodyXs}
+
+  ${(props) => {
+	var _semanticColors$base8;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base8 = semanticColors.base) === null || _semanticColors$base8 === void 0 ? void 0 : _semanticColors$base8.textTertiary};
+    `;
+}}
+`;
+const ResidueCountValue = styled("span")`
+  ${fontBodyXs}
+
+  ${(props) => {
+	var _semanticColors$base9;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base9 = semanticColors.base) === null || _semanticColors$base9 === void 0 ? void 0 : _semanticColors$base9.textPrimary};
+    `;
+}}
+`;
+/**
+* Scroll region for the residue grid. The `::before` fade masks residues as
+* they scroll up under the header, so it has to start from whatever the panel
+* is painted with or it leaves a mismatched strip.
+*/
+const SequenceScroller = styled("div")`
+  position: relative;
+  flex: 1;
+  min-height: 0;
+
+  ${(props) => {
+	var _props$backgroundColo3, _semanticColors$base10;
+	const semanticColors = getSemanticColors(props);
+	return `
+      &::before {
+        content: "";
+        position: absolute;
+        inset-inline: 0;
+        top: 0;
+        z-index: 10;
+        height: ${SCROLL_FADE_HEIGHT}px;
+        pointer-events: none;
+        background: linear-gradient(to bottom, ${(_props$backgroundColo3 = props.backgroundColor) !== null && _props$backgroundColo3 !== void 0 ? _props$backgroundColo3 : semanticColors === null || semanticColors === void 0 || (_semanticColors$base10 = semanticColors.base) === null || _semanticColors$base10 === void 0 ? void 0 : _semanticColors$base10.surfacePrimary}, transparent);
+      }
+    `;
+}}
+`;
+/**
+* Residue spans are written to directly by `useResidueMarkers` rather than
+* re-rendered, so their hover and selection colors are set inline. Everything
+* here is the static styling underneath that: the monospace type, the pointer
+* affordance, and the superscript sequence numbers (which need their own color
+* rule, since they are nested inside residue spans and would otherwise inherit
+* the inline color).
+*/
+const SequenceScrollArea = styled("div")`
+  height: 100%;
+  overflow-y: auto;
+
+  .msp-sequence-wrapper {
+    ${fontCodeXs};
+    font-size: 11px;
+    line-height: 1.2;
+  }
+
+  .msp-sequence-present {
+    cursor: pointer;
+  }
+
+  ${(props) => {
+	var _semanticColors$base11;
+	const semanticColors = getSemanticColors(props);
+	return `
+      .msp-sequence-number {
+        font-size: 8px;
+        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base11 = semanticColors.base) === null || _semanticColors$base11 === void 0 ? void 0 : _semanticColors$base11.textTertiaryOnDark};
+      }
+    `;
+}}
+`;
+/**
+* Layout for one chain's residues.
+*
+* Residues are grouped into fixed-size sections, each one grid cell. The
+* equal-width auto-fill tracks and uniform gap keep the spacing between
+* sections identical on every row - including a partial last row, which keeps
+* the same column width (rather than stretching) and stacks from the leading
+* edge.
+*/
+const ResidueGrid = styled("div")`
+  user-select: none;
+  display: grid;
+  grid-template-columns: repeat(
+    auto-fill,
+    minmax(${10}ch, 1fr)
+  );
+  gap: 8px;
+  justify-items: start;
+  padding-top: 6px;
+
+  /* Section wrappers, so a section's letters never split across lines. */
+  & > span {
+    white-space: nowrap;
+  }
+
+  .msp-sequence-present {
+    position: relative;
+    display: inline-block;
+    width: 1ch;
+    /*
+     * Reserves room above the letter for its superscript sequence number.
+     * content-box clipping keeps the active fill off that gutter, so a
+     * highlighted residue does not tint the number.
+     */
+    padding-top: 8px;
+    background-clip: content-box;
+    text-align: center;
+  }
+
+  .msp-sequence-number {
+    position: absolute;
+    top: 0;
+    line-height: 1.2;
+    white-space: nowrap;
+    pointer-events: none;
+  }
+`;
+/**
+* The row above each chain's grid: a visibility toggle and the chain's name.
+*
+* A structure with more than one chain renders one grid per chain, and without
+* a caption between them the grids read as a single continuous protein. The
+* controls sit here rather than only in the legend because this is where a
+* reader is already looking at one chain at a time.
+*/
+const ChainHeaderRow = styled("div")`
+  display: flex;
+  align-items: center;
+
+  ${(props) => {
+	const spaces = getSpaces(props);
+	return `
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxs}px;
+      margin-top: ${spaces === null || spaces === void 0 ? void 0 : spaces.xs}px;
+      margin-bottom: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxxs}px;
+    `;
+}}
+`;
+/**
+* Shows or hides the chain's cartoon in the 3D view. Full strength even while
+* the chain is hidden, since it is the way back.
+*/
+const ChainVisibilityToggle = styled("button")`
+  display: flex;
+  align-items: center;
+  padding: 0;
+  border: none;
+  background: none;
+  cursor: pointer;
+
+  ${(props) => {
+	var _semanticColors$base12, _semanticColors$base13;
+	const semanticColors = getSemanticColors(props);
+	return `
+      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base12 = semanticColors.base) === null || _semanticColors$base12 === void 0 ? void 0 : _semanticColors$base12.textTertiaryOnDark};
+
+      &:hover {
+        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base13 = semanticColors.base) === null || _semanticColors$base13 === void 0 ? void 0 : _semanticColors$base13.textPrimary};
+      }
+
+      svg {
+        display: block;
+      }
+    `;
+}}
+`;
+/**
+* The chain's name, and a button because it also selects the chain: the caption
+* is already the one thing on screen that stands for a whole chain, so clicking
+* it is where a reader looks to select one. Clicking it again clears it.
+*/
+const ChainLabel = styled("button")`
+  ${fontBodyXs}
+
+  padding: 0;
+  border: none;
+  background: none;
+  text-align: left;
+
+  ${(props) => {
+	var _semanticColors$base14, _semanticColors$base15, _semanticColors$base16;
+	const semanticColors = getSemanticColors(props);
+	const resting = props.isSelected ? semanticColors === null || semanticColors === void 0 || (_semanticColors$base14 = semanticColors.base) === null || _semanticColors$base14 === void 0 ? void 0 : _semanticColors$base14.textPrimary : semanticColors === null || semanticColors === void 0 || (_semanticColors$base15 = semanticColors.base) === null || _semanticColors$base15 === void 0 ? void 0 : _semanticColors$base15.textSecondary;
+	return `
+      color: ${resting};
+      cursor: ${props.isHidden ? "default" : "pointer"};
+      font-weight: ${props.isSelected ? 600 : 500};
+      opacity: ${props.isHidden ? .4 : 1};
+
+      &:hover {
+        color: ${props.isHidden ? resting : semanticColors === null || semanticColors === void 0 || (_semanticColors$base16 = semanticColors.base) === null || _semanticColors$base16 === void 0 ? void 0 : _semanticColors$base16.textPrimary};
+      }
+    `;
+}}
+`;
+/**
+* Wraps a chain whose 3D cartoon is hidden. The grid stays in place and stays
+* interactive - the sequence is still the sequence - but is dimmed to match the
+* chain being absent from the structure beside it. Dimmed rather than removed
+* so the panel does not reflow every time a chain is toggled.
+*/
+const HiddenChainGroup = styled("div")`
+  opacity: 0.4;
+`;
+//#endregion
+//#region src/core/ProteinStructureViewer/components/SequenceView/components/ChainHeader/index.tsx
+/**
+* The row above one chain's residue grid: a visibility toggle and the chain's
+* name, which selects it.
+*
+* The name is a toggle rather than a one-way switch, so the tooltip says which
+* way the next click goes - offering to select a chain that is already selected
+* would be telling the reader the wrong thing. A hidden chain cannot be
+* selected at all, so the name stops being a button then: there is no geometry
+* to focus, and the toggle beside it is what the reader wants instead.
+*/
+function ChainHeader({ chainId, isHidden, isSelected, label, onHover, onSelect, onToggle }) {
+	return /* @__PURE__ */ jsxs(ChainHeaderRow, {
+		onBlur: () => onHover === null || onHover === void 0 ? void 0 : onHover(null),
+		onFocus: () => onHover === null || onHover === void 0 ? void 0 : onHover(chainId),
+		onMouseEnter: () => onHover === null || onHover === void 0 ? void 0 : onHover(chainId),
+		onMouseLeave: () => onHover === null || onHover === void 0 ? void 0 : onHover(null),
+		children: [/* @__PURE__ */ jsx(Tooltip, {
+			arrow: true,
+			placement: "top",
+			title: isHidden ? `Chain ${label} is hidden` : `Click to ${isSelected ? "deselect" : "select"} Chain ${label}`,
+			textAlign: "left",
+			children: /* @__PURE__ */ jsxs(ChainLabel, {
+				"aria-pressed": isSelected,
+				disabled: isHidden,
+				isHidden,
+				isSelected,
+				onClick: () => onSelect === null || onSelect === void 0 ? void 0 : onSelect(chainId),
+				type: "button",
+				children: ["Chain ", label]
+			})
+		}), onToggle && /* @__PURE__ */ jsx(Tooltip, {
+			arrow: true,
+			placement: "top",
+			title: `${isHidden ? "Show" : "Hide"} Chain ${label}`,
+			children: /* @__PURE__ */ jsx(ChainVisibilityToggle, {
+				"aria-label": `${isHidden ? "Show" : "Hide"} chain ${label}`,
+				"aria-pressed": isHidden,
+				onClick: () => onToggle(chainId),
+				type: "button",
+				children: isHidden ? /* @__PURE__ */ jsx(EyeSlashIcon, { size: 12 }) : /* @__PURE__ */ jsx(EyeIcon, { size: 12 })
+			})
+		})]
+	});
+}
+//#endregion
+//#region src/core/ProteinStructureViewer/hooks/usePlugin.ts
+/**
+* The plugin owning the React root this component renders in.
+*
+* Mol* renders its view components inside its own root and provides the plugin
+* through this context, which is what `PluginUIComponent` reads to populate
+* `this.plugin`.
+*/
+function usePlugin() {
+	return useContext(PluginReactContext);
+}
+//#endregion
+//#region src/core/ProteinStructureViewer/components/SequenceView/utils/residue.ts
+/** Reads the sequence index off a residue span, or undefined if it is not one. */
+function readSeqIdx(el) {
+	if (!el || !el.getAttribute) return void 0;
+	return el.hasAttribute("data-seqid") ? +el.getAttribute(SEQ_ID_ATTR) : void 0;
+}
+/**
+* Nearest ancestor that scrolls vertically, or null if none. Used to scope the
+* residue tooltip's hide-on-scroll listener to the sequence's own overflow
+* container instead of a global window listener.
+*/
+function getScrollParent(node) {
+	var _node$parentElement;
+	let el = (_node$parentElement = node === null || node === void 0 ? void 0 : node.parentElement) !== null && _node$parentElement !== void 0 ? _node$parentElement : null;
+	while (el) {
+		const overflowY = getComputedStyle(el).overflowY;
+		if (overflowY === "auto" || overflowY === "scroll") return el;
+		el = el.parentElement;
+	}
+	return null;
+}
+function getResidueClass(sequenceWrapper, seqIdx) {
+	return sequenceWrapper.isHighlighted(seqIdx) || sequenceWrapper.isSelected(seqIdx) || sequenceWrapper.isFocused(seqIdx) ? "msp-sequence-present msp-sequence-residue-active" : "msp-sequence-present msp-sequence-residue";
+}
+/**
+* The label shown above a residue: its author sequence id for atomic units,
+* or a 1-based position for coarse ones.
+*
+* `location` is a scratch object the caller reuses across residues, since this
+* runs once per numbered residue on every render.
+*/
+function getSequenceNumber(sequenceWrapper, seqIdx, location) {
+	let seqNum = "";
+	const loci = sequenceWrapper.getLoci(seqIdx);
+	const l = StructureElement.Loci.getFirstLocation(loci, location);
+	if (l) {
+		if (Unit.isAtomic(l.unit)) {
+			const seqId = StructureProperties.residue.auth_seq_id(l);
+			const insCode = StructureProperties.residue.pdbx_PDB_ins_code(l);
+			seqNum = `${seqId}${insCode ? insCode : ""}`;
+		} else if (Unit.isCoarse(l.unit)) seqNum = `${seqIdx + 1}`;
+	}
+	return seqNum;
+}
+/**
 * How often a sequence number is drawn above the residues.
 *
 * Long sequences get one every ten residues. Short ones number every residue,
@@ -1226,6 +2149,63 @@ function useResidueMarkers({ containerRef, residueColors, sequenceWrapper }) {
 	});
 }
 //#endregion
+//#region src/core/ProteinStructureViewer/utils/residueRef.ts
+/**
+* Reads the residue a loci points at, or null when it points at nothing the
+* viewer can address.
+*
+* `index` comes from Mol*'s residue key, which counts residues in file order
+* from zero and is the same counter `injectPlddtIntoPdb` walks. Deriving it
+* from the residue's *number* instead would tie it to how the file happens to
+* be numbered: a crop beginning at residue 200 would index `plddt` at 199, and
+* a file numbering each chain from 1 would give two residues the same index.
+*/
+function residueRefFromLoci(loci) {
+	var _StructureProperties$;
+	const location = StructureElement.Location.create(void 0);
+	const firstLoc = StructureElement.Loci.getFirstLocation(loci, location);
+	if (!firstLoc) return null;
+	return {
+		chainId: StructureProperties.chain.auth_asym_id(firstLoc),
+		compId: StructureProperties.atom.label_comp_id(firstLoc),
+		insCode: (_StructureProperties$ = StructureProperties.residue.pdbx_PDB_ins_code(firstLoc)) !== null && _StructureProperties$ !== void 0 ? _StructureProperties$ : "",
+		index: StructureProperties.residue.key(firstLoc),
+		seqId: StructureProperties.residue.auth_seq_id(firstLoc)
+	};
+}
+/**
+* Every residue a loci covers, as a selection the consumer can echo back.
+*
+* The counterpart to `residueRefFromLoci`, which names only the first: a drag
+* across the sequence hands Mol* a range, and reporting its first residue
+* alone would turn a range the user drew into a single-residue selection.
+*
+* Reported as residues rather than as chains even when a whole chain is
+* covered. What the user drew is a span of residues, and calling it a chain
+* because it happens to end where one does would change the selection's meaning
+* on a structure where the two coincide.
+*/
+function selectionFromLoci(loci) {
+	const location = StructureElement.Location.create(loci.structure);
+	const residues = /* @__PURE__ */ new Set();
+	for (const element of loci.elements) {
+		location.unit = element.unit;
+		OrderedSet.forEach(element.indices, (i) => {
+			location.element = element.unit.elements[i];
+			residues.add(StructureProperties.residue.key(location));
+		});
+	}
+	return { residues: [...residues].sort((a, b) => a - b) };
+}
+/**
+* How a residue is named in the readout, e.g. `"LYS 111"`. Takes the number and
+* the insertion code from the file so that the readout and the sequence panel
+* beneath it agree on what to call a residue.
+*/
+function residueLabel(residue) {
+	return `${residue.compId} ${residue.seqId}${residue.insCode}`;
+}
+//#endregion
 //#region src/core/ProteinStructureViewer/components/SequenceView/utils/loci.ts
 /** The loci for a residue, or undefined when there is no residue there. */
 function getLoci(sequenceWrapper, seqIdx) {
@@ -1238,25 +2218,28 @@ function getLoci(sequenceWrapper, seqIdx) {
 * Extends a loci to the range between the mouse-down anchor and the current
 * residue, so dragging across the sequence selects a contiguous span.
 *
-* Element indices are only comparable within a single unit, and the range below
-* is built on the anchor's unit alone. So a drag is only extended when both
-* endpoints are a single element of the same unit; anything else -- different
-* units, or an endpoint spanning several because the chain has more than one
-* symmetry operator -- is left unextended rather than collapsed onto one unit
-* and silently reinterpreted as a different range.
+* The span is measured in the viewer's own residue index - position in file
+* order across the whole structure - rather than in element indices, which are
+* unit-local and so cannot describe a range reaching from one chain into the
+* next. Measuring it the way every other residue-keyed API measures it is what
+* lets a drag cross a chain break, and it means a range covers exactly the
+* residues whose indices lie between its ends.
+*
+* An endpoint that names no residue leaves the drag unextended rather than
+* guessing at where it was. An endpoint spanning several units - a chain with
+* more than one symmetry operator - is fine: each copy of a residue carries the
+* same index, so the span is the same either way and resolves back across all
+* of them.
 */
 function extendToRange(loci, anchor) {
-	if (anchor.elements.length !== 1 || loci.elements.length !== 1) return loci;
-	const ref = anchor.elements[0];
-	const ext = loci.elements[0];
-	if (!ref || !ext) return loci;
-	if (ref.unit !== ext.unit) return loci;
-	const min = Math.min(OrderedSet.min(ref.indices), OrderedSet.min(ext.indices));
-	const max = Math.max(OrderedSet.max(ref.indices), OrderedSet.max(ext.indices));
-	return StructureElement.Loci(loci.structure, [{
-		indices: OrderedSet.ofRange(min, max),
-		unit: ref.unit
-	}]);
+	var _lociForResidueRange;
+	const from = residueRefFromLoci(anchor);
+	const to = residueRefFromLoci(loci);
+	if (!from || !to) return loci;
+	if (from.index === to.index) return loci;
+	const min = Math.min(from.index, to.index);
+	const max = Math.max(from.index, to.index);
+	return (_lociForResidueRange = lociForResidueRange(loci.structure, min, max)) !== null && _lociForResidueRange !== void 0 ? _lociForResidueRange : loci;
 }
 //#endregion
 //#region src/core/ProteinStructureViewer/components/SequenceView/hooks/useHoveredResidue.ts
@@ -1343,34 +2326,75 @@ function useLociDispatch() {
 	}), [click, hover]);
 }
 //#endregion
+//#region src/core/ProteinStructureViewer/components/SequenceView/hooks/useSequenceDrag.ts
+const SequenceDragContext = createContext({
+	clearAnchor: () => void 0,
+	getAnchor: () => void 0,
+	setAnchor: () => void 0
+});
+const SequenceDragProvider = SequenceDragContext.Provider;
+/**
+* The anchor a drag across the sequence started from, shared by every chain's
+* grid.
+*
+* It has to live above the grids rather than inside one. A complex renders one
+* grid per chain, so a drag that begins on the target and ends on the binder
+* starts in one component and finishes in another; an anchor held by the grid
+* it started in is not there to be read by the grid it ends in, and the drag
+* would be reported as a plain click on whatever it landed on.
+*
+* Held in a ref rather than state: it changes on mouse-down and mouse-up, and
+* nothing renders from it, so re-rendering every residue in the panel twice per
+* drag would buy nothing.
+*/
+function useCreateSequenceDrag() {
+	const anchorRef = useRef(void 0);
+	const getAnchor = useCallback(() => anchorRef.current, []);
+	const setAnchor = useCallback((anchor) => {
+		anchorRef.current = anchor;
+	}, []);
+	const clearAnchor = useCallback(() => {
+		anchorRef.current = void 0;
+	}, []);
+	return useMemo(() => ({
+		clearAnchor,
+		getAnchor,
+		setAnchor
+	}), [
+		clearAnchor,
+		getAnchor,
+		setAnchor
+	]);
+}
+function useSequenceDrag() {
+	return useContext(SequenceDragContext);
+}
+//#endregion
 //#region src/core/ProteinStructureViewer/components/SequenceView/hooks/useResidueSelection.ts
 /**
 * Turns a press and release on the grid into a selection: one residue when
-* both land on the same one, otherwise the contiguous range dragged across.
+* both land on the same one, otherwise the contiguous range dragged across -
+* which the panel-level anchor lets reach into another chain's grid.
 */
 function useResidueSelection({ sequenceWrapper }) {
-	const anchorRef = useRef(void 0);
+	const { clearAnchor, getAnchor, setAnchor } = useSequenceDrag();
 	const { click } = useLociDispatch();
 	const onMouseDown = (e) => {
 		e.stopPropagation();
-		anchorRef.current = getLoci(sequenceWrapper, readSeqIdx(e.target));
+		setAnchor(getLoci(sequenceWrapper, readSeqIdx(e.target)));
 	};
 	const onMouseUp = (e) => {
 		e.stopPropagation();
-		const anchor = anchorRef.current;
+		const anchor = getAnchor();
 		if (anchor === void 0) return;
 		const loci = getLoci(sequenceWrapper, readSeqIdx(e.target));
 		if (loci) {
 			const dragged = !StructureElement.Loci.areEqual(anchor, loci);
 			click(loci, getButtons(e.nativeEvent), getButton(e.nativeEvent), getModifiers(e.nativeEvent), dragged ? anchor : void 0);
 		}
-		anchorRef.current = void 0;
+		clearAnchor();
 	};
 	return {
-		clearAnchor: () => {
-			anchorRef.current = void 0;
-		},
-		getAnchor: () => anchorRef.current,
 		onMouseDown,
 		onMouseUp
 	};
@@ -1392,7 +2416,8 @@ function useResiduePointer({ containerRef, sequenceWrapper }) {
 		containerRef,
 		sequenceWrapper
 	});
-	const { clearAnchor, getAnchor, onMouseDown, onMouseUp } = useResidueSelection({ sequenceWrapper });
+	const { getAnchor } = useSequenceDrag();
+	const { onMouseDown, onMouseUp } = useResidueSelection({ sequenceWrapper });
 	const queueRef = useRef(null);
 	if (queueRef.current === null) queueRef.current = new Subject();
 	const queue = queueRef.current;
@@ -1432,9 +2457,14 @@ function useResiduePointer({ containerRef, sequenceWrapper }) {
 		}
 		hover(getLoci(sequenceWrapper, seqIdx), ButtonsType.Flag.None, ButtonsType.Flag.None, getModifiers(e.nativeEvent), anchor);
 	};
+	/**
+	* Leaving one grid is not the end of a drag: on a complex the next chain's
+	* grid is a separate element, so a drag from the target into the binder
+	* leaves this one on its way. The anchor is therefore left alone here and
+	* dropped by the release, or by the pointer leaving the panel altogether.
+	*/
 	const onMouseLeave = (e) => {
 		e.stopPropagation();
-		clearAnchor();
 		hide();
 		releaseHover(e);
 	};
@@ -1450,247 +2480,6 @@ function useResiduePointer({ containerRef, sequenceWrapper }) {
 	};
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/components/SequenceView/style.ts
-/** Height of the fade that masks residues scrolling under the panel header. */
-const SCROLL_FADE_HEIGHT = 8;
-const SequencePanel = styled("div")`
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-
-  ${(props) => {
-	var _semanticColors$base, _props$backgroundColo, _semanticColors$base2;
-	const spaces = getSpaces(props);
-	const semanticColors = getSemanticColors(props);
-	return `
-      padding: ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px 0;
-      border-top: 1px solid ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base = semanticColors.base) === null || _semanticColors$base === void 0 ? void 0 : _semanticColors$base.divider};
-      background-color: ${(_props$backgroundColo = props.backgroundColor) !== null && _props$backgroundColo !== void 0 ? _props$backgroundColo : semanticColors === null || semanticColors === void 0 || (_semanticColors$base2 = semanticColors.base) === null || _semanticColors$base2 === void 0 ? void 0 : _semanticColors$base2.surfacePrimary};
-    `;
-}}
-`;
-const EmptyState = styled("div")`
-  ${fontBodyXs}
-
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100%;
-
-  ${(props) => {
-	var _props$backgroundColo2, _semanticColors$base3, _semanticColors$base4;
-	const spaces = getSpaces(props);
-	const semanticColors = getSemanticColors(props);
-	return `
-      padding: ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px;
-      background-color: ${(_props$backgroundColo2 = props.backgroundColor) !== null && _props$backgroundColo2 !== void 0 ? _props$backgroundColo2 : semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.surfaceSecondary};
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base4 = semanticColors.base) === null || _semanticColors$base4 === void 0 ? void 0 : _semanticColors$base4.textTertiaryOnDark};
-    `;
-}}
-`;
-const PanelHeader = styled("div")`
-  display: flex;
-  align-items: center;
-
-  ${(props) => {
-	const spaces = getSpaces(props);
-	return `
-      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xs}px;
-    `;
-}}
-`;
-const PanelTitle = styled("span")`
-  ${fontHeaderM}
-
-  ${(props) => {
-	var _semanticColors$base5;
-	const semanticColors = getSemanticColors(props);
-	return `
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base5 = semanticColors.base) === null || _semanticColors$base5 === void 0 ? void 0 : _semanticColors$base5.textPrimary};
-    `;
-}}
-`;
-const CopyButton = styled("button")`
-  display: flex;
-  align-items: center;
-  padding: 0;
-  border: none;
-  background: none;
-  cursor: default;
-
-  ${(props) => {
-	var _semanticColors$base6, _semanticColors$base7;
-	const semanticColors = getSemanticColors(props);
-	return `
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base6 = semanticColors.base) === null || _semanticColors$base6 === void 0 ? void 0 : _semanticColors$base6.ornamentSecondary};
-
-      &:hover {
-        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base7 = semanticColors.base) === null || _semanticColors$base7 === void 0 ? void 0 : _semanticColors$base7.textPrimary};
-      }
-    `;
-}}
-`;
-const ResidueCount = styled("div")`
-  display: flex;
-  align-items: center;
-  margin-left: auto;
-
-  ${(props) => {
-	const spaces = getSpaces(props);
-	return `
-      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxs}px;
-    `;
-}}
-`;
-const ResidueCountLabel = styled("span")`
-  ${fontBodyXs}
-
-  ${(props) => {
-	var _semanticColors$base8;
-	const semanticColors = getSemanticColors(props);
-	return `
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base8 = semanticColors.base) === null || _semanticColors$base8 === void 0 ? void 0 : _semanticColors$base8.textTertiary};
-    `;
-}}
-`;
-const ResidueCountValue = styled("span")`
-  ${fontBodyXs}
-
-  ${(props) => {
-	var _semanticColors$base9;
-	const semanticColors = getSemanticColors(props);
-	return `
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base9 = semanticColors.base) === null || _semanticColors$base9 === void 0 ? void 0 : _semanticColors$base9.textPrimary};
-    `;
-}}
-`;
-/**
-* Scroll region for the residue grid. The `::before` fade masks residues as
-* they scroll up under the header, so it has to start from whatever the panel
-* is painted with or it leaves a mismatched strip.
-*/
-const SequenceScroller = styled("div")`
-  position: relative;
-  flex: 1;
-  min-height: 0;
-
-  ${(props) => {
-	var _props$backgroundColo3, _semanticColors$base10;
-	const semanticColors = getSemanticColors(props);
-	return `
-      &::before {
-        content: "";
-        position: absolute;
-        inset-inline: 0;
-        top: 0;
-        z-index: 10;
-        height: ${SCROLL_FADE_HEIGHT}px;
-        pointer-events: none;
-        background: linear-gradient(to bottom, ${(_props$backgroundColo3 = props.backgroundColor) !== null && _props$backgroundColo3 !== void 0 ? _props$backgroundColo3 : semanticColors === null || semanticColors === void 0 || (_semanticColors$base10 = semanticColors.base) === null || _semanticColors$base10 === void 0 ? void 0 : _semanticColors$base10.surfacePrimary}, transparent);
-      }
-    `;
-}}
-`;
-/**
-* Residue spans are written to directly by `useResidueMarkers` rather than
-* re-rendered, so their hover and selection colors are set inline. Everything
-* here is the static styling underneath that: the monospace type, the pointer
-* affordance, and the superscript sequence numbers (which need their own color
-* rule, since they are nested inside residue spans and would otherwise inherit
-* the inline color).
-*/
-const SequenceScrollArea = styled("div")`
-  height: 100%;
-  overflow-y: auto;
-
-  .msp-sequence-wrapper {
-    ${fontCodeXs};
-    font-size: 11px;
-    line-height: 1.2;
-  }
-
-  .msp-sequence-present {
-    cursor: pointer;
-  }
-
-  ${(props) => {
-	var _semanticColors$base11;
-	const semanticColors = getSemanticColors(props);
-	return `
-      .msp-sequence-number {
-        font-size: 8px;
-        color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base11 = semanticColors.base) === null || _semanticColors$base11 === void 0 ? void 0 : _semanticColors$base11.textTertiaryOnDark};
-      }
-    `;
-}}
-`;
-/**
-* Layout for one chain's residues.
-*
-* Residues are grouped into fixed-size sections, each one grid cell. The
-* equal-width auto-fill tracks and uniform gap keep the spacing between
-* sections identical on every row - including a partial last row, which keeps
-* the same column width (rather than stretching) and stacks from the leading
-* edge.
-*/
-const ResidueGrid = styled("div")`
-  user-select: none;
-  display: grid;
-  grid-template-columns: repeat(
-    auto-fill,
-    minmax(${10}ch, 1fr)
-  );
-  gap: 8px;
-  justify-items: start;
-  padding-top: 6px;
-
-  /* Section wrappers, so a section's letters never split across lines. */
-  & > span {
-    white-space: nowrap;
-  }
-
-  .msp-sequence-present {
-    position: relative;
-    display: inline-block;
-    width: 1ch;
-    /*
-     * Reserves room above the letter for its superscript sequence number.
-     * content-box clipping keeps the active fill off that gutter, so a
-     * highlighted residue does not tint the number.
-     */
-    padding-top: 8px;
-    background-clip: content-box;
-    text-align: center;
-  }
-
-  .msp-sequence-number {
-    position: absolute;
-    top: 0;
-    line-height: 1.2;
-    white-space: nowrap;
-    pointer-events: none;
-  }
-`;
-/**
-* Caption naming the chain a sequence grid belongs to. A structure with more
-* than one chain renders one grid per chain, and without a caption between them
-* the grids read as a single continuous protein.
-*/
-const ChainLabel = styled("div")`
-  ${fontBodyXs}
-
-  ${(props) => {
-	var _semanticColors$base12;
-	const spaces = getSpaces(props);
-	const semanticColors = getSemanticColors(props);
-	return `
-      margin-top: ${spaces === null || spaces === void 0 ? void 0 : spaces.xs}px;
-      margin-bottom: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxxs}px;
-      color: ${semanticColors === null || semanticColors === void 0 || (_semanticColors$base12 = semanticColors.base) === null || _semanticColors$base12 === void 0 ? void 0 : _semanticColors$base12.textSecondary};
-    `;
-}}
-`;
-//#endregion
 //#region src/core/ProteinStructureViewer/components/SequenceView/components/ResidueTooltip/index.tsx
 var _getSpaces$m, _getSpaces;
 /**
@@ -1912,10 +2701,37 @@ function buildParams(state) {
 		structure: ParamDefinition.Select(structureOptions.options[0][0], structureOptions.options, { shortLabel: true })
 	};
 }
-/** One entry per chain, in Mol*'s entity / chain / operator order. */
+/**
+* The file's own name for a chain group, or `""` when the structure holds no
+* unit for it. Mol* groups its sequence panel by `chainGroupId`, but every
+* chain-level prop on the viewer is keyed by `auth_asym_id`, so the two have
+* to be bridged through the structure itself.
+*/
+function authAsymIdFor(structure, chainGroupId) {
+	const location = StructureElement.Location.create(structure);
+	for (const unit of structure.units) {
+		if (unit.chainGroupId !== chainGroupId) continue;
+		const element = unit.elements[0];
+		if (element === void 0) continue;
+		StructureElement.Location.set(location, structure, unit, element);
+		return StructureProperties.chain.auth_asym_id(location);
+	}
+	return "";
+}
+/**
+* One entry per polymer chain, in Mol*'s entity / chain / operator order.
+*
+* Polymer entities only. The heteroatoms on a chain are separate entities, and
+* Mol* would hand back a caption and a grid for each - a myoglobin listing
+* "Chain A" and then two more headers, both reading "Chain A_1 [auth A]", one
+* holding the heme and one the hydroxide. They are drawn in the 3D view and
+* they are not sequence, and a caption per ligand offers a chain toggle for
+* something that is not a chain.
+*/
 function buildEntries(structure, selection, _params) {
 	const entries = [];
-	for (const [modelEntityId] of getModelEntityOptions(structure)) for (const [chainGroupId, cLabel] of getChainOptions(structure, modelEntityId)) for (const [operatorKey] of getOperatorOptions(structure, modelEntityId, chainGroupId)) entries.push({
+	for (const [modelEntityId] of getModelEntityOptions(structure, true)) for (const [chainGroupId, cLabel] of getChainOptions(structure, modelEntityId)) for (const [operatorKey] of getOperatorOptions(structure, modelEntityId, chainGroupId)) entries.push({
+		chainId: authAsymIdFor(structure, chainGroupId),
 		id: `${modelEntityId}:${chainGroupId}:${operatorKey}`,
 		label: cLabel,
 		wrapper: getSequenceWrapper({
@@ -1984,8 +2800,14 @@ function createSequenceView(viewSettings) {
 	return function SequenceView() {
 		const { mode, theme } = useMolstarTheme(viewSettings);
 		const backgroundColor = useViewSetting(viewSettings, (s) => s.sequenceViewerBackgroundColor);
+		const hiddenChains = useViewSetting(viewSettings, (s) => s.hiddenChains);
+		const onChainHover = useViewSetting(viewSettings, (s) => s.onChainHover);
+		const onChainSelect = useViewSetting(viewSettings, (s) => s.onChainSelect);
+		const onChainToggle = useViewSetting(viewSettings, (s) => s.onChainToggle);
+		const selectedChains = useViewSetting(viewSettings, (s) => s.selectedChains);
 		const { entries, isEmpty, residueCount } = useSequenceWrappers();
 		const { copied, copySequence } = useCopySequence(entries);
+		const drag = useCreateSequenceDrag();
 		if (isEmpty) return /* @__PURE__ */ jsx(ThemeProvider, {
 			theme,
 			children: /* @__PURE__ */ jsx(EmptyState, {
@@ -2016,16 +2838,33 @@ function createSequenceView(viewSettings) {
 					/* @__PURE__ */ jsxs(ResidueCount, { children: [/* @__PURE__ */ jsx(ResidueCountLabel, { children: "Residues" }), /* @__PURE__ */ jsx(ResidueCountValue, { children: residueCount })] })
 				] }), /* @__PURE__ */ jsx(SequenceScroller, {
 					backgroundColor,
-					children: /* @__PURE__ */ jsx(SequenceScrollArea, {
-						className: "msp-sequence msp-sequence-wrapper-non-empty",
-						children: entries.map((s) => /* @__PURE__ */ jsxs(Fragment, { children: [showChainLabels && /* @__PURE__ */ jsx(ChainLabel, { children: s.label }), typeof s.wrapper === "string" ? /* @__PURE__ */ jsx("div", {
-							className: "msp-sequence-wrapper",
-							children: s.wrapper
-						}) : /* @__PURE__ */ jsx(Sequence, {
-							chainLabel: showChainLabels ? s.label : void 0,
-							residueColors,
-							sequenceWrapper: s.wrapper
-						})] }, s.id))
+					children: /* @__PURE__ */ jsx(SequenceDragProvider, {
+						value: drag,
+						children: /* @__PURE__ */ jsx(SequenceScrollArea, {
+							className: "msp-sequence msp-sequence-wrapper-non-empty",
+							onMouseLeave: drag.clearAnchor,
+							children: entries.map((s) => {
+								var _hiddenChains$has, _selectedChains$has;
+								const hidden = (_hiddenChains$has = hiddenChains === null || hiddenChains === void 0 ? void 0 : hiddenChains.has(s.chainId)) !== null && _hiddenChains$has !== void 0 ? _hiddenChains$has : false;
+								const grid = typeof s.wrapper === "string" ? /* @__PURE__ */ jsx("div", {
+									className: "msp-sequence-wrapper",
+									children: s.wrapper
+								}) : /* @__PURE__ */ jsx(Sequence, {
+									chainLabel: showChainLabels ? s.label : void 0,
+									residueColors,
+									sequenceWrapper: s.wrapper
+								});
+								return /* @__PURE__ */ jsxs(Fragment, { children: [showChainLabels && /* @__PURE__ */ jsx(ChainHeader, {
+									chainId: s.chainId,
+									isHidden: hidden,
+									isSelected: (_selectedChains$has = selectedChains === null || selectedChains === void 0 ? void 0 : selectedChains.has(s.chainId)) !== null && _selectedChains$has !== void 0 ? _selectedChains$has : false,
+									label: s.label,
+									onHover: onChainHover,
+									onSelect: onChainSelect,
+									onToggle: onChainToggle
+								}), hidden ? /* @__PURE__ */ jsx(HiddenChainGroup, { children: grid }) : grid] }, s.id);
+							})
+						})
 					})
 				})]
 			})
@@ -2033,21 +2872,71 @@ function createSequenceView(viewSettings) {
 	};
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/components/Viewport/constants.ts
+//#region src/core/ProteinStructureViewer/utils/axes.ts
 /**
-* Fraction of the bounding sphere radius within which the camera still counts
-* as sitting at the default view, absorbing easing and float error.
+* 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 DEFAULT_VIEW_TOLERANCE = .02;
+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/components/Viewport/utils/camera.ts
-/** True when the camera's zoom/center differs from the default fit. */
-function isZoomedOffDefault(canvas3d) {
-	const { center, radius } = canvas3d.boundingSphereVisible;
-	if (radius <= 0) return false;
-	const { state } = canvas3d.camera;
-	const tolerance = radius * DEFAULT_VIEW_TOLERANCE;
-	return Math.abs(state.radius - radius) > tolerance || Vec3.distance(state.target, center) > tolerance;
+//#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 \0@oxc-project+runtime@0.134.0/helpers/esm/asyncToGenerator.js
@@ -2076,6 +2965,88 @@ function _asyncToGenerator(n) {
 	};
 }
 //#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
+* as sitting at the default view, absorbing easing and float error.
+*/
+const DEFAULT_VIEW_TOLERANCE = .02;
+//#endregion
+//#region src/core/ProteinStructureViewer/components/Viewport/utils/camera.ts
+/** True when the camera's zoom/center differs from the default fit. */
+function isZoomedOffDefault(canvas3d) {
+	const { center, radius } = canvas3d.boundingSphereVisible;
+	if (radius <= 0) return false;
+	const { state } = canvas3d.camera;
+	const tolerance = radius * DEFAULT_VIEW_TOLERANCE;
+	return Math.abs(state.radius - radius) > tolerance || Vec3.distance(state.target, center) > tolerance;
+}
+//#endregion
 //#region src/core/ProteinStructureViewer/components/Viewport/hooks/useCameraReset.ts
 /**
 * Tracks whether the camera has moved off the default view, and puts it back.
@@ -2176,16 +3147,24 @@ function useCameraReset() {
 /**
 * Pinned to the lower-left of the viewport, clear of the sequence panel below
 * and the axes widget in the corner.
+*
+* Anchored by its bottom edge, so the buttons stack upwards: the last one
+* stays put where a reader last saw it, and an earlier one appearing or going
+* does not move the rest. Reset comes first in the markup and so sits above
+* capture.
 */
-const ResetCameraSlot = styled("div")`
+const ViewportButtonStack = styled("div")`
   position: absolute;
   bottom: 48px;
   z-index: 10;
+  display: flex;
+  flex-direction: column;
 
   ${(props) => {
 	const spaces = getSpaces(props);
 	return `
       left: ${spaces === null || spaces === void 0 ? void 0 : spaces.m}px;
+      gap: ${spaces === null || spaces === void 0 ? void 0 : spaces.xxs}px;
     `;
 }}
 `;
@@ -2203,8 +3182,30 @@ const ResetCameraSlot = styled("div")`
 */
 function createViewportView(viewSettings) {
 	return function ViewportWithReset() {
+		const plugin = usePlugin();
 		const { theme } = useMolstarTheme(viewSettings);
 		const { cameraChanged, resetCamera } = useCameraReset();
+		const showAxes = useViewSetting(viewSettings, (s) => {
+			var _s$showAxes;
+			return (_s$showAxes = s.showAxes) !== null && _s$showAxes !== void 0 ? _s$showAxes : true;
+		});
+		const download = useViewSetting(viewSettings, (s) => s.download);
+		/**
+		* Disabled while a capture is in flight. A high resolution takes long
+		* enough to click twice through, and each click renders its own pass.
+		*/
+		const [downloading, setDownloading] = useState(false);
+		const captureImage = useCallback(_asyncToGenerator(function* () {
+			if (!download) return;
+			setDownloading(true);
+			try {
+				yield downloadStructureImage(plugin, download);
+			} catch (error) {
+				console.error("Failed to download the structure image:", error);
+			} finally {
+				setDownloading(false);
+			}
+		}), [download, plugin]);
 		return /* @__PURE__ */ jsxs(Fragment$1, { children: [
 			/* @__PURE__ */ jsx(Viewport, {}),
 			/* @__PURE__ */ jsx("div", {
@@ -2213,18 +3214,37 @@ function createViewportView(viewSettings) {
 			}),
 			/* @__PURE__ */ jsx(ThemeProvider, {
 				theme,
-				children: /* @__PURE__ */ jsx(ResetCameraSlot, {
-					hidden: !cameraChanged,
-					children: /* @__PURE__ */ jsx(Button, {
-						"aria-label": "Reset camera",
-						onClick: resetCamera,
+				children: /* @__PURE__ */ jsxs(ViewportButtonStack, { children: [/* @__PURE__ */ jsx("div", {
+					hidden: !showAxes || !cameraChanged,
+					children: /* @__PURE__ */ jsx(Tooltip, {
+						arrow: true,
+						placement: "right",
 						title: "Reset camera",
+						textAlign: "left",
+						children: /* @__PURE__ */ jsx(Button, {
+							"aria-label": "Reset camera",
+							onClick: resetCamera,
+							sdsStyle: "minimal",
+							sdsType: "secondary",
+							size: "medium",
+							children: /* @__PURE__ */ jsx(ArrowCounterClockwiseIcon, {})
+						})
+					})
+				}), download && /* @__PURE__ */ jsx(Tooltip, {
+					arrow: true,
+					placement: "right",
+					title: "Download image",
+					textAlign: "left",
+					children: /* @__PURE__ */ jsx(Button, {
+						"aria-label": "Download image of the structure",
+						disabled: downloading,
+						onClick: captureImage,
 						sdsStyle: "minimal",
 						sdsType: "secondary",
 						size: "medium",
-						children: /* @__PURE__ */ jsx(ArrowCounterClockwiseIcon, {})
+						children: /* @__PURE__ */ jsx(ApertureIcon, {})
 					})
-				})
+				})] })
 			})
 		] });
 	};
@@ -2304,37 +3324,274 @@ function syncClipToZoom(plugin, getClipRatio) {
 	}
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/residueRef.ts
+//#region src/core/ProteinStructureViewer/utils/chains.ts
 /**
-* Reads the residue a loci points at, or null when it points at nothing the
-* viewer can address.
+* 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.
 *
-* `index` comes from Mol*'s residue key, which counts residues in file order
-* from zero and is the same counter `injectPlddtIntoPdb` walks. Deriving it
-* from the residue's *number* instead would tie it to how the file happens to
-* be numbered: a crop beginning at residue 200 would index `plddt` at 199, and
-* a file numbering each chain from 1 would give two residues the same index.
+* 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 residueRefFromLoci(loci) {
-	var _StructureProperties$;
-	const location = StructureElement.Location.create(void 0);
-	const firstLoc = StructureElement.Loci.getFirstLocation(loci, location);
-	if (!firstLoc) return null;
+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 {
-		chainId: StructureProperties.chain.auth_asym_id(firstLoc),
-		compId: StructureProperties.atom.label_comp_id(firstLoc),
-		insCode: (_StructureProperties$ = StructureProperties.residue.pdbx_PDB_ins_code(firstLoc)) !== null && _StructureProperties$ !== void 0 ? _StructureProperties$ : "",
-		index: StructureProperties.residue.key(firstLoc),
-		seqId: StructureProperties.residue.auth_seq_id(firstLoc)
+		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
 /**
-* How a residue is named in the readout, e.g. `"LYS 111"`. Takes the number and
-* the insertion code from the file so that the readout and the sequence panel
-* beneath it agree on what to call a residue.
+* The spec's list-valued keys. These are appended rather than merged: Mol*
+* reads them as collections, so a consumer's entries join the viewer's instead
+* of replacing them.
+*
+* `config` is the one where order carries meaning - Mol* folds the list into a
+* Map in order, so a later entry overwrites an earlier one, and appending is
+* what lets a consumer override a setting the viewer chose.
 */
-function residueLabel(residue) {
-	return `${residue.compId} ${residue.seqId}${residue.insCode}`;
+const LIST_KEYS = [
+	"actions",
+	"animations",
+	"behaviors",
+	"config",
+	"customFormats",
+	"customParamEditors"
+];
+/**
+* Whether a value should be merged into rather than replaced.
+*
+* Only object literals qualify. Arrays are collections, and the spec is full
+* of React components and Mol* class instances, all of which are values in
+* their own right - merging into one would take it apart.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function deepMerge(base, override) {
+	if (!isPlainObject(base) || !isPlainObject(override)) return override;
+	const merged = _objectSpread2({}, base);
+	for (const [key, value] of Object.entries(override)) merged[key] = key in base ? deepMerge(base[key], value) : value;
+	return merged;
+}
+function withoutLists(spec) {
+	const rest = _objectSpread2({}, spec);
+	for (const key of LIST_KEYS) delete rest[key];
+	return rest;
+}
+/**
+* Lays a consumer's Mol* spec over the viewer's own.
+*
+* The viewer builds a spec of its own - the sequence panel and viewport it
+* renders, the controls it hides, the behaviors it drops - and this is how a
+* consumer reaches the rest of Mol* without the viewer having to grow a prop
+* per setting. Anything the consumer names wins, so `canvas3d.renderer` or a
+* `PluginConfig` item can be set to something other than the default the
+* viewer picked.
+*
+* The one thing it cannot do is take something away: `behaviors` is appended
+* to, so a behavior the viewer removed - Mol*'s click-to-zoom camera - stays
+* removed, and one the viewer kept cannot be dropped.
+*/
+function mergeMolstarSpec(base, override) {
+	if (!override) return base;
+	const merged = deepMerge(withoutLists(base), withoutLists(override));
+	for (const key of LIST_KEYS) {
+		var _base, _override;
+		const ours = (_base = base[key]) !== null && _base !== void 0 ? _base : [];
+		const theirs = (_override = override[key]) !== null && _override !== void 0 ? _override : [];
+		if (ours.length > 0 || theirs.length > 0) merged[key] = [...ours, ...theirs];
+	}
+	return merged;
+}
+//#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
@@ -2370,6 +3627,14 @@ const PLDDT_COLOR_SCALE = {
 	]
 };
 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.
@@ -2411,47 +3676,23 @@ function injectPlddtIntoPdb(pdbData, plddtValues) {
 /**
 * Mol* color theme that reads pLDDT scores out of the B-factor column, paired
 * with `injectPlddtIntoPdb`. 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/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);
-}
+*/
+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. */
@@ -2510,10 +3751,13 @@ function createResidueValueTheme(mode) {
 }
 //#endregion
 //#region src/core/ProteinStructureViewer/hooks/useMolstarPlugin.ts
-/** Structure representation Mol* builds for the loaded model. */
-const REPRESENTATION_PRESET = "polymer-cartoon";
-/** Theme used when no pLDDT scores are supplied. */
-const FALLBACK_THEME_NAME = "chain-id";
+/**
+* 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;
 /** How long to wait for a frame before starting without one. */
@@ -2550,38 +3794,6 @@ function nextFrame() {
 */
 const HIGHLIGHT_STRENGTH = .2;
 const SELECT_STRENGTH = 0;
-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: {}
-};
 /**
 * Turns the screenshot controls off, on the versions of Mol* that have them.
 *
@@ -2607,13 +3819,13 @@ function createViewer(_x) {
 	return _createViewer.apply(this, arguments);
 }
 function _createViewer() {
-	_createViewer = _asyncToGenerator(function* ({ backgroundColor, edgeColor, highlightColor, residueValueTheme, root, showAxes, showSequenceViewer, viewSettings }) {
+	_createViewer = _asyncToGenerator(function* ({ backgroundColor, chainColorTheme, edgeColor, highlightColor, molstarSpec, residueValueTheme, root, showAxes, showSequenceViewer, viewSettings }) {
 		var _spec$config;
 		const spec = DefaultPluginUISpec();
 		const behaviors = spec.behaviors.filter((b) => b.transformer !== PluginBehaviors.Camera.FocusLoci);
 		const plugin = yield createPluginUI({
 			render: renderReact18,
-			spec: _objectSpread2(_objectSpread2({}, spec), {}, {
+			spec: mergeMolstarSpec(_objectSpread2(_objectSpread2({}, spec), {}, {
 				behaviors,
 				canvas3d: {
 					camera: { helper: { axes: showAxes ? AXES_ON : AXES_OFF } },
@@ -2629,10 +3841,16 @@ function _createViewer() {
 						selectStrength: SELECT_STRENGTH
 					}
 				},
-				components: _objectSpread2({
+				components: {
+					controls: {
+						bottom: "none",
+						left: "none",
+						right: "none"
+					},
 					remoteState: "none",
-					sequenceViewer: { view: createSequenceView(viewSettings) }
-				}, showAxes && { viewport: { view: createViewportView(viewSettings) } }),
+					sequenceViewer: { view: createSequenceView(viewSettings) },
+					viewport: { view: createViewportView(viewSettings) }
+				},
 				config: [
 					...(_spec$config = spec.config) !== null && _spec$config !== void 0 ? _spec$config : [],
 					[PluginConfig.Viewport.ShowExpand, false],
@@ -2653,12 +3871,13 @@ function _createViewer() {
 						top: showSequenceViewer ? "full" : "hidden"
 					}
 				} }
-			}),
+			}), 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;
@@ -2669,7 +3888,112 @@ function _createViewer() {
 	});
 	return _createViewer.apply(this, arguments);
 }
-function loadStructure(_x2, _x3, _x4, _x5) {
+/**
+* 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 PDB 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.
+*/
+function loadStructure(_x9, _x10, _x11, _x12) {
 	return _loadStructure.apply(this, arguments);
 }
 function _loadStructure() {
@@ -2682,31 +4006,69 @@ function _loadStructure() {
 				label: "Structure"
 			});
 			const trajectory = yield plugin.builders.structure.parseTrajectory(data, "pdb");
-			yield plugin.builders.structure.hierarchy.applyPreset(trajectory, "default", {
-				representationPreset: REPRESENTATION_PRESET,
-				showUnitcell: false,
-				structure: {
-					name: "model",
-					params: {}
-				}
+			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);
 }
-/** Recolors every loaded structure's representations with the named theme. */
-function applyColorTheme(_x6, _x7) {
+/**
+* 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, { color: colorTheme });
+			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);
@@ -2720,11 +4082,35 @@ function _applyColorTheme() {
 * axes, coloring, new PDB) are pushed in through the effects below and in the
 * sibling hooks rather than by rebuilding.
 */
-function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt, highlightColor, mode, onResidueClick, onResidueHover, onSelectionClear, pdb, sequenceViewerBackgroundColor, showAxes, showSequenceViewer }) {
+function useMolstarPlugin({ backgroundColor, chainColors, containerRef, download, edgeColor, hasPlddt, hiddenChains, highlightColor, mode, molstarSpec, onChainHover, onChainSelect, onChainToggle, onResidueClick, onResidueHover, onSelectionChange, onSelectionClear, pdb, selectedChains, sequenceViewerBackgroundColor, showAxes, showSequenceViewer }) {
 	const pluginRef = useRef(null);
 	const residueValueThemeRef = useRef(null);
+	const chainColorThemeRef = useRef(null);
 	const currentPdbRef = useRef(null);
 	const [isReady, setIsReady] = useState(false);
+	const [chains, setChains] = useState([]);
+	/**
+	* 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());
+	/**
+	* 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());
+	/**
+	* 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.
+	*/
+	const hiddenChainsRef = useRef(hiddenChains);
+	hiddenChainsRef.current = hiddenChains;
+	const chainColorsRef = useRef(chainColors);
+	chainColorsRef.current = chainColors;
 	/**
 	* 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
@@ -2733,7 +4119,8 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 	const viewSettingsRef = useRef(null);
 	if (viewSettingsRef.current === null) viewSettingsRef.current = new BehaviorSubject({
 		mode,
-		sequenceViewerBackgroundColor
+		sequenceViewerBackgroundColor,
+		showAxes
 	});
 	const viewSettings = viewSettingsRef.current;
 	/**
@@ -2744,10 +4131,27 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 	const setClipRatio = useCallback((ratio) => {
 		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.
+	*
+	* 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.
+	*/
+	const adoptLoadedStructure = useCallback((plugin, loaded) => {
+		componentRefsRef.current = loaded.componentRefs;
+		residuesByChainRef.current = loaded.residuesByChain;
+		applyChainVisibility(plugin, loaded.componentRefs, hiddenChainsRef.current);
+		setChains((prev) => chainsEqual(prev, loaded.chains) ? prev : loaded.chains);
+	}, []);
 	const onResidueClickRef = useRef(onResidueClick);
 	onResidueClickRef.current = onResidueClick;
 	const onSelectionClearRef = useRef(onSelectionClear);
 	onSelectionClearRef.current = onSelectionClear;
+	const onSelectionChangeRef = useRef(onSelectionChange);
+	onSelectionChangeRef.current = onSelectionChange;
 	const onResidueHoverRef = useRef(onResidueHover);
 	onResidueHoverRef.current = onResidueHover;
 	/** Last residue reported to `onResidueHover`, to suppress repeats. */
@@ -2758,6 +4162,7 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 		hasPlddt,
 		highlightColor,
 		mode,
+		molstarSpec,
 		pdb,
 		showAxes,
 		showSequenceViewer
@@ -2768,17 +4173,32 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 		hasPlddt,
 		highlightColor,
 		mode,
+		molstarSpec,
 		pdb,
 		showAxes,
 		showSequenceViewer
 	};
+	/**
+	* 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
+	* as an object written inline - so the effect below turns on what they say
+	* rather than on the identity of the object saying it.
+	*/
+	const canvas3dOverrideKey = (() => {
+		try {
+			var _molstarSpec$canvas3d;
+			return JSON.stringify((_molstarSpec$canvas3d = molstarSpec === null || molstarSpec === void 0 ? void 0 : molstarSpec.canvas3d) !== null && _molstarSpec$canvas3d !== void 0 ? _molstarSpec$canvas3d : null);
+		} catch (_unused) {
+			return String(Date.now());
+		}
+	})();
 	useEffect(() => {
 		const container = containerRef.current;
 		if (!container) return;
 		let cancelled = false;
 		let clipSubscription;
 		const init = function() {
-			var _ref = _asyncToGenerator(function* () {
+			var _ref2 = _asyncToGenerator(function* () {
 				yield nextFrame();
 				if (cancelled) return;
 				const rect = container.getBoundingClientRect();
@@ -2790,10 +4210,13 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 				try {
 					var _plugin$canvas3d2;
 					const residueValueTheme = createResidueValueTheme(initial.mode);
+					const chainColorTheme = createChainColorTheme();
 					const plugin = yield createViewer({
 						backgroundColor: initial.backgroundColor,
+						chainColorTheme,
 						edgeColor: initial.edgeColor,
 						highlightColor: initial.highlightColor,
+						molstarSpec: initial.molstarSpec,
 						residueValueTheme,
 						root: container,
 						showAxes: initial.showAxes,
@@ -2806,11 +4229,28 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 					}
 					pluginRef.current = plugin;
 					residueValueThemeRef.current = residueValueTheme;
+					chainColorThemeRef.current = chainColorTheme;
 					const latest = initialPropsRef.current;
-					yield loadStructure(plugin, latest.pdb, latest.hasPlddt, latest.showAxes);
+					const loaded = yield loadStructure(plugin, latest.pdb, latest.hasPlddt, latest.showAxes);
 					currentPdbRef.current = latest.pdb;
+					adoptLoadedStructure(plugin, loaded);
+					/**
+					* Mol*'s click behavior is a BehaviorSubject, so subscribing replays
+					* whatever it is currently holding - which, before anything has been
+					* clicked, is an empty click. Acting on that would read as the user
+					* clicking empty space and clear a selection the consumer had set
+					* before the viewer was even interactive.
+					*
+					* Only the replay is skipped, not every empty click: clicking away
+					* from the structure is how a selection is meant to be cleared.
+					*/
+					let clickReplayConsumed = false;
 					plugin.behaviors.interaction.click.subscribe((e) => {
-						var _onResidueClickRef$cu;
+						var _onResidueClickRef$cu, _onSelectionChangeRef;
+						if (!clickReplayConsumed) {
+							clickReplayConsumed = true;
+							if (Representation.Loci.isEmpty(e.current)) return;
+						}
 						if (Representation.Loci.isEmpty(e.current)) {
 							var _onSelectionClearRef$;
 							(_onSelectionClearRef$ = onSelectionClearRef.current) === null || _onSelectionClearRef$ === void 0 || _onSelectionClearRef$.call(onSelectionClearRef);
@@ -2821,6 +4261,7 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 						const residue = residueRefFromLoci(loci);
 						if (!residue) return;
 						(_onResidueClickRef$cu = onResidueClickRef.current) === null || _onResidueClickRef$cu === void 0 || _onResidueClickRef$cu.call(onResidueClickRef, residue);
+						(_onSelectionChangeRef = onSelectionChangeRef.current) === null || _onSelectionChangeRef === void 0 || _onSelectionChangeRef.call(onSelectionChangeRef, selectionFromLoci(loci));
 					});
 					plugin.behaviors.interaction.hover.subscribe((e) => {
 						var _lastHoverRef$current, _onResidueHoverRef$cu;
@@ -2839,7 +4280,7 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 				}
 			});
 			return function init() {
-				return _ref.apply(this, arguments);
+				return _ref2.apply(this, arguments);
 			};
 		}();
 		init();
@@ -2850,13 +4291,16 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 			(_pluginRef$current = pluginRef.current) === null || _pluginRef$current === void 0 || _pluginRef$current.dispose();
 			pluginRef.current = null;
 			residueValueThemeRef.current = null;
+			chainColorThemeRef.current = null;
+			componentRefsRef.current = /* @__PURE__ */ new Map();
+			residuesByChainRef.current = /* @__PURE__ */ new Map();
 			currentPdbRef.current = null;
 			clipRatioRef.current = null;
 			setIsReady(false);
 		};
 	}, []);
 	useEffect(() => {
-		var _pluginRef$current2;
+		var _pluginRef$current2, _initialPropsRef$curr;
 		const canvas3d = (_pluginRef$current2 = pluginRef.current) === null || _pluginRef$current2 === void 0 ? void 0 : _pluginRef$current2.canvas3d;
 		if (!canvas3d || !isReady) return;
 		canvas3d.setProps({
@@ -2869,20 +4313,37 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 				highlightColor
 			}
 		});
+		const override = (_initialPropsRef$curr = initialPropsRef.current.molstarSpec) === null || _initialPropsRef$curr === void 0 ? void 0 : _initialPropsRef$curr.canvas3d;
+		if (override) canvas3d.setProps(override);
 	}, [
 		backgroundColor,
+		canvas3dOverrideKey,
 		edgeColor,
 		highlightColor,
 		isReady
 	]);
 	useEffect(() => {
 		viewSettings.next({
+			download,
+			hiddenChains,
 			mode,
-			sequenceViewerBackgroundColor
+			onChainHover,
+			onChainSelect,
+			onChainToggle,
+			selectedChains,
+			sequenceViewerBackgroundColor,
+			showAxes
 		});
 	}, [
+		download,
+		hiddenChains,
 		mode,
+		onChainHover,
+		onChainSelect,
+		onChainToggle,
+		selectedChains,
 		sequenceViewerBackgroundColor,
+		showAxes,
 		viewSettings
 	]);
 	useEffect(() => {
@@ -2896,120 +4357,312 @@ function useMolstarPlugin({ backgroundColor, containerRef, edgeColor, hasPlddt,
 		currentPdbRef.current = pdb;
 		clipRatioRef.current = null;
 		lastHoverRef.current = null;
-		loadStructure(plugin, pdb, hasPlddt, showAxes);
+		loadStructure(plugin, pdb, hasPlddt, showAxes).then((loaded) => {
+			if (pluginRef.current !== plugin) return;
+			adoptLoadedStructure(plugin, loaded);
+		});
 	}, [
 		pdb,
 		hasPlddt,
-		isReady
+		isReady,
+		adoptLoadedStructure
 	]);
+	useEffect(() => {
+		const plugin = pluginRef.current;
+		if (!plugin || !isReady) return;
+		applyChainVisibility(plugin, componentRefsRef.current, hiddenChains);
+	}, [hiddenChains, isReady]);
 	return {
+		chainColorThemeRef,
+		chains,
 		isReady,
 		pluginRef,
+		residuesByChainRef,
 		residueValueThemeRef,
 		setClipRatio
 	};
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/residueLoci.ts
+//#region src/core/ProteinStructureViewer/utils/focusRepresentation.ts
+/**
+* What Mol* draws around a focused selection, as ball-and-stick over the
+* cartoon: the selection itself, the residues near it, and the non-covalent
+* contacts between the two. All three stay on; what changes is how far "near"
+* reaches.
+*/
+const FOCUS_COMPONENTS = [
+	"target",
+	"surroundings",
+	"interactions"
+];
+/** Mol*'s own default, in angstroms. */
+const NEIGHBOUR_RADIUS = 5;
+/**
+* Mol* builds the surroundings as `includeSurroundings(target, radius)` with
+* whole residues, so a radius of zero resolves to the residues of the target
+* and nothing else.
+*/
+const OWN_RESIDUES_ONLY = 0;
 /**
-* Every atom of the residue at a 0-based index, as geometry Mol* can focus and
-* frame, or undefined when the structure has no such residue.
+* Chooses how far the focus shell reaches around a selection.
 *
-* The inverse of `residueRefFromLoci`, and keyed on the same residue ordinal,
-* so a `selectedResidue` echoed back from a click resolves to the residue that
-* was clicked - on a complex as much as on a single chain.
+* A residue, or a short range, is a site: the 5A shell around it is the point
+* of looking at it, and Mol*'s default earns its keep. A whole chain is a
+* structural unit instead, and its neighbours are the chain bound to it - so
+* on a complex the shell reaches straight across the interface and draws the
+* partner's contact face in atoms, which reads as the partner being selected
+* too.
 *
-* The whole residue is collected rather than one atom, since the caller frames
-* the camera on the loci's bounding sphere and a single atom would zoom far
-* closer than the residue warrants.
+* Taking the radius to zero confines the shell to the selection rather than
+* turning it off: the surroundings and the interactions are still drawn, over
+* the selected chain's own residues, so a chain shows its own atoms and
+* contacts and no others'.
 */
-function lociForResidueIndex(plugin, residueIndex) {
-	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 location = StructureElement.Location.create(structure);
-		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 (StructureProperties.residue.key(location) === residueIndex) indices.push(i);
-			}
-			if (indices.length > 0) return StructureElement.Loci(structure, [{
-				indices: OrderedSet.ofSortedArray(indices),
-				unit
-			}]);
-		}
-	}
+function setFocusNeighbourhood(_x, _x2) {
+	return _setFocusNeighbourhood.apply(this, arguments);
+}
+function _setFocusNeighbourhood() {
+	_setFocusNeighbourhood = _asyncToGenerator(function* (plugin, includeNeighbours) {
+		const expandRadius = includeNeighbours ? NEIGHBOUR_RADIUS : OWN_RESIDUES_ONLY;
+		yield plugin.state.updateBehavior(StructureFocusRepresentation, (params) => {
+			params.components = FOCUS_COMPONENTS;
+			params.expandRadius = expandRadius;
+		});
+	});
+	return _setFocusNeighbourhood.apply(this, arguments);
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/hooks/useResidueFocus.ts
+//#region src/core/ProteinStructureViewer/hooks/useSelectionFocus.ts
+/**
+* Points the camera at a loci and marks it.
+*
+* A click has already focused what the consumer echoes back by the time it
+* arrives, so the focus is only set when it is not already what is marked;
+* setting it again would restate the selection and repaint the sequence panel
+* for nothing.
+*/
+function focusLoci(plugin, loci, setClipRatio) {
+	const focused = plugin.managers.structure.focus.behaviors.current.value;
+	if (!focused || !StructureElement.Loci.areEqual(focused.loci, loci)) plugin.managers.structure.focus.setFromLoci(loci);
+	setClipRatio(focusResidue(plugin, loci));
+}
+/**
+* Drops the focus, and the depth clipping anchored to it.
+*
+* `resetCamera` separates the two ways this happens. The consumer clearing the
+* selection means there is nothing to look at, so the view goes back to the
+* default. A selection that merely resolved to nothing visible - the chain it
+* covers having been hidden - still stands, so throwing the camera back would
+* be answering a question nobody asked.
+*/
+function clearFocus(plugin, setClipRatio, resetCamera) {
+	var _plugin$canvas3d;
+	setClipRatio(null);
+	plugin.managers.structure.focus.clear();
+	if (resetCamera) (_plugin$canvas3d = plugin.canvas3d) === null || _plugin$canvas3d === void 0 || _plugin$canvas3d.requestCameraReset();
+}
+/**
+* Focuses a loci, resizing the focus shell first when this selection wants a
+* different reach than the last one did.
+*
+* The resize is asynchronous and the focus has to follow it - the shell is
+* sized before focusing so it is not drawn at the old reach and rebuilt - so
+* this hands back a teardown that abandons the focus if the effect is torn
+* down while the resize is still in flight.
+*
+* `currentShell` is the reach already configured, carried in a ref so that two
+* selections of the same kind do not each restate it.
+*/
+function focusWithShell(plugin, loci, includeNeighbours, currentShell, pluginRef, setClipRatio) {
+	if (currentShell.current === includeNeighbours) {
+		focusLoci(plugin, loci, setClipRatio);
+		return;
+	}
+	let cancelled = false;
+	currentShell.current = includeNeighbours;
+	setFocusNeighbourhood(plugin, includeNeighbours).then(() => {
+		if (cancelled || pluginRef.current !== plugin) return;
+		focusLoci(plugin, loci, setClipRatio);
+	});
+	return () => {
+		cancelled = true;
+	};
+}
 /**
-* Makes `selectedResidue` the one thing that decides where the camera sits.
+* Makes `selection` the one thing that decides where the camera sits.
 *
-* Setting the prop zooms in on that residue and marks it; clearing it drops the
-* focus and zooms back out. The click subscription only reports the residue it
-* was given, so a click moves the camera only once the consumer accepts it and
-* echoes it back - which is what the prop being controlled is supposed to mean.
+* Setting the prop frames whatever it covers and marks it; clearing it drops
+* the focus and zooms back out. The camera frames the selection's bounding
+* sphere, so a range or a whole chain is fitted rather than approached as a
+* point - one residue is just the smallest case of that.
 *
-* Clicking still marks the residue immediately, through Mol*'s own focus
-* behavior, so the structure responds to a click whether or not the consumer
-* wires the prop up.
+* The click subscription only reports the selection it was given, so a click
+* moves the camera only once the consumer accepts it and echoes it back -
+* which is what the prop being controlled is supposed to mean. Clicking still
+* marks immediately, through Mol*'s own focus behavior, so the structure
+* responds to a click whether or not the consumer wires the prop up.
 */
-function useResidueFocus({ isReady, pluginRef, selectedResidue, setClipRatio }) {
+function useSelectionFocus({ hiddenChains, isReady, pluginRef, selection, setClipRatio }) {
 	/**
-	* The residue this hook last pointed the camera at. Tracked rather than
-	* compared against the previous prop value so that a selection made before
-	* the plugin was ready is still applied once it is, and so that a plugin
-	* rebuilt underneath us - which comes up focused on nothing - is not assumed
-	* to still be holding the old one.
+	* What this hook last pointed the camera at, as a key rather than the object
+	* itself: a consumer echoing a selection back builds a new object each time,
+	* and comparing identity would refocus on every render.
+	*
+	* Tracked here rather than compared against the previous prop so that a
+	* selection made before the plugin was ready is still applied once it is,
+	* and so that a plugin rebuilt underneath us - which comes up focused on
+	* nothing - is not assumed to still be holding the old one.
 	*/
 	const focusedRef = useRef(null);
+	/**
+	* Whether the focus shell currently reaches beyond the selection, so the
+	* behavior is only updated when the answer actually changes rather than on
+	* every selection.
+	*/
+	const neighbourhoodRef = useRef(null);
+	/**
+	* What the camera should be pointed at, as a string. Hiding a chain changes
+	* what there is to focus, so it belongs in here alongside the selection
+	* itself - and comparing strings rather than objects is what keeps a consumer
+	* echoing an equal selection back from refocusing on every render.
+	*/
+	const focusKey = selection ? `${selectionKey(selection)}#${[...hiddenChains].sort().join(",")}` : null;
 	useEffect(() => {
+		var _chosen$chains;
 		const plugin = pluginRef.current;
 		if (!plugin || !isReady) {
 			focusedRef.current = null;
+			neighbourhoodRef.current = null;
 			return;
 		}
-		const residue = selectedResidue !== null && selectedResidue !== void 0 ? selectedResidue : null;
-		if (residue === focusedRef.current) return;
-		focusedRef.current = residue;
-		if (residue === null) {
-			var _plugin$canvas3d;
-			setClipRatio(null);
-			plugin.managers.structure.focus.clear();
-			(_plugin$canvas3d = plugin.canvas3d) === null || _plugin$canvas3d === void 0 || _plugin$canvas3d.requestCameraReset();
+		if (focusKey === focusedRef.current) return;
+		focusedRef.current = focusKey;
+		if (focusKey === null) {
+			clearFocus(plugin, setClipRatio, true);
 			return;
 		}
-		const loci = lociForResidueIndex(plugin, residue);
-		if (!loci) return;
-		const focused = plugin.managers.structure.focus.behaviors.current.value;
-		if (!focused || !StructureElement.Loci.areEqual(focused.loci, loci)) plugin.managers.structure.focus.setFromLoci(loci);
-		setClipRatio(focusResidue(plugin, loci));
+		const chosen = selection;
+		const loci = lociForSelection(plugin, chosen, hiddenChains);
+		if (!loci) {
+			clearFocus(plugin, setClipRatio, false);
+			return;
+		}
+		return focusWithShell(plugin, loci, !((_chosen$chains = chosen.chains) === null || _chosen$chains === void 0 ? void 0 : _chosen$chains.length), neighbourhoodRef, pluginRef, setClipRatio);
 	}, [
-		selectedResidue,
+		focusKey,
 		isReady,
 		setClipRatio
 	]);
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/hooks/useResidueOverlay.ts
+//#region src/core/ProteinStructureViewer/hooks/useSelectionReadout.ts
+/**
+* Tracks the residue under the pointer, deduplicated, and passes the event on
+* to the consumer.
+*
+* Mol* emits hover events continuously, so a residue the pointer is resting on
+* would otherwise cost a state update per event. The index alone does not
+* identify one: loading a new structure into the same plugin renumbers from
+* zero, so the residue now at an index is not the one that was there before.
+* Comparing the label as well is enough, because the readout this drives is
+* built from the label and the index and from nothing else.
+*/
+function useResidueHoverState(onResidueHover) {
+	const [hoveredResidue, setHoveredResidue] = useState(null);
+	return {
+		handleResidueHover: useCallback((residue) => {
+			setHoveredResidue((prev) => {
+				if (residue === null) return prev === null ? prev : null;
+				const label = residueLabel(residue);
+				return prev !== null && prev.index === residue.index && prev.label === label ? prev : {
+					index: residue.index,
+					label
+				};
+			});
+			onResidueHover === null || onResidueHover === void 0 || onResidueHover(residue);
+		}, [onResidueHover]),
+		hoveredResidue
+	};
+}
+/**
+* Derives the legend's readouts from what is hovered and what is selected.
+*
+* The viewer already knows everything they need - the label, the pLDDT, the
+* overlay value - so they are worked out here rather than asked of the
+* consumer. A readout covering several residues reports the mean of each,
+* which is the only reading that survives a range or a whole chain.
+*/
+function useSelectionReadout({ hoveredResidue, isReady, plddt, pluginRef, residueOverlay, residuesByChainRef, selection }) {
+	const [resolved, setResolved] = useState(null);
+	/**
+	* What the selection covers has to be read off the structure, since a
+	* selection can be made without a click ever naming anything: a lone residue
+	* is named the way the click path names it, so the two readouts cannot
+	* disagree, and a chain is expanded to the residues it actually holds rather
+	* than to the span between its ends.
+	*/
+	useEffect(() => {
+		var _residuesByChainRef$c;
+		const plugin = pluginRef.current;
+		if (!plugin || !isReady || isEmptySelection(selection)) {
+			setResolved(null);
+			return;
+		}
+		const chosen = selection;
+		const residues = selectionResidues(chosen, (_residuesByChainRef$c = residuesByChainRef.current) !== null && _residuesByChainRef$c !== void 0 ? _residuesByChainRef$c : /* @__PURE__ */ new Map());
+		if (residues.length === 0) {
+			setResolved(null);
+			return;
+		}
+		if (residues.length > 1) {
+			setResolved({
+				label: selectionLabel(chosen, residues.length),
+				residues
+			});
+			return;
+		}
+		const loci = lociForSelection(plugin, chosen);
+		const residue = loci && residueRefFromLoci(loci);
+		setResolved(residue ? {
+			label: residueLabel(residue),
+			residues
+		} : null);
+	}, [isReady, selection && selectionKey(selection)]);
+	const buildReadout = useCallback((label, residues) => ({
+		label,
+		plddt: meanOverResidues(residues, (i) => plddt === null || plddt === void 0 ? void 0 : plddt[i]),
+		value: meanOverResidues(residues, (i) => residueOverlay === null || residueOverlay === void 0 ? void 0 : residueOverlay.values.get(i)),
+		residueCount: residues.length
+	}), [plddt, residueOverlay]);
+	return {
+		hoveredReadout: useMemo(() => hoveredResidue === null ? null : buildReadout(hoveredResidue.label, [hoveredResidue.index]), [hoveredResidue, buildReadout]),
+		selectedReadout: useMemo(() => resolved === null ? null : buildReadout(resolved.label, resolved.residues), [resolved, buildReadout])
+	};
+}
+//#endregion
+//#region src/core/ProteinStructureViewer/hooks/useStructureColoring.ts
 /**
-* Switches the structure's coloring between the residue value overlay and the
-* default (pLDDT, or chain-id when no scores were supplied).
+* 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 useResidueOverlay({ hasPlddt, isReady, mode, overlay, pluginRef, residueValueThemeRef }) {
+function useStructureColoring({ chainColorThemeRef, chainColors, hasPlddt, isReady, mode, overlay, pluginRef, residueValueThemeRef }) {
 	useEffect(() => {
 		const plugin = pluginRef.current;
-		const theme = residueValueThemeRef.current;
-		if (!plugin || !theme || !isReady) return;
+		const residueTheme = residueValueThemeRef.current;
+		const chainTheme = chainColorThemeRef.current;
+		if (!plugin || !residueTheme || !chainTheme || !isReady) return;
+		chainTheme.setState(chainColors);
 		if (overlay) {
 			var _overlay$colorScale, _overlay$min;
-			theme.setState({
+			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,
@@ -3017,33 +4670,51 @@ function useResidueOverlay({ hasPlddt, isReady, mode, overlay, pluginRef, residu
 				values: overlay.values
 			});
 			applyColorTheme(plugin, RESIDUE_VALUE_THEME_NAME);
-		} else {
-			theme.setState({
-				mode,
-				values: /* @__PURE__ */ new Map()
-			});
-			applyColorTheme(plugin, hasPlddt ? PLDDT_THEME_NAME : FALLBACK_THEME_NAME);
+			return;
 		}
+		residueTheme.setState({
+			mode,
+			values: /* @__PURE__ */ new Map()
+		});
+		applyColorTheme(plugin, hasPlddt ? PLDDT_THEME_NAME : FALLBACK_THEME_NAME);
 	}, [
 		overlay,
 		hasPlddt,
 		isReady,
-		mode
+		mode,
+		chainColors
 	]);
 }
 //#endregion
+//#region src/core/ProteinStructureViewer/ProteinStructureViewer.types.ts
+/** Pixel dimensions each resolution produces, for documentation and labels. */
+const DOWNLOAD_RESOLUTIONS = {
+	high: "3840x2160",
+	low: "1280x720",
+	maximum: "7680x4320",
+	medium: "1920x1080"
+};
+//#endregion
 //#region src/core/ProteinStructureViewer/index.tsx
 const _excluded$1 = [
 	"backgroundColor",
+	"chainColors",
+	"disableChainHighlightOnHover",
+	"download",
+	"hiddenChains",
+	"onChainVisibilityChange",
+	"onChainsChange",
+	"molstarSpec",
 	"onResidueClick",
 	"onResidueHover",
-	"onSelectionClear",
+	"onSelectionChange",
 	"pdb",
 	"plddt",
 	"residueOverlay",
-	"selectedResidue",
+	"selection",
 	"sequenceViewerBackgroundColor",
 	"showAxes",
+	"showChainLegend",
 	"showLegend",
 	"showSequenceViewer",
 	"stats"
@@ -3104,64 +4775,121 @@ function resolveScaleProps(overlay, hasPlddt) {
 	};
 }
 var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
-	const { backgroundColor, onResidueClick, onResidueHover, onSelectionClear, pdb, plddt, residueOverlay, selectedResidue = null, sequenceViewerBackgroundColor, showAxes = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded$1);
+	var _selection$chains;
+	const { backgroundColor, chainColors: chainColorOverrides, disableChainHighlightOnHover = false, download, hiddenChains: hiddenChainsProp, onChainVisibilityChange, onChainsChange, molstarSpec, onResidueClick, onResidueHover, onSelectionChange, pdb, plddt, residueOverlay, selection = null, sequenceViewerBackgroundColor, showAxes = true, showChainLegend = true, showLegend = true, showSequenceViewer = true, stats } = props, rest = _objectWithoutProperties(props, _excluded$1);
 	const theme = useTheme();
 	const mode = getMode({ theme });
 	const semanticColors = getSemanticColors({ theme });
 	const pluginMountRef = useRef(null);
-	const [hoveredResidue, setHoveredResidue] = useState(null);
-	/**
-	* Label for the selected residue, read back off the structure rather than
-	* remembered from the click that selected it, so the readout follows the
-	* prop however the selection was made.
-	*/
-	const [selectedLabel, setSelectedLabel] = useState(null);
 	const hasPlddt = Boolean(plddt && plddt.length > 0);
 	const processedPdb = useMemo(() => hasPlddt ? injectPlddtIntoPdb(pdb, plddt) : pdb, [
 		pdb,
 		plddt,
 		hasPlddt
 	]);
-	const { isReady, pluginRef, residueValueThemeRef, setClipRatio } = useMolstarPlugin({
-		backgroundColor: 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]);
-		}, [
-			backgroundColor,
-			mode,
-			semanticColors
-		]),
+	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]);
+	}, [
+		backgroundColor,
+		mode,
+		semanticColors
+	]);
+	const edgeColor = useMemo(() => {
+		var _semanticColors$base2;
+		return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base2 = semanticColors.base) === null || _semanticColors$base2 === void 0 ? void 0 : _semanticColors$base2.borderPrimary, FALLBACK_EDGE_COLOR);
+	}, [semanticColors]);
+	const highlightColor = useMemo(() => {
+		var _semanticColors$base3;
+		return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.fillSelected, FALLBACK_HIGHLIGHT_COLOR);
+	}, [semanticColors]);
+	const { handleResidueHover, hoveredResidue } = useResidueHoverState(onResidueHover);
+	const handleSelectionClear = useCallback(() => {
+		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(null);
+	}, [onSelectionChange]);
+	/**
+	* Chains the selection covers whole, which is what makes a chain caption a
+	* toggle rather than a one-way switch. Keyed on its contents because the
+	* set is pushed into the views Mol* renders, where a fresh object every
+	* render would be a fresh push every render.
+	*/
+	const selectedChainsKey = [...(_selection$chains = selection === null || selection === void 0 ? void 0 : selection.chains) !== null && _selection$chains !== void 0 ? _selection$chains : []].sort().join("\0");
+	const selectedChains = useMemo(() => new Set(selectedChainsKey === "" ? [] : selectedChainsKey.split("\0")), [selectedChainsKey]);
+	/**
+	* Clicking a chain selects it; clicking the selected chain again clears it.
+	*
+	* A whole chain is reported as the chain it is, not as the hundreds of
+	* residue indices it stands for, so echoing it back costs nothing. Only a
+	* selection that is exactly this one chain toggles off - with a residue or
+	* another chain also selected, the click is narrowing to this chain rather
+	* than undoing itself.
+	*/
+	const handleChainSelect = useCallback((chainId) => {
+		var _selection$chains2, _selection$residues;
+		const isOnlyThisChain = (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);
+		onSelectionChange === null || onSelectionChange === void 0 || onSelectionChange(isOnlyThisChain ? null : { chains: [chainId] });
+	}, [onSelectionChange, selection]);
+	/**
+	* Lights a chain up while its name is pointed at, in the legend or in the
+	* sequence panel's captions.
+	*
+	* Reached through a ref because the two ends need each other: lighting a
+	* chain up takes the plugin, which the hook below creates, and that hook
+	* has to be handed the callback to give the captions it renders. This one
+	* is stable and forwards to whatever the highlight hook installs once
+	* there is a plugin for it to talk to.
+	*/
+	const highlightChainRef = useRef(() => void 0);
+	const highlightChain = useCallback((chainId) => {
+		highlightChainRef.current(chainId);
+	}, []);
+	const [chains, setChains] = useState([]);
+	const { colors: chainColors, hidden: hiddenChains, toggleChain } = useChains({
+		chainColors: chainColorOverrides,
+		chains,
+		hiddenChains: hiddenChainsProp,
+		onChainVisibilityChange
+	});
+	const { chainColorThemeRef, chains: loadedChains, isReady, pluginRef, residuesByChainRef, residueValueThemeRef, setClipRatio } = useMolstarPlugin({
+		backgroundColor: bgColor,
+		chainColors,
 		containerRef: pluginMountRef,
-		edgeColor: useMemo(() => {
-			var _semanticColors$base2;
-			return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base2 = semanticColors.base) === null || _semanticColors$base2 === void 0 ? void 0 : _semanticColors$base2.borderPrimary, FALLBACK_EDGE_COLOR);
-		}, [semanticColors]),
+		download,
+		edgeColor,
 		hasPlddt,
-		highlightColor: useMemo(() => {
-			var _semanticColors$base3;
-			return themeColor(semanticColors === null || semanticColors === void 0 || (_semanticColors$base3 = semanticColors.base) === null || _semanticColors$base3 === void 0 ? void 0 : _semanticColors$base3.fillSelected, FALLBACK_HIGHLIGHT_COLOR);
-		}, [semanticColors]),
+		hiddenChains,
+		highlightColor,
 		mode,
+		molstarSpec,
+		onChainHover: highlightChain,
+		onChainSelect: handleChainSelect,
+		onChainToggle: toggleChain,
 		onResidueClick,
-		onResidueHover: useCallback((residue) => {
-			setHoveredResidue((prev) => {
-				if (residue === null) return prev === null ? prev : null;
-				const label = residueLabel(residue);
-				if (prev !== null && prev.index === residue.index && prev.label === label) return prev;
-				return {
-					index: residue.index,
-					label
-				};
-			});
-			onResidueHover === null || onResidueHover === void 0 || onResidueHover(residue);
-		}, [onResidueHover]),
-		onSelectionClear,
+		onResidueHover: handleResidueHover,
+		onSelectionChange,
+		onSelectionClear: handleSelectionClear,
 		pdb: processedPdb,
+		selectedChains,
 		sequenceViewerBackgroundColor,
 		showAxes,
 		showSequenceViewer
 	});
-	useResidueOverlay({
+	highlightChainRef.current = useChainHighlight({
+		disabled: disableChainHighlightOnHover,
+		pluginRef
+	});
+	useEffect(() => {
+		setChains(loadedChains);
+	}, [loadedChains]);
+	const onChainsChangeRef = useRef(onChainsChange);
+	onChainsChangeRef.current = onChainsChange;
+	useEffect(() => {
+		var _onChainsChangeRef$cu;
+		(_onChainsChangeRef$cu = onChainsChangeRef.current) === null || _onChainsChangeRef$cu === void 0 || _onChainsChangeRef$cu.call(onChainsChangeRef, loadedChains);
+	}, [loadedChains]);
+	useStructureColoring({
+		chainColorThemeRef,
+		chainColors,
 		hasPlddt,
 		isReady,
 		mode,
@@ -3169,46 +4897,49 @@ var ProteinStructureViewer_default = memo(forwardRef((props, ref) => {
 		pluginRef,
 		residueValueThemeRef
 	});
-	useResidueFocus({
+	useSelectionFocus({
+		hiddenChains,
 		isReady,
 		pluginRef,
-		selectedResidue,
+		selection,
 		setClipRatio
 	});
-	useEffect(() => {
-		const plugin = pluginRef.current;
-		if (!plugin || !isReady || selectedResidue === null) {
-			setSelectedLabel(null);
-			return;
-		}
-		const loci = lociForResidueIndex(plugin, selectedResidue);
-		const residue = loci && residueRefFromLoci(loci);
-		setSelectedLabel(residue ? residueLabel(residue) : null);
-	}, [
+	const { hoveredReadout, selectedReadout } = useSelectionReadout({
+		hoveredResidue,
 		isReady,
+		plddt,
 		pluginRef,
-		selectedResidue
-	]);
-	const buildReadout = useCallback((label, index) => {
-		var _plddt$index, _residueOverlay$value;
-		return {
-			label,
-			plddt: (_plddt$index = plddt === null || plddt === void 0 ? void 0 : plddt[index]) !== null && _plddt$index !== void 0 ? _plddt$index : null,
-			value: (_residueOverlay$value = residueOverlay === null || residueOverlay === void 0 ? void 0 : residueOverlay.values.get(index)) !== null && _residueOverlay$value !== void 0 ? _residueOverlay$value : null
-		};
-	}, [plddt, residueOverlay]);
-	const hoveredReadout = useMemo(() => hoveredResidue === null ? null : buildReadout(hoveredResidue.label, hoveredResidue.index), [hoveredResidue, buildReadout]);
-	const selectedReadout = useMemo(() => selectedResidue === null || selectedLabel === null ? null : buildReadout(selectedLabel, selectedResidue), [
-		selectedResidue,
-		selectedLabel,
-		buildReadout
-	]);
+		residueOverlay,
+		residuesByChainRef,
+		selection
+	});
 	const scaleProps = useMemo(() => resolveScaleProps(residueOverlay, hasPlddt), [residueOverlay, hasPlddt]);
+	/**
+	* What a chain's swatch can show follows whatever is painting the
+	* structure, in the same order the color key resolves in.
+	*
+	* Chain coloring gives each chain one color of its own. pLDDT gives every
+	* chain the same four bands, which says they are colored by confidence
+	* rather than telling them apart - so the swatch carries the whole key,
+	* quartered. An overlay is continuous and has no discrete colors to put in
+	* 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;
 	return /* @__PURE__ */ jsxs(ViewerRoot, _objectSpread2(_objectSpread2({
 		ref,
 		showSequenceViewer
 	}, rest), {}, { children: [/* @__PURE__ */ jsx(PluginMount, { ref: pluginMountRef }), showLegend && /* @__PURE__ */ jsx(StructureLegend, _objectSpread2({
+		chainBandColors: plddtColoringActive ? PLDDT_BAND_COLORS : void 0,
+		chainColors: chainColoringActive ? chainColors : void 0,
+		chains: showChainLegend ? chains : [],
+		hiddenChains,
 		hoveredResidue: hoveredReadout,
+		onChainHover: highlightChain,
+		onChainSelect: handleChainSelect,
+		onChainToggle: toggleChain,
+		selectedChains,
 		selectedResidue: selectedReadout,
 		showSequenceViewer,
 		stats: stats !== null && stats !== void 0 ? stats : []
@@ -3690,4 +5421,4 @@ const StackedBarChart = (props) => {
 	return /* @__PURE__ */ jsxs(ChartWrapper, _objectSpread2(_objectSpread2({ width }, rest), {}, { children: [/* @__PURE__ */ jsxs(TitleContainer, { children: [/* @__PURE__ */ jsx(ChartTitle, { children: title }), !hideBadge && displayBadge && /* @__PURE__ */ jsx(StyledBadge, { children: displayBadge })] }), chartContent] }));
 };
 //#endregion
-export { HeatmapChart_default as HeatmapChart, PLASMA_COLOR_SCALE, PLDDT_COLOR_SCALE, ProteinStructureViewer_default as ProteinStructureViewer, StackedBarChart, injectPlddtIntoPdb, sampleColorScale, toCssGradient };
+export { DOWNLOAD_RESOLUTIONS, HeatmapChart_default as HeatmapChart, PLASMA_COLOR_SCALE, PLDDT_COLOR_SCALE, ProteinStructureViewer_default as ProteinStructureViewer, StackedBarChart, injectPlddtIntoPdb, sampleColorScale, toCssGradient };