react-cheminfo 0.11.0 → 0.13.0

package/src/orbital/core/electronConfiguration.ts

@@ -12,10 +12,13 @@
  * writes them in — `[Ar]3d⁵4s¹`, not `[Ar]4s¹3d⁵`.
  */
 
+import { formatSuperscript } from '../../format/core/superscript.ts';
+
 import { subshellLetter } from './realHarmonics.ts';
 
 /** One subshell, e.g. `{ n: 3, l: 2 }` for 3d. */
 export interface Subshell {
+  /** Principal quantum number, from 1. */
   n: number;
   /** Angular momentum quantum number: 0 = s, 1 = p, 2 = d, 3 = f. */
   l: number;
@@ -23,11 +26,12 @@ export interface Subshell {
 
 /** A subshell and how many electrons sit in it. */
 export interface SubshellOccupancy extends Subshell {
+  /** How many electrons sit in it. */
   electrons: number;
 }
 
 /** No known element occupies a shell above n = 7. */
-const MAXIMUM_PRINCIPAL_NUMBER = 7;
+export const MAXIMUM_PRINCIPAL_NUMBER = 7;
 
 /** Protons in the heaviest element that has been made. */
 export const HIGHEST_ATOMIC_NUMBER = 118;
@@ -40,7 +44,7 @@ export const NOBLE_GASES: readonly number[] = [2, 10, 18, 36, 54, 86, 118];
  * @param atomicNumber - Proton count to check.
  * @throws {Error} When it is not an integer between 1 and 118.
  */
-export function assertAtomicNumber(atomicNumber: number): void {
+function assertAtomicNumber(atomicNumber: number): void {
   if (
     !Number.isInteger(atomicNumber) ||
     atomicNumber < 1 ||
@@ -76,26 +80,26 @@ export function subshellCapacity(l: number): number {
  * rather than observed, so nothing beyond Z = 103 is listed here.
  */
 export const ELEMENT_ANOMALIES: Record<number, SubshellOccupancy[]> = {
-  24: [o(3, 2, 5), o(4, 0, 1)],
-  29: [o(3, 2, 10), o(4, 0, 1)],
-  41: [o(4, 2, 4), o(5, 0, 1)],
-  42: [o(4, 2, 5), o(5, 0, 1)],
-  44: [o(4, 2, 7), o(5, 0, 1)],
-  45: [o(4, 2, 8), o(5, 0, 1)],
-  46: [o(4, 2, 10)],
-  47: [o(4, 2, 10), o(5, 0, 1)],
-  57: [o(5, 2, 1), o(6, 0, 2)],
-  58: [o(4, 3, 1), o(5, 2, 1), o(6, 0, 2)],
-  64: [o(4, 3, 7), o(5, 2, 1), o(6, 0, 2)],
-  78: [o(4, 3, 14), o(5, 2, 9), o(6, 0, 1)],
-  79: [o(4, 3, 14), o(5, 2, 10), o(6, 0, 1)],
-  89: [o(6, 2, 1), o(7, 0, 2)],
-  90: [o(6, 2, 2), o(7, 0, 2)],
-  91: [o(5, 3, 2), o(6, 2, 1), o(7, 0, 2)],
-  92: [o(5, 3, 3), o(6, 2, 1), o(7, 0, 2)],
-  93: [o(5, 3, 4), o(6, 2, 1), o(7, 0, 2)],
-  96: [o(5, 3, 7), o(6, 2, 1), o(7, 0, 2)],
-  103: [o(5, 3, 14), o(7, 0, 2), o(7, 1, 1)],
+  24: [occupancy(3, 2, 5), occupancy(4, 0, 1)],
+  29: [occupancy(3, 2, 10), occupancy(4, 0, 1)],
+  41: [occupancy(4, 2, 4), occupancy(5, 0, 1)],
+  42: [occupancy(4, 2, 5), occupancy(5, 0, 1)],
+  44: [occupancy(4, 2, 7), occupancy(5, 0, 1)],
+  45: [occupancy(4, 2, 8), occupancy(5, 0, 1)],
+  46: [occupancy(4, 2, 10)],
+  47: [occupancy(4, 2, 10), occupancy(5, 0, 1)],
+  57: [occupancy(5, 2, 1), occupancy(6, 0, 2)],
+  58: [occupancy(4, 3, 1), occupancy(5, 2, 1), occupancy(6, 0, 2)],
+  64: [occupancy(4, 3, 7), occupancy(5, 2, 1), occupancy(6, 0, 2)],
+  78: [occupancy(4, 3, 14), occupancy(5, 2, 9), occupancy(6, 0, 1)],
+  79: [occupancy(4, 3, 14), occupancy(5, 2, 10), occupancy(6, 0, 1)],
+  89: [occupancy(6, 2, 1), occupancy(7, 0, 2)],
+  90: [occupancy(6, 2, 2), occupancy(7, 0, 2)],
+  91: [occupancy(5, 3, 2), occupancy(6, 2, 1), occupancy(7, 0, 2)],
+  92: [occupancy(5, 3, 3), occupancy(6, 2, 1), occupancy(7, 0, 2)],
+  93: [occupancy(5, 3, 4), occupancy(6, 2, 1), occupancy(7, 0, 2)],
+  96: [occupancy(5, 3, 7), occupancy(6, 2, 1), occupancy(7, 0, 2)],
+  103: [occupancy(5, 3, 14), occupancy(7, 0, 2), occupancy(7, 1, 1)],
 };
 
 /**
@@ -169,7 +173,7 @@ export function formatConfiguration(
  * @returns The label with a superscript electron count.
  */
 export function formatOccupancy(occupancy: SubshellOccupancy): string {
-  return `${subshellLabel(occupancy)}${superscript(occupancy.electrons)}`;
+  return `${subshellLabel(occupancy)}${formatSuperscript(occupancy.electrons)}`;
 }
 
 /**
@@ -181,22 +185,7 @@ export function subshellLabel(subshell: Subshell): string {
   return `${subshell.n}${subshellLetter(subshell.l)}`;
 }
 
-/**
- * Render a number in unicode superscript digits.
- * @param value - A non-negative integer.
- * @returns The digits as superscripts, e.g. `14` becomes `¹⁴`.
- */
-export function superscript(value: number): string {
-  let text = '';
-  for (const digit of String(value)) {
-    text += SUPERSCRIPT_DIGITS[Number(digit)] ?? digit;
-  }
-  return text;
-}
-
-const SUPERSCRIPT_DIGITS = ['⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹'];
-
-function o(n: number, l: number, electrons: number): SubshellOccupancy {
+function occupancy(n: number, l: number, electrons: number): SubshellOccupancy {
   return { n, l, electrons };
 }
 
@@ -226,7 +215,7 @@ function sortByShell(occupancies: SubshellOccupancy[]): SubshellOccupancy[] {
 /**
  * Madelung order: ascending `n + ℓ`, then ascending `n`. Capped at ℓ = 3 — the
  * g subshells a Madelung diagram shows after 8s are unoccupied in every known
- * element, and this site has no g harmonics to draw them with.
+ * element, and `REAL_HARMONICS` holds no g harmonics to draw them with.
  * @returns The subshells, in filling order.
  */
 function buildMadelungOrder(): Subshell[] {

package/src/orbital/core/grid.ts

@@ -36,8 +36,11 @@ export interface OrbitalGrid {
   origin: Vec3;
   /** Distance between neighbouring samples on every axis, ångström. */
   spacing: number;
+  /** Smallest sample. */
   min: number;
+  /** Largest sample. */
   max: number;
+  /** Mean of the samples. */
   mean: number;
   /** Population standard deviation of the samples. */
   sigma: number;

package/src/orbital/core/index.ts

@@ -49,6 +49,11 @@ export {
 } from './occupancy.ts';
 export type { PhasePalette, PhasePaletteId } from './palette.ts';
 export { DEFAULT_PHASE_PALETTE_ID, PHASE_PALETTES } from './palette.ts';
+export type {
+  RadialDistribution,
+  RadialDistributionOptions,
+} from './radialDistribution.ts';
+export { radialDistribution } from './radialDistribution.ts';
 export type { RealHarmonic } from './realHarmonics.ts';
 export {
   REAL_HARMONICS,

package/src/orbital/core/isovalue.ts

@@ -11,8 +11,9 @@
  * absolute `1e-5` and returns no isovalue at all — a guard against degenerate
  * data that instead reads the amplitude *scale*. Amplitudes are Å^(-3/2), so a
  * diffuse orbital is normalised straight into that range and draws nothing:
- * caesium's 6s reaches 13 Å, and 2588 of the 7460 orbitals lcao.cheminfo.org
- * offers came back blank. A quantile has no scale of its own and cannot.
+ * caesium's 6s reaches 13 Å and falls under it, as does about a third of the
+ * orbitals of the periodic table. A quantile has no scale of its own and
+ * cannot.
  *
  * Every pass below touches each of the million-odd samples, so all of them are
  * indexed loops: `for…of` over a `Float32Array` measures 6.7× slower.

package/src/orbital/core/occupancy.ts

@@ -8,11 +8,9 @@
  */
 
 import type { SubshellOccupancy } from './electronConfiguration.ts';
+import { MAXIMUM_PRINCIPAL_NUMBER } from './electronConfiguration.ts';
 import { groupRank } from './screening.ts';
 
-/** No known element occupies a shell above n = 7. */
-const HIGHEST_SHELL = 7;
-
 /**
  * Slater's rules can hand a badly-screened orbital a charge at or below zero —
  * a 7p on hydrogen, say — which has no bound hydrogen-like solution. Clamping
@@ -49,7 +47,7 @@ export function hundDistribution(
  * @returns One shell past it, never below 4 and never above 7.
  */
 export function defaultMaximumShell(valenceShell: number): number {
-  return Math.min(HIGHEST_SHELL, Math.max(4, valenceShell + 1));
+  return Math.min(MAXIMUM_PRINCIPAL_NUMBER, Math.max(4, valenceShell + 1));
 }
 
 /**

package/src/orbital/core/palette.ts

@@ -8,10 +8,11 @@
  */
 
 /** Which pair of phase colours the viewer uses. */
-export type PhasePaletteId = 'textbook' | 'colourBlindSafe';
+export type PhasePaletteId = 'textbook' | 'colorBlindSafe';
 
 /** The colours one phase palette provides. */
 export interface PhasePalette {
+  /** Key of the palette in {@link PHASE_PALETTES}. */
   id: PhasePaletteId;
   /** Name shown in the palette picker. */
   label: string;
@@ -19,9 +20,12 @@ export interface PhasePalette {
   positive: string;
   /** Lobe where the wavefunction is negative. */
   negative: string;
-  /** Lobe drawn with the `phase` display flag off. */
+  /**
+   * Lobe drawn when the phases are not told apart, for a caller that offers
+   * a sign-blind view.
+   */
   neutral: string;
-  /** Translucent disc marking a nodal plane. */
+  /** Translucent disc marking a nodal plane, for a caller that draws one. */
   node: string;
 }
 
@@ -29,7 +33,7 @@ export interface PhasePalette {
  * The two phase palettes.
  *
  * `textbook` is the blue/red of printed MO diagrams and of Jmol's signed
- * isosurfaces; `colourBlindSafe` swaps the negative lobe for the amber of the
+ * isosurfaces; `colorBlindSafe` swaps the negative lobe for the amber of the
  * Okabe-Ito qualitative palette, which stays separable under protanopia,
  * deuteranopia and tritanopia.
  */
@@ -42,8 +46,8 @@ export const PHASE_PALETTES: Record<PhasePaletteId, PhasePalette> = {
     neutral: '#9ca3af',
     node: '#64748b',
   },
-  colourBlindSafe: {
-    id: 'colourBlindSafe',
+  colorBlindSafe: {
+    id: 'colorBlindSafe',
     label: 'Blue / yellow (colour-blind safe)',
     positive: '#0072b2',
     negative: '#e69f00',

package/src/orbital/core/radialDistribution.ts

@@ -0,0 +1,97 @@
+/**
+ * The radial distribution of one orbital, sampled once for a plot: the curve,
+ * the amplitude behind it, where it peaks, and where its nodes are.
+ *
+ * A plot, its caption and its accessible label all read the same record, so
+ * the number a sentence quotes is the number the curve was drawn from.
+ */
+
+import type { HydrogenicParameters } from './hydrogenic.ts';
+import {
+  enclosingRadius,
+  radialNodeRadii,
+  radialProfile,
+} from './hydrogenic.ts';
+
+/** How finely, and how far out, the distribution is sampled. */
+export interface RadialDistributionOptions {
+  /**
+   * Samples between the nucleus and the end of the range, at least 2.
+   * @default 600
+   */
+  samples?: number;
+  /**
+   * Share of the electron the sampled range must hold, between 0 and 1. The
+   * range is then widened by a tenth, so the tail is seen flattening out.
+   * @default 0.995
+   */
+  enclosed?: number;
+}
+
+/** One orbital's radial distribution, as a plot reads it. */
+export interface RadialDistribution {
+  /** Distance of every sample from the nucleus, ångström, from 0 to `limit`. */
+  distances: Float64Array;
+  /** The radial function `R(r)` at each sample, Å^(-3/2), signed. */
+  amplitude: Float64Array;
+  /** The radial distribution `r²R(r)²` at each sample, Å⁻¹. */
+  density: Float64Array;
+  /** Where the sampled range ends, ångström. */
+  limit: number;
+  /** The largest value of `density`. */
+  peakDensity: number;
+  /** The largest magnitude of `amplitude`. */
+  peakAmplitude: number;
+  /** The sampled distance at which `density` peaks, ångström. */
+  peakDistance: number;
+  /** The radii of the radial nodes, ångström, ascending. */
+  nodeRadii: number[];
+}
+
+/** How much the range is widened past the enclosing sphere. */
+const RANGE_MARGIN = 1.1;
+
+/**
+ * Sample the radial distribution of an orbital over the range that holds it.
+ * @param parameters - Which orbital, and how strongly it is bound.
+ * @param options - See {@link RadialDistributionOptions}.
+ * @returns The samples, their extremes and the node radii.
+ * @throws {Error} When the quantum numbers are not a real orbital, the charge
+ * is not positive, `enclosed` is outside `(0, 1)` or `samples` is below 2.
+ */
+export function radialDistribution(
+  parameters: HydrogenicParameters,
+  options: RadialDistributionOptions = {},
+): RadialDistribution {
+  const { samples = 600, enclosed = 0.995 } = options;
+  const limit = enclosingRadius(parameters, enclosed) * RANGE_MARGIN;
+  const { distances, amplitude, density } = radialProfile(
+    parameters,
+    limit,
+    samples,
+  );
+
+  let peakDensity = 0;
+  let peakDistance = 0;
+  let peakAmplitude = 0;
+  for (let index = 0; index < samples; index++) {
+    const value = density[index] as number;
+    if (value > peakDensity) {
+      peakDensity = value;
+      peakDistance = distances[index] as number;
+    }
+    const magnitude = Math.abs(amplitude[index] as number);
+    if (magnitude > peakAmplitude) peakAmplitude = magnitude;
+  }
+
+  return {
+    distances,
+    amplitude,
+    density,
+    limit,
+    peakDensity,
+    peakAmplitude,
+    peakDistance,
+    nodeRadii: radialNodeRadii(parameters, limit),
+  };
+}

package/src/orbital/core/realHarmonics.ts

@@ -11,8 +11,8 @@
  * this file is where that fact becomes visible: `s` has none, every `p` has one
  * plane, every `d` two surfaces, every `f` three.
  *
- * `key` is ascii and appears in a URL — `#/elements/Fe/3dx2-y2`; `label` is the
- * typeset subscript a student reads.
+ * `key` is ascii and url-safe, so an orbital id such as `3dx2-y2` can sit in
+ * an address; `label` is the typeset subscript a student reads.
  */
 
 /** Subshell letter for an angular momentum, `s p d f`. */
@@ -150,7 +150,7 @@ export const REAL_HARMONICS: RealHarmonic[][] = [
  * The harmonics of one subshell.
  * @param l - Angular momentum quantum number, 0 to 3.
  * @returns Its `2ℓ + 1` real harmonics, in list order.
- * @throws {Error} When ℓ is outside the s, p, d and f shells this site draws.
+ * @throws {Error} When ℓ is outside the s, p, d and f shells.
  */
 export function harmonicsOf(l: number): RealHarmonic[] {
   const shell = REAL_HARMONICS[l];

package/src/orbital/ui/AtomicOrbitalCanvas.tsx

@@ -6,24 +6,26 @@
  * reason the two components are separate files.
  */
 
-import { Button } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
-import type { HelpContent } from '../../help/ui/HelpBody.tsx';
-import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+import { errorMessage } from '../../error/core/index.ts';
+import { useResizeObserver } from '../../hooks/ui/useResizeObserver.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { ResolutionLimits } from '../core/atomicGrid.ts';
 import type { PhasePalette } from '../core/palette.ts';
 import { PHASE_PALETTES } from '../core/palette.ts';
 import type { AtomicSampler } from '../core/sample.ts';
 import { sampleInProcess } from '../core/sample.ts';
 
+import { AtomicOrbitalControls } from './AtomicOrbitalControls.tsx';
 import { DEFAULT_SPIN_SPEED } from './camera.ts';
+import { fitAxes, resolutionKey } from './orbitalCanvasHelpers.ts';
 import type { OrbitalViewer } from './viewer.ts';
 import { createOrbitalViewer } from './viewer.ts';
 
 /** Props of {@link AtomicOrbitalCanvas}. */
-export interface AtomicOrbitalCanvasProps {
+interface AtomicOrbitalCanvasProps {
   /** Proton count of the element on screen. */
   atomicNumber: number;
   /** Which orbital of it, e.g. `3dz2`. */
@@ -84,10 +86,11 @@ export interface AtomicOrbitalCanvasProps {
    */
   onNodeRadii?: (radii: number[]) => void;
   /**
-   * Called when an orbital cannot be drawn, with the reason.
+   * Called with the reason when an orbital cannot be drawn, and with `null`
+   * once one has been drawn again.
    * @default undefined
    */
-  onError?: (message: string) => void;
+  onFailureChange?: (message: string | null) => void;
 }
 
 /**
@@ -109,7 +112,7 @@ export function AtomicOrbitalCanvas(
     sample = sampleInProcess,
     onAxesChange,
     onNodeRadii,
-    onError,
+    onFailureChange,
   } = props;
 
   const containerRef = useRef<HTMLDivElement>(null);
@@ -132,9 +135,9 @@ export function AtomicOrbitalCanvas(
 
   // Callbacks are read through refs so a caller passing an inline arrow does
   // not re-sample the orbital on every render of its parent.
-  const callbacks = useRef({ onAxesChange, onNodeRadii, onError });
+  const callbacks = useRef({ onAxesChange, onNodeRadii, onFailureChange });
   useEffect(() => {
-    callbacks.current = { onAxesChange, onNodeRadii, onError };
+    callbacks.current = { onAxesChange, onNodeRadii, onFailureChange };
   });
 
   // Created and disposed once per mount. React 19 runs this twice in
@@ -145,17 +148,16 @@ export function AtomicOrbitalCanvas(
     if (container === null) return;
     const viewer = createOrbitalViewer(container);
     viewerRef.current = viewer;
-    const observer = new ResizeObserver(() => {
-      viewer.handleResize();
-    });
-    observer.observe(container);
     return () => {
-      observer.disconnect();
       viewerRef.current = null;
       viewer.dispose();
     };
   }, []);
 
+  useResizeObserver(containerRef, () => {
+    viewerRef.current?.handleResize();
+  });
+
   useEffect(() => {
     const viewer = viewerRef.current;
     if (viewer === null) return;
@@ -165,18 +167,18 @@ export function AtomicOrbitalCanvas(
         if (cancelled) return;
         callbacks.current.onNodeRadii?.(result.nodeRadii);
         const reach = await viewer.showOrbital(result.grid, result.contour, {
-          positiveColour: palette.positive,
-          negativeColour: palette.negative,
+          positiveColor: palette.positive,
+          negativeColor: palette.negative,
         });
         reachRef.current = reach ?? null;
         await viewer.refit(await fitAxes(viewer, reach, axesRef.current));
-        if (!cancelled) setDrawn(wanted);
+        if (cancelled) return;
+        setDrawn(wanted);
+        callbacks.current.onFailureChange?.(null);
       })
       .catch((error: unknown) => {
         if (cancelled) return;
-        callbacks.current.onError?.(
-          error instanceof Error ? error.message : String(error),
-        );
+        callbacks.current.onFailureChange?.(errorMessage(error));
       });
     return () => {
       cancelled = true;
@@ -200,89 +202,23 @@ export function AtomicOrbitalCanvas(
   return (
     <div ref={containerRef} style={CANVAS_STYLE}>
       {busy && <div style={BUSY_STYLE}>Sampling…</div>}
-      <div style={CONTROLS_STYLE}>
-        <HelpTooltip content={AXES_HELP} placement="bottom">
-          <Button
-            variant="minimal"
-            size="small"
-            icon="grid"
-            active={axes}
-            aria-label="Show the x, y, z axes"
-            aria-pressed={axes}
-            onClick={() => {
-              setAxes(!axes);
-              callbacks.current.onAxesChange?.(!axes);
-            }}
-          />
-        </HelpTooltip>
-        <HelpTooltip content={RESET_HELP} placement="bottom">
-          <Button
-            variant="minimal"
-            size="small"
-            icon="zoom-to-fit"
-            aria-label="Reset the view"
-            onClick={() => {
-              void viewerRef.current?.resetView();
-            }}
-          />
-        </HelpTooltip>
-      </div>
+      <AtomicOrbitalControls
+        axes={axes}
+        onToggleAxes={() => {
+          setAxes(!axes);
+          callbacks.current.onAxesChange?.(!axes);
+        }}
+        onResetView={() => {
+          void viewerRef.current?.resetView();
+        }}
+      />
     </div>
   );
 }
 
-/**
- * Draw the cartesian frame around the orbital, or remove it.
- * @param viewer - The viewer holding the canvas.
- * @param reach - How far the drawn surface reaches, as `showOrbital` returned
- * it.
- * @param axes - Whether the frame is wanted.
- * @returns What the camera has to fit: the frame reaches past the surface, so
- * turning it on has to zoom out or the labels sit off screen.
- */
-async function fitAxes(
-  viewer: OrbitalViewer,
-  reach: number | undefined,
-  axes: boolean,
-): Promise<number | undefined> {
-  if (!axes) {
-    await viewer.hideAxes();
-    return reach;
-  }
-  if (reach === undefined) return undefined;
-  return (await viewer.showAxes(reach)) ?? reach;
-}
-
-/** What the frame button says it is for. */
-const AXES_HELP: HelpContent = {
-  title: 'Cartesian axes',
-  body: 'Draw x, y and z through the nucleus. The label names an orbital by where its lobes sit against them.',
-  example: {
-    code: '3d_yz',
-    note: 'four lobes between the y and z axes, none on either.',
-  },
-};
-
-/** What the reset button says it is for. */
-const RESET_HELP: HelpContent = {
-  title: 'Reset the view',
-  body: 'Back to the angle and zoom the orbital opened on. A change of orbital keeps whatever view you have turned it to.',
-};
-
 /** Samples per edge; 56 resolves the radial node of a 3s in about 25 ms. */
 const DEFAULT_RESOLUTION = 56;
 
-/**
- * A stable identity for either shape the resolution prop can take.
- * @param resolution - A fixed sample count, or the limits it may vary between.
- * @returns A string that changes exactly when the sampling would.
- */
-function resolutionKey(resolution: number | ResolutionLimits): string {
-  return typeof resolution === 'number'
-    ? String(resolution)
-    : `${resolution.floor}-${resolution.cap}`;
-}
-
 /**
  * A square, centred stage: an atomic orbital is as tall as it is wide, so a
  * square wastes the least of the frame and keeps the lobes the same size when
@@ -299,20 +235,6 @@ const CANVAS_STYLE: CSSProperties = {
   overflow: 'hidden',
 };
 
-/**
- * The two controls the canvas owns: the frame, and the way back to the framing
- * the orbital opened on — a change of orbital now keeps whatever angle and zoom
- * the student is on.
- */
-const CONTROLS_STYLE: CSSProperties = {
-  position: 'absolute',
-  top: 4,
-  right: 4,
-  zIndex: 1,
-  display: 'flex',
-  gap: 2,
-};
-
 const BUSY_STYLE: CSSProperties = {
   position: 'absolute',
   top: 8,
@@ -320,7 +242,8 @@ const BUSY_STYLE: CSSProperties = {
   zIndex: 1,
   padding: '3px 8px',
   borderRadius: 3,
-  background: 'rgba(255, 255, 255, 0.85)',
-  color: 'var(--text-muted, #5f6b7c)',
+  background: TOKEN.surface,
+  opacity: 0.85,
+  color: TOKEN.textMuted,
   fontSize: 11,
 };

package/src/orbital/ui/AtomicOrbitalControls.tsx

@@ -0,0 +1,81 @@
+/**
+ * The two controls an orbital canvas owns: the cartesian frame, and the way
+ * back to the framing the orbital opened on — a change of orbital keeps
+ * whatever angle and zoom the student is on.
+ */
+
+import { Button } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+
+/** Props of {@link AtomicOrbitalControls}. */
+interface AtomicOrbitalControlsProps {
+  /** Whether the frame is drawn. */
+  axes: boolean;
+  /** Called when the frame button is pressed. */
+  onToggleAxes: () => void;
+  /** Called when the reset button is pressed. */
+  onResetView: () => void;
+}
+
+/**
+ * The frame and reset buttons, in the canvas's top-right corner.
+ * @param props - See {@link AtomicOrbitalControlsProps}.
+ * @returns The two buttons.
+ */
+export function AtomicOrbitalControls(
+  props: AtomicOrbitalControlsProps,
+): ReactElement {
+  const { axes, onToggleAxes, onResetView } = props;
+  return (
+    <div style={CONTROLS_STYLE}>
+      <HelpTooltip content={AXES_HELP} placement="bottom">
+        <Button
+          variant="minimal"
+          size="small"
+          icon="grid"
+          active={axes}
+          aria-label="Show the x, y, z axes"
+          aria-pressed={axes}
+          onClick={onToggleAxes}
+        />
+      </HelpTooltip>
+      <HelpTooltip content={RESET_HELP} placement="bottom">
+        <Button
+          variant="minimal"
+          size="small"
+          icon="zoom-to-fit"
+          aria-label="Reset the view"
+          onClick={onResetView}
+        />
+      </HelpTooltip>
+    </div>
+  );
+}
+
+/** What the frame button says it is for. */
+const AXES_HELP: HelpContent = {
+  title: 'Cartesian axes',
+  body: 'Draw x, y and z through the nucleus. The label names an orbital by where its lobes sit against them.',
+  example: {
+    code: '3d_yz',
+    note: 'four lobes between the y and z axes, none on either.',
+  },
+};
+
+/** What the reset button says it is for. */
+const RESET_HELP: HelpContent = {
+  title: 'Reset the view',
+  body: 'Back to the angle and zoom the orbital opened on. A change of orbital keeps whatever view you have turned it to.',
+};
+
+const CONTROLS_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 4,
+  right: 4,
+  zIndex: 1,
+  display: 'flex',
+  gap: 2,
+};