Brush + pin elements via legend hover/click

Hovering an element pill in the Controls legend now dims non-matching
atoms (and labels) to opacity 0.15. Clicking a pill *pins* the
highlight, surviving subsequent hover changes — useful for inspecting
one species while orbiting/scrubbing.

UX details:

- Container-level `onMouseLeave` (not per-item) closes the inter-pill
  gap so traversing between adjacent pills doesn't briefly reset to
  null and flicker all atoms back on.
- Pin is cleared by *meaningless* clicks only: a non-drag mouseup that
  isn't on/from an interactive control. `mousedown`/`mouseup` deltas
  >5px count as drag (so orbit-rotating the canvas preserves pin); a
  selector list (`input, button, select, textarea, label, a, summary,
  [role=…], [contenteditable], [data-legend-item]`) shields real
  controls from triggering an unpin.
- Pinned pill shows a colored border in its element color as a visual
  cue.
- Atom labels now default-on (`al` is `boolTrueParam`) so brushing has
  legible legend-to-atom association out of the box.

The dim factor multiplies through `atomOpacity`'s tile-fade, and labels
share the same opacity, so periodic copies fade in concert with their
primary-cell counterparts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ryan-williams

pkgs/core/src/components/Controls.tsx

@@ -1,3 +1,4 @@
+import { useEffect, useState } from 'react'
 import { getElement } from '../utils/elements.ts'
 import { densityToQuantile, quantileToDensity } from '../utils/color-ramp.ts'
 import styles from './Controls.module.css'
@@ -59,6 +60,10 @@ interface ControlsProps {
   onTilePaddingChange?: (v: number) => void
   tileFade?: number
   onTileFadeChange?: (v: number) => void
+  /** Element symbol currently hovered in the legend (controlled by parent) */
+  highlightElement?: string | null
+  /** Called when the user hovers/unhovers an element pill in the legend */
+  onHighlightElementChange?: (el: string | null) => void
 }
 
 const AXIS_LABELS = ['X', 'Y', 'Z'] as const
