react-cheminfo 0.11.0 → 0.13.0

package/src/router/core/query.ts

@@ -1,5 +1,8 @@
 import { safeDecode } from './address.ts';
 
+/** One `key=value` pair of a query string, already decoded. */
+export type QueryEntry = readonly [key: string, value: string];
+
 /** How a query string is read and written. */
 export interface QueryStringOptions {
   /**
@@ -19,22 +22,21 @@ export interface QueryStringOptions {
 }
 
 /**
- * Read a query string.
+ * Read a query string into its pairs, in the order it wrote them.
  *
- * Forgiving by design, because the address is hand-editable and arrives from
- * bookmarks, course pages and lecture slides: a repeated key keeps its last
- * value, a key carrying nothing is kept as an empty value so a bare `?embed`
- * reads as present, and an escape that does not decode is taken literally.
- * @param search - The query string, with or without its leading `?`.
+ * A bare key reads as a key carrying the empty string, so `?embed` is present.
+ * An empty key is not a parameter and is skipped, and an escape that does not
+ * decode is taken literally, because the address is hand-editable.
+ * @param search - The query string, with or without its leading `?`, and without a fragment.
  * @param options - How the values are decoded.
- * @returns One entry per key, decoded.
+ * @returns The pairs, decoded.
  */
-export function parseQueryString(
+export function parseQueryEntries(
   search: string,
   options: QueryStringOptions = {},
-): Record<string, string> {
+): QueryEntry[] {
   const literalPlus = options.literalPlus ?? true;
-  const query: Record<string, string> = {};
+  const entries: QueryEntry[] = [];
   const text = search.startsWith('?') ? search.slice(1) : search;
   for (const part of text.split('&')) {
     if (part === '') continue;
@@ -43,13 +45,71 @@ export function parseQueryString(
     const rawValue = index === -1 ? '' : part.slice(index + 1);
     const key = decodeValue(rawKey, literalPlus);
     if (key === '') continue;
-    query[key] = decodeValue(rawValue, literalPlus);
+    entries.push([key, decodeValue(rawValue, literalPlus)]);
+  }
+  return entries;
+}
+
+/**
+ * Write pairs back into a query string, in the order given.
+ *
+ * A pair carrying the empty string is written as its bare key, which reads back
+ * as itself. A `+` is written `%2B`, because every other parser of the address
+ * reads a bare one as a space.
+ * @param entries - The pairs to write.
+ * @returns The query string, without its leading `?`.
+ */
+export function formatQueryEntries(entries: readonly QueryEntry[]): string {
+  const parts: string[] = [];
+  for (const [key, value] of entries) {
+    if (key === '') continue;
+    const name = encodeValue(key);
+    parts.push(value === '' ? name : `${name}=${encodeValue(value)}`);
+  }
+  return parts.join('&');
+}
+
+/**
+ * The first value each key carries, which is what a link means when it names
+ * the same parameter twice.
+ * @param entries - The pairs of a query string.
+ * @returns One value per key, in the order the keys first appear.
+ */
+export function firstQueryValues(
+  entries: readonly QueryEntry[],
+): Map<string, string> {
+  const values = new Map<string, string>();
+  for (const [key, value] of entries) {
+    if (!values.has(key)) values.set(key, value);
+  }
+  return values;
+}
+
+/**
+ * Read a query string into one value per key.
+ *
+ * Forgiving by design, because the address arrives from bookmarks, course pages
+ * and lecture slides: a repeated key keeps its first value, a bare key such as
+ * `?embed` reads as present, and an escape that does not decode is taken
+ * literally.
+ * @param search - The query string, with or without its leading `?`.
+ * @param options - How the values are decoded.
+ * @returns One entry per key, decoded.
+ */
+export function parseQueryString(
+  search: string,
+  options: QueryStringOptions = {},
+): Record<string, string> {
+  const query: Record<string, string> = {};
+  const values = firstQueryValues(parseQueryEntries(search, options));
+  for (const [key, value] of values) {
+    query[key] = value;
   }
   return query;
 }
 
 /**
- * Write a query string.
+ * Write a query string from one value per key.
  *
  * A parameter left at nothing is dropped unless `keepEmptyValues` asks for it,
  * and `undefined` or `null` removes a parameter outright, so a page can hand
@@ -63,16 +123,13 @@ export function formatQueryString(
   options: QueryStringOptions = {},
 ): string {
   const keepEmptyValues = options.keepEmptyValues ?? false;
-  const parts: string[] = [];
+  const entries: QueryEntry[] = [];
   for (const [key, value] of Object.entries(params)) {
-    if (key === '' || value === undefined || value === null) continue;
-    if (value === '') {
-      if (keepEmptyValues) parts.push(encodeValue(key));
-      continue;
-    }
-    parts.push(`${encodeValue(key)}=${encodeValue(value)}`);
+    if (value === undefined || value === null) continue;
+    if (value === '' && !keepEmptyValues) continue;
+    entries.push([key, value]);
   }
-  return parts.join('&');
+  return formatQueryEntries(entries);
 }
 
 // A comma is legal in a query value and is what separates the keys of `hide`

package/src/router/core/siteAddresses.ts

@@ -0,0 +1,98 @@
+import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { siteUrl } from '../../ecosystem/core/sites.ts';
+
+import {
+  joinBasePath,
+  normalizeBasePath,
+  readMountPath,
+  stripBasePath,
+} from './basePath.ts';
+
+/**
+ * The addresses of one site of the family: where this deployment is mounted,
+ * the address the site names as its own, and the conversions between the
+ * site's own paths and what the browser shows.
+ *
+ * The mount is read off the page, not off the build: the build carries no
+ * mount, and the `<base>` a deployment stamps into its pages is what tells
+ * `https://surge.cheminfo.org/` from `https://www.cheminfo.org/surge/`. Under
+ * Node there is no page, and the mount is the root.
+ * @param siteId - The site, as `ECOSYSTEM_SITES` names it.
+ * @param options - A mount path to use instead of the one read off the page.
+ * @returns The site's addresses.
+ * @throws {Error} When no site of the family carries that identifier.
+ */
+export function createSiteAddresses(
+  siteId: SiteId,
+  options: SiteAddressesOptions = {},
+): SiteAddresses {
+  const site = siteById(siteId);
+  const ownUrl = siteUrl(site);
+  const basePath = normalizeBasePath(options.basePath ?? readMountPath());
+
+  function withBase(path: string): string {
+    return joinBasePath(basePath, path);
+  }
+
+  function pathWithoutBase(pathname: string): string {
+    return stripBasePath(basePath, pathname);
+  }
+
+  function absoluteUrl(path: string): string {
+    const location = globalThis.location as Location | undefined;
+    const origin = location?.origin ?? new URL(ownUrl).origin;
+    return `${origin}${withBase(path)}`;
+  }
+
+  function configuredSiteUrl(): string {
+    const environment = (
+      globalThis as { process?: { env?: Record<string, string | undefined> } }
+    ).process?.env?.SITE_URL;
+    return environment || ownUrl;
+  }
+
+  return {
+    basePath,
+    siteName: siteDisplayName(site),
+    siteUrl: ownUrl,
+    withBase,
+    pathWithoutBase,
+    absoluteUrl,
+    configuredSiteUrl,
+  };
+}
+
+/** How {@link createSiteAddresses} reads the mount. */
+export interface SiteAddressesOptions {
+  /**
+   * The path the deployment is mounted at, for a build script or a test that
+   * knows it.
+   * @default the mount read off the page's `<base>`, or '' under Node
+   */
+  basePath?: string;
+}
+
+/** The addresses of one site of the family. */
+export interface SiteAddresses {
+  /** The mount path: '' on a host of its own, `/surge` under a shared one. */
+  basePath: string;
+  /** What the tab, the social card and the sitemap call the site. */
+  siteName: string;
+  /** The site's own address, e.g. `https://smiles.cheminfo.org/`. */
+  siteUrl: string;
+  /** One of the site's own paths, under the mount, as the browser writes it. */
+  withBase: (path: string) => string;
+  /** The site's own path behind what `location.pathname` reads. */
+  pathWithoutBase: (pathname: string) => string;
+  /**
+   * One of the site's paths written out in full, on the origin the page is
+   * served from — or the site's own origin where there is no page.
+   */
+  absoluteUrl: (path: string) => string;
+  /**
+   * The address a build names as its own: `SITE_URL` from the environment when
+   * it says something, the site's own address otherwise.
+   */
+  configuredSiteUrl: () => string;
+}

package/src/router/core/tabRouter.ts

@@ -1,6 +1,6 @@
-import { splitAddress, splitPath } from './address.ts';
+import { splitAddress, splitPath, trimTrailingSlash } from './address.ts';
 import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
-import { pathFromLegacyHash } from './legacyHash.ts';
+import { adoptLegacyHashAddress, pathFromLegacyHash } from './legacyHash.ts';
 import type { QueryStringOptions } from './query.ts';
 import { formatQueryString, parseQueryString } from './query.ts';
 
@@ -72,7 +72,17 @@ export function createTabRouter<Tab extends string>(
     return search === '' ? address : `${address}?${search}`;
   }
 
-  return { parse, format, isTab };
+  function legacyAddress(address: string): string | null {
+    if (mode !== 'path' || !adoptLegacyHash) return null;
+    const adopted = adoptLegacyHashAddress(address, { basePath });
+    if (adopted === null) return null;
+    const route = parse(adopted);
+    const path = format({ tab: route.tab, id: route.id });
+    const { search } = splitAddress(adopted);
+    return search === '' ? path : `${path}?${search}`;
+  }
+
+  return { mode, parse, format, isTab, legacyAddress };
 }
 
 /** A tab whose address carries more than the tab's own name. */
@@ -167,6 +177,8 @@ export interface TabRouteInput<Tab extends string = string> {
 
 /** The string ↔ route mapping of a site. */
 export interface TabRouter<Tab extends string = string> {
+  /** Whether the route lives in the path or in the fragment. */
+  mode: 'path' | 'hash';
   /**
    * The route an address denotes. An unknown tab, a trailing slash, an empty
    * address and an escape that does not decode all resolve to something
@@ -177,6 +189,13 @@ export interface TabRouter<Tab extends string = string> {
   format: (route: TabRouteInput<Tab>) => string;
   /** Whether a string read out of an address names one of the site's tabs. */
   isTab: (value: string) => value is Tab;
+  /**
+   * The address to put in the bar in place of a link written before the site
+   * routed by path: the page it names as this router writes it, with the query
+   * string kept as it was. `null` when the address is no such link, or when the
+   * router does not adopt them.
+   */
+  legacyAddress: (address: string) => string | null;
 }
 
 interface NormalizedTab {
@@ -208,7 +227,5 @@ function readAddress(
 }
 
 function normalizeTabPath(path: string): string {
-  const opened = path.startsWith('/') ? path : `/${path}`;
-  const closed = opened.replace(/\/+$/, '');
-  return closed === '' ? '/' : closed;
+  return trimTrailingSlash(path.startsWith('/') ? path : `/${path}`);
 }

package/src/router/ui/index.ts

@@ -0,0 +1 @@
+export { useTabRoute } from './useTabRoute.ts';

package/src/router/ui/useTabRoute.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+
+import {
+  currentAddress,
+  readRoute,
+  subscribeToRoute,
+} from '../core/history.ts';
+import type { TabRoute, TabRouter } from '../core/tabRouter.ts';
+
+/**
+ * The route the browser is showing, re-rendered on every move — back, forward,
+ * and every `writeRoute` the app makes.
+ *
+ * A legacy hash link is replaced by its path once, after the first render, when
+ * the router adopts such links.
+ * @param router - The site's router, created once at module level.
+ * @returns The route of the address on screen.
+ */
+export function useTabRoute<Tab extends string>(
+  router: TabRouter<Tab>,
+): TabRoute<Tab> {
+  const subscribe = useCallback(
+    (onChange: () => void) => subscribeToRoute(router, onChange),
+    [router],
+  );
+  const address = useSyncExternalStore(
+    subscribe,
+    currentAddress,
+    currentAddress,
+  );
+  useEffect(() => {
+    readRoute(router);
+  }, [router]);
+  return useMemo(() => router.parse(address), [router, address]);
+}

package/src/scatter/core/confidenceEllipse.ts

@@ -6,19 +6,13 @@
  * axes rarely carry the same number of pixels per unit.
  */
 
-import { standardDeviationsForCoverage } from './ellipseCoverage.ts';
+import type { MatrixLike } from '../../chart/core/matrix.ts';
 
-/**
- * A smaller eigenvalue below this share of the larger one is read as zero.
- *
- * A group whose spread across the major axis is under a millionth of its
- * spread along it is collinear for any purpose a plot has, and the rounding of
- * the covariance alone reaches that far: the nine points on a straight line
- * used in the tests leave a residue of about 5e-17 where the exact answer is
- * 0. Without the floor those points would draw a hairline ellipse on one
- * machine and a segment on the next.
- */
-const COLLINEAR_FLOOR = 1e-12;
+import type { EllipseCovariance } from './ellipseAxes.ts';
+import { ellipseAxes } from './ellipseAxes.ts';
+import { standardDeviationsForCoverage } from './ellipseCoverage.ts';
+import type { ScatterGroupMoments } from './scatterGroupMoments.ts';
+import { scatterGroupMoments } from './scatterGroupMoments.ts';
 
 /** A point of a cloud, or of an outline drawn around one, in data units. */
 export interface EllipsePoint {
@@ -54,15 +48,11 @@ export interface EllipseStandardDeviationSize {
  */
 export type EllipseSize = EllipseCoverageSize | EllipseStandardDeviationSize;
 
-/** How a cloud is spread, as the three distinct entries of its covariance. */
-export interface EllipseCovariance {
-  /** The spread along the horizontal axis. */
-  xx: number;
-  /** How the two axes move together; zero when they are unrelated. */
-  xy: number;
-  /** The spread along the vertical axis. */
-  yy: number;
-}
+/** What a group is outlined at when the caller says nothing: the share holding 95 % of it. */
+export const DEFAULT_ELLIPSE_SIZE: EllipseSize = {
+  kind: 'coverage',
+  probability: 0.95,
+};
 
 /** A group outline, in data units. */
 export interface ConfidenceEllipse {
@@ -114,101 +104,65 @@ export function confidenceEllipse(
   points: readonly EllipsePoint[],
   options: ConfidenceEllipseOptions = {},
 ): ConfidenceEllipse | null {
-  const { size = { kind: 'coverage', probability: 0.95 }, minimumPoints = 3 } =
-    options;
-
-  let count = 0;
-  let sumX = 0;
-  let sumY = 0;
-  for (const point of points) {
-    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) continue;
-    count++;
-    sumX += point.x;
-    sumY += point.y;
-  }
-  if (count < Math.max(2, minimumPoints)) return null;
-
-  const cx = sumX / count;
-  const cy = sumY / count;
-  let spreadX = 0;
-  let together = 0;
-  let spreadY = 0;
-  for (const point of points) {
-    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) continue;
-    const dx = point.x - cx;
-    const dy = point.y - cy;
-    spreadX += dx * dx;
-    together += dx * dy;
-    spreadY += dy * dy;
-  }
-
-  const divisor = count - 1;
-  const covariance: EllipseCovariance = {
-    xx: spreadX / divisor,
-    xy: together / divisor,
-    yy: spreadY / divisor,
-  };
-  if (
-    !Number.isFinite(cx) ||
-    !Number.isFinite(cy) ||
-    !Number.isFinite(covariance.xx) ||
-    !Number.isFinite(covariance.xy) ||
-    !Number.isFinite(covariance.yy)
-  ) {
-    return null;
-  }
+  const { size = DEFAULT_ELLIPSE_SIZE, minimumPoints = 3 } = options;
+  const moments = scatterGroupMoments(pointMatrix(points), null, 1, 2);
+  return momentsEllipse(moments, {
+    group: 0,
+    xAxis: 0,
+    yAxis: 1,
+    standardDeviations: ellipseStandardDeviations(size),
+    minimumPoints,
+  });
+}
 
-  const { rx, ry, angle } = ellipseAxes(
-    covariance,
-    ellipseStandardDeviations(size),
-  );
-  if (!Number.isFinite(rx) || !Number.isFinite(ry)) return null;
-  return { cx, cy, rx, ry, angle, count, covariance };
+/** Which outline {@link momentsEllipse} cuts out of a block of moments. */
+interface MomentsEllipseOptions {
+  /** Which group. */
+  group: number;
+  /** The axis the outline's `x` is read along. */
+  xAxis: number;
+  /** The axis its `y` is read along. */
+  yAxis: number;
+  /** How far out to draw, in standard deviations. */
+  standardDeviations: number;
+  /** How many rows the group needs before it has a shape; below two is read as two. */
+  minimumPoints: number;
 }
 
 /**
- * The semi-axes and the rotation that a covariance describes.
+ * One group's outline for one pair of axes, cut out of measured moments.
  *
- * The shape of an outline is the eigen-decomposition of a symmetric two by two
- * matrix, which has a closed form and so never needs an iterative solver. It
- * is public because the same three numbers are what turns any covariance into
- * something drawable — one measured elsewhere, or one already mapped into
- * pixels.
- * @param covariance - How the cloud is spread.
- * @param standardDeviations - How far out to measure. Defaults to `1`.
- * @returns The two semi-axis lengths and the rotation of the major one, in radians, in `(-π/2, π/2]`. A collinear cloud gives `ry` of exactly `0`, and one with no spread at all gives an angle of `0` because it has no direction to report.
+ * The two-by-two block of a covariance is a covariance in its own right, so a
+ * pair grid measuring every axis at once and a map measuring one pair give
+ * the same outline for the same samples.
+ * @param moments - The block, from `scatterGroupMoments`.
+ * @param options - See {@link MomentsEllipseOptions}.
+ * @returns The outline, or `null` when the group is too small to have a shape, when either axis or the group is outside the block, or when the size or the coordinates are not finite.
  */
-export function ellipseAxes(
-  covariance: EllipseCovariance,
-  standardDeviations = 1,
-): Pick<ConfidenceEllipse, 'rx' | 'ry' | 'angle'> {
-  const { xx, xy, yy } = covariance;
-  const middle = (xx + yy) / 2;
-  const half = (xx - yy) / 2;
-  const radius = Math.hypot(half, xy);
-  const major = middle + radius;
-  let minor = middle - radius;
-  if (!(minor > major * COLLINEAR_FLOOR)) minor = 0;
-  return {
-    rx: standardDeviations * Math.sqrt(major),
-    ry: standardDeviations * Math.sqrt(minor),
-    angle: majorAxisAngle(xx, xy, yy, major),
-  };
-}
+export function momentsEllipse(
+  moments: ScatterGroupMoments,
+  options: MomentsEllipseOptions,
+): ConfidenceEllipse | null {
+  const { axes, groups, counts, means, covariances } = moments;
+  const { group, xAxis, yAxis, standardDeviations, minimumPoints } = options;
+  if (group < 0 || group >= groups) return null;
+  if (xAxis < 0 || yAxis < 0 || xAxis >= axes || yAxis >= axes) return null;
+  const count = counts[group] ?? 0;
+  if (count < Math.max(2, minimumPoints)) return null;
 
-function majorAxisAngle(
-  xx: number,
-  xy: number,
-  yy: number,
-  major: number,
-): number {
-  // With no cross term the axes already are the eigenvectors, and asking
-  // `atan2` would only turn the exact answer into a rounded one.
-  if (xy === 0) return xx >= yy ? 0 : Math.PI / 2;
-  // `major - xx` is never negative, so this lands in [0, π] and a negative
-  // cross term arrives half a turn away from the direction actually wanted.
-  const angle = Math.atan2(major - xx, xy);
-  return angle > Math.PI / 2 ? angle - Math.PI : angle;
+  const base = group * axes;
+  const block = group * axes * axes;
+  const covariance: EllipseCovariance = {
+    xx: covariances[block + xAxis * axes + xAxis] ?? 0,
+    xy: covariances[block + xAxis * axes + yAxis] ?? 0,
+    yy: covariances[block + yAxis * axes + yAxis] ?? 0,
+  };
+  const { rx, ry, angle } = ellipseAxes(covariance, standardDeviations);
+  const cx = means[base + xAxis] ?? 0;
+  const cy = means[base + yAxis] ?? 0;
+  if (!Number.isFinite(rx) || !Number.isFinite(ry)) return null;
+  if (!Number.isFinite(cx) || !Number.isFinite(cy)) return null;
+  return { cx, cy, rx, ry, angle, count, covariance };
 }
 
 /**
@@ -228,3 +182,20 @@ export function ellipseStandardDeviations(size: EllipseSize): number {
   }
   return standardDeviationsForCoverage(size.probability);
 }
+
+/*
+ * A run of points read as a two-column matrix, so a group handed as objects
+ * is measured by the same scan as one handed as a score matrix.
+ */
+function pointMatrix(points: readonly EllipsePoint[]): MatrixLike {
+  return {
+    rows: points.length,
+    columns: 2,
+    get(rowIndex: number, columnIndex: number): number {
+      const point = points[rowIndex];
+      if (point === undefined) return Number.NaN;
+      if (columnIndex === 0) return point.x;
+      return columnIndex === 1 ? point.y : Number.NaN;
+    },
+  };
+}

package/src/scatter/core/ellipseAxes.ts

@@ -0,0 +1,85 @@
+/**
+ * The shape a covariance describes: two semi-axes and the turn of the longer
+ * one, from the closed form of a symmetric two by two eigen-decomposition.
+ *
+ * It is its own module because a map outline, a pair-grid cell and the
+ * silhouette of a shell in a cloud all end in this same decomposition, and a
+ * second copy of it is a second collinear floor to forget.
+ */
+
+/**
+ * A smaller eigenvalue below this share of the larger one is read as zero.
+ *
+ * A group whose spread across the major axis is under a millionth of its
+ * spread along it is collinear for any purpose a plot has, and the rounding of
+ * the covariance alone reaches that far: the nine points on a straight line
+ * used in the tests leave a residue of about 5e-17 where the exact answer is
+ * 0. Without the floor those points would draw a hairline ellipse on one
+ * machine and a segment on the next.
+ */
+const COLLINEAR_FLOOR = 1e-12;
+
+/** How a cloud is spread, as the three distinct entries of its covariance. */
+export interface EllipseCovariance {
+  /** The spread along the horizontal axis. */
+  xx: number;
+  /** How the two axes move together; zero when they are unrelated. */
+  xy: number;
+  /** The spread along the vertical axis. */
+  yy: number;
+}
+
+/** The drawable shape of a covariance. */
+export interface EllipseAxes {
+  /** Semi-major axis length. */
+  rx: number;
+  /** Semi-minor axis length; exactly `0` when the spread is collinear. */
+  ry: number;
+  /** Rotation of the major axis, in radians counter-clockwise, in `(-π/2, π/2]`. */
+  angle: number;
+}
+
+/**
+ * The semi-axes and the rotation that a covariance describes.
+ *
+ * The shape of an outline is the eigen-decomposition of a symmetric two by two
+ * matrix, which has a closed form and so never needs an iterative solver. It
+ * is public because the same three numbers are what turns any covariance into
+ * something drawable — one measured elsewhere, or one already mapped into
+ * pixels.
+ * @param covariance - How the cloud is spread.
+ * @param standardDeviations - How far out to measure. Defaults to `1`.
+ * @returns The two semi-axis lengths and the rotation of the major one, in radians, in `(-π/2, π/2]`. A collinear cloud gives `ry` of exactly `0`, and one with no spread at all gives an angle of `0` because it has no direction to report.
+ */
+export function ellipseAxes(
+  covariance: EllipseCovariance,
+  standardDeviations = 1,
+): EllipseAxes {
+  const { xx, xy, yy } = covariance;
+  const middle = (xx + yy) / 2;
+  const half = (xx - yy) / 2;
+  const radius = Math.hypot(half, xy);
+  const major = middle + radius;
+  let minor = middle - radius;
+  if (!(minor > major * COLLINEAR_FLOOR)) minor = 0;
+  return {
+    rx: standardDeviations * Math.sqrt(major),
+    ry: standardDeviations * Math.sqrt(minor),
+    angle: majorAxisAngle(xx, xy, yy, major),
+  };
+}
+
+function majorAxisAngle(
+  xx: number,
+  xy: number,
+  yy: number,
+  major: number,
+): number {
+  // With no cross term the axes already are the eigenvectors, and asking
+  // `atan2` would only turn the exact answer into a rounded one.
+  if (xy === 0) return xx >= yy ? 0 : Math.PI / 2;
+  // `major - xx` is never negative, so this lands in [0, π] and a negative
+  // cross term arrives half a turn away from the direction actually wanted.
+  const angle = Math.atan2(major - xx, xy);
+  return angle > Math.PI / 2 ? angle - Math.PI : angle;
+}

package/src/scatter/core/ellipseProjection.ts

@@ -10,7 +10,7 @@
 import type { ChartScale } from '../../chart/core/chartScale.ts';
 
 import type { ConfidenceEllipse, EllipsePoint } from './confidenceEllipse.ts';
-import { ellipseAxes } from './confidenceEllipse.ts';
+import { ellipseAxes } from './ellipseAxes.ts';
 
 const HALF_TURN_DEGREES = 180;
 const DEFAULT_STEPS = 64;