@@ -128,21 +133,90 @@ export function Controls({
   onTilePaddingChange,
   tileFade,
   onTileFadeChange,
+  highlightElement: _highlightElement,
+  onHighlightElementChange,
 }: ControlsProps) {
   const tp = tilePadding ?? 0
   const hasTiling = tp > 0
 
+  // Element legend brushing: pin via click (sticky), hover otherwise.
+  const [pinned, setPinned] = useState<string | null>(null)
+  const [hovered, setHovered] = useState<string | null>(null)
+  const active = pinned ?? hovered
+  useEffect(() => {
+    onHighlightElementChange?.(active)
+  }, [active, onHighlightElementChange])
+
+  // Only "meaningless" clicks (empty space, no drag, not on an interactive control) unpin.
+  useEffect(() => {
+    if (!pinned) return
+    const INTERACTIVE = [
+      'input', 'button', 'select', 'textarea', 'label', 'a', 'summary',
+      '[role="button"]', '[role="checkbox"]', '[role="slider"]', '[role="link"]',
+      '[role="menuitem"]', '[role="tab"]', '[role="switch"]', '[role="combobox"]',
+      '[contenteditable=""]', '[contenteditable="true"]',
+      '[data-legend-item]',
+    ].join(',')
+    let downX = 0
+    let downY = 0
+    let downInteractive = false
+    const onDown = (e: MouseEvent) => {
+      downX = e.clientX
+      downY = e.clientY
+      downInteractive = !!(e.target as Element | null)?.closest(INTERACTIVE)
+    }
+    const onUp = (e: MouseEvent) => {
+      // Drag (>5px movement) → preserve pin
+      if (Math.hypot(e.clientX - downX, e.clientY - downY) > 5) return
+      if (downInteractive) return
+      if ((e.target as Element | null)?.closest(INTERACTIVE)) return
+      setPinned(null)
+    }
+    document.addEventListener('mousedown', onDown)
+    document.addEventListener('mouseup', onUp)
+    return () => {
+      document.removeEventListener('mousedown', onDown)
+      document.removeEventListener('mouseup', onUp)
+    }
+  }, [pinned])
+
   return (
     <div className={styles.controls}>
       <div className={styles.controlTitle}>{filename}</div>
       {elements && elements.length > 0 && (
-        <div style={{ display: 'flex', gap: 8, padding: '2px 0 6px', flexWrap: 'wrap' }}>
+        <div
+          style={{ display: 'flex', gap: 8, padding: '2px 0 6px', flexWrap: 'wrap' }}
+          onMouseLeave={() => setHovered(null)}
+        >
           {elements.map((el, i) => {
             const { color } = getElement(el)
             const css = `#${color.toString(16).padStart(6, '0')}`
             const count = counts?.[i]
+            const isActive = active === el
+            const isDimmed = active != null && !isActive
+            const isPinned = pinned === el
             return (
-              <span key={el} style={{ display: 'flex', alignItems: 'center', gap: 4, fontSize: 12, color: '#ccc' }}>
+              <span
+                key={el}
+                data-legend-item=""
+                onMouseEnter={() => setHovered(el)}
+                onClick={() => setPinned(p => p === el ? null : el)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 4,
+                  fontSize: 12,
+                  color: '#ccc',
+                  cursor: 'pointer',
+                  opacity: isDimmed ? 0.4 : 1,
+                  fontWeight: isActive ? 600 : 400,
+                  transition: 'opacity 120ms, font-weight 120ms',
+                  padding: '2px 6px',
+                  borderRadius: 4,
+                  border: isPinned ? `1px solid ${css}` : '1px solid transparent',
+                  userSelect: 'none',
+                }}
+              >
                 <span style={{
                   width: 10,
                   height: 10,

pkgs/core/src/components/CrystalStructure.tsx

@@ -19,6 +19,8 @@ interface CrystalStructureProps {
   tiles?: TileInfo[]
   tilePadding?: number
   tileFade?: number
+  /** When set, atoms of this element render normally; others fade aggressively. */
+  highlightElement?: string | null
 }
 
 // Lattice vector colors — YOV (yellow, orange, violet), warm complement of gizmo RGB
@@ -108,7 +110,7 @@ function quantizeOpacity(o: number): number {
   return Math.round(o * 20) / 20
 }
 
-export function CrystalStructure({ volume, showAtoms, showAtomLabels, showAbcCell, showXyzBox, dashedLines, lineWidth = 1, tiles, tilePadding = 0, tileFade = 1 }: CrystalStructureProps) {
+export function CrystalStructure({ volume, showAtoms, showAtomLabels, showAbcCell, showXyzBox, dashedLines, lineWidth = 1, tiles, tilePadding = 0, tileFade = 1, highlightElement }: CrystalStructureProps) {
   const { lattice, structure } = volume
 
   // Group atoms by (element, quantized opacity) for tiled instanced rendering
@@ -128,7 +130,9 @@ export function CrystalStructure({ volume, showAtoms, showAtomLabels, showAbcCel
           atom.fracCoords[1] + tile.fracOffset[1],
           atom.fracCoords[2] + tile.fracOffset[2],
         ]
-        const opacity = tile.isPrimary ? 1 : atomOpacity(fracPos, tilePadding, tileFade)
+        const dim = highlightElement != null && atom.element !== highlightElement ? 0.15 : 1
+        const tileOp = tile.isPrimary ? 1 : atomOpacity(fracPos, tilePadding, tileFade)
+        const opacity = tileOp * dim
         if (opacity <= 0) continue
 
         const qo = quantizeOpacity(opacity)
@@ -147,7 +151,7 @@ export function CrystalStructure({ volume, showAtoms, showAtomLabels, showAbcCel
       }
     }
     return { atomGroups: groups, labelAtoms: labels }
-  }, [lattice, structure, tiles, tilePadding, tileFade])
+  }, [lattice, structure, tiles, tilePadding, tileFade, highlightElement])
 
   const origin = useMemo(() => fracToCart(lattice, [0, 0, 0]), [lattice])
 

pkgs/core/src/components/DensityViewer.tsx

@@ -73,6 +73,8 @@ interface DensityViewerProps {
   /** Override surface color/opacity (e.g. from density-quantile ramp). If null, renderers use defaults. */
   surfaceColor?: [number, number, number] | null
   surfaceOpacityOverride?: number | null
+  /** When set, atoms of this element render normally; others fade aggressively. */
+  highlightElement?: string | null
 }
 
 export function DensityViewer({
@@ -103,6 +105,7 @@ export function DensityViewer({
   glbUrl,
   surfaceColor,
   surfaceOpacityOverride,
+  highlightElement,
 }: DensityViewerProps) {
   const tiles = useMemo(() => {
     if (tilePadding <= 0) return undefined
@@ -149,7 +152,7 @@ export function DensityViewer({
             ? <VolumeRenderer volume={volume} isoLevel={isoLevel} opacity={surfaceOpacityOverride ?? opacity} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} color={surfaceColor ?? undefined} />
             : <IsosurfaceRenderer volume={volume} isoLevel={isoLevel} opacity={surfaceOpacityOverride ?? opacity} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} color={surfaceColor ?? undefined} />
         }
-        <CrystalStructure volume={volume} showAtoms={showAtoms} showAtomLabels={showAtomLabels} showAbcCell={showAbcCell} showXyzBox={showXyzBox} dashedLines={dashedLines} lineWidth={lineWidth} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} />
+        <CrystalStructure volume={volume} showAtoms={showAtoms} showAtomLabels={showAtomLabels} showAbcCell={showAbcCell} showXyzBox={showXyzBox} dashedLines={dashedLines} lineWidth={lineWidth} tiles={tiles} tilePadding={tilePadding} tileFade={tileFade} highlightElement={highlightElement} />
         {showSlice && sliceAxis !== undefined && sliceIndex !== undefined && (
           <SlicePlane3D lattice={volume.lattice} axis={sliceAxis} sliceIndex={sliceIndex} dims={volume.grid.dims} data={volume.grid.data} padding={tilePadding} fade={tileFade} />
         )}

pkgs/static/src/App.tsx

@@ -203,7 +203,7 @@ export default function App() {
   const [showAtoms, setShowAtoms] = useUrlState('ha', boolTrueParam)
   const [showAbcCell, setShowAbcCell] = useUrlState('hc', boolTrueParam)
   const [showXyzBox, setShowXyzBox] = useUrlState('xb', boolParam)
-  const [showAtomLabels, setShowAtomLabels] = useUrlState('al', boolParam)
+  const [showAtomLabels, setShowAtomLabels] = useUrlState('al', boolTrueParam)
   const [dashedLines, setDashedLines] = useUrlState('dl', boolParam)
   const [showSlice, setShowSlice] = useUrlState('sl', boolTrueParam)
   const [sliceAxis, setSliceAxis] = useUrlState('sa', intParam(2)) as [0 | 1 | 2, (v: 0 | 1 | 2) => void]
@@ -239,6 +239,7 @@ export default function App() {
   })
   const [urlLoading, setUrlLoading] = useState(false)
   const [fetchStatus, setFetchStatus] = useState<string | null>(null)
+  const [highlightElement, setHighlightElement] = useState<string | null>(null)
   const [awsModalOpen, setAwsModalOpen] = useState(false)
   const [browseOpen, setBrowseOpen] = useState(false)
   const [awsCreds, setAwsCreds] = useState<AWSCredentials | null>(loadCredentials)
@@ -1399,6 +1400,7 @@ export default function App() {
                   glbUrl={glbUrl}
                   surfaceColor={sampledColor?.color ?? null}
                   surfaceOpacityOverride={sampledColor?.opacity ?? null}
+                  highlightElement={highlightElement}
                 />
               )}
               {showSlice && (() => {
@@ -1529,6 +1531,8 @@ export default function App() {
               onTilePaddingChange={setTilePadding}
               tileFade={tileFade}
               onTileFadeChange={setTileFade}
+              highlightElement={highlightElement}
+              onHighlightElementChange={setHighlightElement}
             />
           </ErrorBoundary>
         )}