react-cheminfo 0.76.0 → 0.78.0

package/src/locales/it.json

@@ -114,6 +114,14 @@
   "site.atoms.tagline": "Elettroni, neutroni, strutture di Lewis e numeri di ossidazione.",
   "site.moles.tagline": "Bilanciare una reazione e calcolarne la composizione in massa.",
   "site.inorganic.tagline": "Nominare un composto inorganico e scriverne la formula.",
+  "site.iupac-name.tagline": "Il nome IUPAC di una struttura, e la struttura che un nome designa.",
+  "site.slides.tagline": "Mettere uno strumento interattivo su una diapositiva, con il link del suo pulsante Condividi.",
+  "site.vibrations.tagline": "Spettri IR e Raman calcolati nel browser.",
+  "site.draw.tagline": "Strutture di qualità da pubblicazione, in un SVG che conserva la chimica.",
+  "site.molecules.tagline": "Cercare una molecola, le sue proprietà calcolate e le sue fonti.",
+  "site.chembio.tagline": "Prodotti naturali, e gli organismi in cui sono stati trovati.",
+  "site.wikidata.tagline": "La chimica delle infobox di Wikipedia, ricercabile per struttura.",
+  "site.mz.tagline": "Spettri di massa, classificati in base a come sono stati misurati.",
   "share.button": "Condividi",
   "share.buttonTitle": "Condividere un link a questa pagina, o incorporarla nel proprio sito",
   "share.dialogTitleFor": "Condividere o incorporare — {title}",
@@ -282,10 +290,14 @@
   "download.resolution": "Risoluzione",
   "download.resolutionHelp": "Quante volte la figura sullo schermo misura il file. Un PNG riceve altrettanti pixel in più: due va bene per una diapositiva, tre o quattro per la stampa. Un SVG resta nitido a qualsiasi dimensione, e si apre altrettante volte più grande.",
   "download.resolutionExample": "Una figura larga 640 pixel sullo schermo viene salvata larga 1280 pixel.",
+  "download.resolutionDpiHelp": "Punti per pollice, con la figura stampata alla sua dimensione sulla pagina. 150 basta per una diapositiva, 300 per le fotografie di una rivista, da 600 a 1200 per i disegni al tratto. Il PNG lo indica, così un documento lo colloca a quella dimensione.",
+  "download.resolutionDpiExample": "Una figura larga 8,5 cm viene salvata larga 1004 pixel.",
   "download.noFigure": "Non c'è ancora nessuna figura nella pagina da salvare.",
   "download.hintRasterSvg": "Un SVG che contiene un'immagine di {pixels}: una scena 3D non ha forma vettoriale.",
   "download.hintSvg": "Si apre a {pixels}, e resta nitido a qualsiasi dimensione.",
   "download.hintPng": "Salvato {pixels}.",
+  "download.hintSvgDpi": "Si stampa a {width} × {height} cm, e resta nitido a qualsiasi dimensione.",
+  "download.hintPngDpi": "Salvato {pixels}, che si stampano a {width} × {height} cm.",
   "download.hintCopied": "Copiato negli appunti: PNG di {pixels}.",
   "download.copyUnsupported": "Questo browser non può mettere un'immagine negli appunti. Salvala invece.",
   "download.size": "Dimensione",
@@ -794,5 +806,22 @@
   "ir.raman.doc.sampled": "Una banda è data nel punto campionato in cui raggiunge il massimo: la sua posizione non è più precisa della griglia su cui lo spettro è stato registrato.",
   "ir.raman.aboutLead": "Disegna uno spettro Raman, ne trova le bande e le elenca accanto al grafico.",
   "ir.raman.credit.picking": "**ir-spectrum** (cheminfo, MIT) trova le bande, con il rilevatore di picchi di **common-spectrum** e **ml-gsd**.",
-  "ir.raman.credit.jcamp": "**convert-to-jcamp** (cheminfo, MIT) scrive il file JCAMP-DX scaricato."
+  "ir.raman.credit.jcamp": "**convert-to-jcamp** (cheminfo, MIT) scrive il file JCAMP-DX scaricato.",
+  "panel.focus": "Concentrati sul pannello {panel}",
+  "panel.focusTooltip": "Concentrati su questo pannello: comprimi tutti gli altri",
+  "panel.unfocusTooltip": "Espandi di nuovo gli altri pannelli",
+  "panel.fillScreen": "Mostra il pannello {panel} a schermo intero",
+  "panel.fillScreenTooltip": "Mostra questo pannello a schermo intero",
+  "panel.fold": "Comprimi il pannello {panel}",
+  "panel.unfold": "Espandi il pannello {panel}",
+  "panel.foldTooltip": "Comprimi questo pannello",
+  "panel.unfoldTooltip": "Espandilo",
+  "panel.close": "Chiudi il pannello {panel}",
+  "panel.closeTooltip": "Chiudi questo pannello",
+  "panel.leaveFullScreen": "Esci dallo schermo intero",
+  "panel.leaveFullScreenTooltip": "Esci dallo schermo intero (Esc)",
+  "panel.clearFilter": "Cancella il filtro",
+  "panel.colourOf": "Colore di {name}",
+  "panel.drawIn": "Disegna {name} in {color}",
+  "panel.changeColour": "Disegna questo spettro in un altro colore"
 }

package/src/molecule3d/ui/Molecule3DStage.tsx

@@ -1,92 +1,8 @@
 /**
  * The box the molecule canvas and its toolbars are drawn in, which is also the
- * box that fills the screen.
- *
- * A box filling the screen hides everything outside it, and the popovers and
- * tooltips of the toolbars are portalled to `document.body`: while the box
- * fills the screen they are portalled into it instead, the way react-science's
- * `RootLayout` keeps its own menus visible. Otherwise the portal options of the
- * page around the viewer are passed through untouched.
+ * box that fills the screen. It is the shared fullscreen stage, so the
+ * toolbars' popovers stay visible while it does.
  */
 
-import { PortalContext, PortalProvider } from '@blueprintjs/core';
-import type { CSSProperties, ReactElement, ReactNode } from 'react';
-import { useCallback, useContext, useState } from 'react';
-import { FullScreenProvider, useFullscreen } from 'react-science/ui';
-
-import type { Molecule3DFullscreen } from './Molecule3DToolbar.tsx';
-
-/** Props of {@link Molecule3DStage}. */
-export interface Molecule3DStageProps {
-  /**
-   * Style of the box, or a function handed whether the box fills the screen,
-   * for a box shaped differently while it does.
-   */
-  style: CSSProperties | ((fillsScreen: boolean) => CSSProperties);
-  /**
-   * Called with the box once it is mounted, and with `null` once it is gone.
-   * @default undefined
-   */
-  onStage?: (element: HTMLDivElement | null) => void;
-  /**
-   * What is drawn in the box, handed whether it fills the screen and the
-   * toggle, or `undefined` where the browser cannot fill the screen.
-   */
-  children: (fullscreen: Molecule3DFullscreen | undefined) => ReactNode;
-}
-
-/**
- * The box of the canvas, able to fill the screen.
- * @param props - See {@link Molecule3DStageProps}.
- * @returns The box.
- */
-export function Molecule3DStage(props: Molecule3DStageProps): ReactElement {
-  return (
-    <FullScreenProvider>
-      {(fullscreenRef) => <Stage {...props} fullscreenRef={fullscreenRef} />}
-    </FullScreenProvider>
-  );
-}
-
-interface StageProps extends Molecule3DStageProps {
-  /** Where `FullScreenProvider` expects the element that fills the screen. */
-  fullscreenRef: { current: HTMLDivElement | null };
-}
-
-function Stage(props: StageProps): ReactElement {
-  const { style, onStage, children, fullscreenRef } = props;
-  const { isFullScreen, toggle } = useFullscreen();
-  const portal = useContext(PortalContext);
-  const [canFillScreen] = useState(isFullscreenEnabled);
-  const [stage, setStage] = useState<HTMLDivElement | null>(null);
-  const stageRef = useCallback(
-    (element: HTMLDivElement | null) => {
-      fullscreenRef.current = element;
-      setStage(element);
-      onStage?.(element);
-    },
-    [fullscreenRef, onStage],
-  );
-
-  // The provider is always there, so entering full screen changes a value
-  // rather than the tree, and the canvas inside is never mounted again.
-  return (
-    <div
-      ref={stageRef}
-      style={typeof style === 'function' ? style(isFullScreen) : style}
-    >
-      <PortalProvider
-        portalClassName={portal.portalClassName}
-        portalContainer={
-          isFullScreen && stage !== null ? stage : portal.portalContainer
-        }
-      >
-        {children(canFillScreen ? { active: isFullScreen, toggle } : undefined)}
-      </PortalProvider>
-    </div>
-  );
-}
-
-function isFullscreenEnabled(): boolean {
-  return typeof document !== 'undefined' && document.fullscreenEnabled;
-}
+export type { FullscreenStageProps as Molecule3DStageProps } from '../../shared/ui/FullscreenStage.tsx';
+export { FullscreenStage as Molecule3DStage } from '../../shared/ui/FullscreenStage.tsx';

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -64,6 +64,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     fileName = 'molecule',
     background,
     minHeight = 320,
+    onCapture,
     onFailureChange,
   } = props;
   const tools = resolveMolecule3DTools(toolsProp);
@@ -139,13 +140,21 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     camera: props,
   });
 
-  const { canvasSize, exportImage, copyImage } = useImageExport(
+  const { canvasSize, exportImage, copyImage, capture } = useImageExport(
     container,
     viewerRef,
     fileName,
     framesPerSecond,
   );
 
+  useEffect(() => {
+    if (onCapture === undefined || container === null) return;
+    onCapture(capture);
+    return () => {
+      onCapture(null);
+    };
+  }, [onCapture, container, capture]);
+
   return (
     <Molecule3DStage style={{ ...STAGE_STYLE, minHeight }}>
       {(fullscreen) => (

package/src/molecule3d/ui/exportMoleculeImage.ts

@@ -59,6 +59,28 @@ export async function captureMoleculePng(
   return new Blob([dataUriBytes(dataUri)], { type: FIGURE_PNG_TYPE });
 }
 
+/**
+ * Render the scene as an SVG holding the rendered image, as the export writes
+ * it.
+ * @param viewer - The viewer holding the scene.
+ * @param scale - Multiple of the canvas on screen it is rendered at.
+ * @param size - Size of the canvas on screen, CSS pixels.
+ * @returns The SVG markup.
+ * @throws {Error} When the viewer has nothing to render.
+ */
+export async function captureMoleculeSvg(
+  viewer: SceneCapture,
+  scale: number,
+  size: ImageSize,
+): Promise<string> {
+  const pixels = figurePixels(size, scale);
+  const dataUri = await viewer.captureImage(pixels);
+  if (dataUri === undefined) {
+    throw new Error('There is no picture to copy yet.');
+  }
+  return rasterSvgMarkup(dataUri, pixels);
+}
+
 /**
  * Render the scene and hand it to the browser as a file.
  * @param viewer - The viewer holding the scene.

package/src/molecule3d/ui/index.ts

@@ -25,4 +25,7 @@ export { exportMoleculeImage } from './exportMoleculeImage.ts';
 export type { ImageExport } from './useImageExport.ts';
 export { useImageExport } from './useImageExport.ts';
 export { MoleculeViewer3D } from './MoleculeViewer3D.tsx';
-export type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+export type {
+  Molecule3DCapture,
+  MoleculeViewer3DProps,
+} from './moleculeViewer3DProps.ts';

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -7,6 +7,23 @@ import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type { Molecule3DSettings, Molecule3DTools } from '../core/settings.ts';
 
+/** The scene on screen, rendered as a picture on request. */
+export interface Molecule3DCapture {
+  /**
+   * Render the scene as an SVG document holding the rendered image: a molecule
+   * drawn by WebGL has no vector form.
+   * @param scale - Multiple of the canvas on screen it is rendered at.
+   * @returns The SVG markup.
+   */
+  svg: (scale: number) => Promise<string>;
+  /**
+   * Render the scene as a PNG.
+   * @param scale - Multiple of the canvas on screen it is rendered at.
+   * @returns The PNG.
+   */
+  png: (scale: number) => Promise<Blob>;
+}
+
 /**
  * Props of `MoleculeViewer3D`.
  *
@@ -129,6 +146,13 @@ export interface MoleculeViewer3DProps {
    * @default 'molecule'
    */
   fileName?: string;
+  /**
+   * Handed the means to render the scene on screen once the viewer exists, and
+   * `null` when it goes — for a page that hands the picture on, to a host
+   * framing it. Keep it stable: a new function is handed the means again.
+   * @default undefined
+   */
+  onCapture?: (capture: Molecule3DCapture | null) => void;
   /**
    * Scene background, as `#rrggbb`.
    * @default '#ffffff'

package/src/molecule3d/ui/useImageExport.ts

@@ -1,5 +1,5 @@
 import type { RefObject } from 'react';
-import { useCallback } from 'react';
+import { useCallback, useMemo } from 'react';
 
 import type { FigureNotice } from '../../download/core/copyFigure.ts';
 import { copyFigure } from '../../download/core/copyFigure.ts';
@@ -10,8 +10,10 @@ import { DEFAULT_FRAMES_PER_SECOND } from '../core/animatedPng.ts';
 import type { SceneCapture } from './exportMoleculeImage.ts';
 import {
   captureMoleculePng,
+  captureMoleculeSvg,
   exportMoleculeImage,
 } from './exportMoleculeImage.ts';
+import type { Molecule3DCapture } from './moleculeViewer3DProps.ts';
 
 /** What {@link useImageExport} hands the export panel. */
 export interface ImageExport {
@@ -31,6 +33,8 @@ export interface ImageExport {
    * from the click itself: Safari only allows a write the click started.
    */
   copyImage: (scale: number) => Promise<FigureNotice>;
+  /** The scene rendered on request, for a page handing the picture on. */
+  capture: Molecule3DCapture;
 }
 
 /**
@@ -85,5 +89,27 @@ export function useImageExport(
     [canvasSize, viewerRef],
   );
 
-  return { canvasSize, exportImage, copyImage };
+  const capture = useMemo(
+    (): Molecule3DCapture => ({
+      svg: async (scale) => {
+        const viewer = viewerRef.current;
+        const size = canvasSize();
+        if (viewer === null || size === null) {
+          throw new Error('There is no picture to copy yet.');
+        }
+        return captureMoleculeSvg(viewer, scale, size);
+      },
+      png: async (scale) => {
+        const viewer = viewerRef.current;
+        const size = canvasSize();
+        if (viewer === null || size === null) {
+          throw new Error('There is no picture to copy yet.');
+        }
+        return captureMoleculePng(viewer, scale, size);
+      },
+    }),
+    [canvasSize, viewerRef],
+  );
+
+  return { canvasSize, exportImage, copyImage, capture };
 }

package/src/osiris/core/barGeometry.ts

@@ -0,0 +1,74 @@
+/**
+ * Where a property's bar starts, how far it runs, and where its labelled mark
+ * goes.
+ *
+ * Three numbers come out of the domain and are merely arranged here. The
+ * **position** is how far along the scale the value sits and gives the bar its
+ * length; the **fitness** is DataWarrior's own `getValuation`, a continuous
+ * 0-to-1 score that the stylesheet reads as the green-to-red ramp; the
+ * **threshold** is the published rule of thumb — cLogP ≤ 5, logS > −4,
+ * molweight < 450, drug-likeness > 0 — drawn as a mark on the track.
+ *
+ * Nothing here invents a cut-off. A bar whose colour disagreed with the panel's
+ * own scale record would be a second opinion nobody could trace.
+ */
+
+import { propertyFitness, propertyPosition } from './fitness.ts';
+import type { PropertyKey } from './propertyKeys.ts';
+import { propertyScale } from './scales.ts';
+
+/** Where a bar's fill and its mark go, all as fractions of the track. */
+export interface BarGeometry {
+  /** Where the fill starts, 0 at the left end of the track and 1 at the right. */
+  start: number;
+  /** How much of the track the fill covers, 0 to 1. */
+  length: number;
+  /** How good the value is: 0 as bad as the ramp goes, 1 inside the preferred band. */
+  fitness: number;
+  /**
+   * Where the fill grows from: the left end of the track, or its middle for a
+   * quantity that runs either side of zero. Drawn as a tick, because a fill
+   * that starts at a quarter of the way along says nothing without it.
+   */
+  origin: number;
+  /** Where the published threshold is marked, or `null` where the property has none. */
+  mark: number | null;
+  /** How that threshold reads, e.g. `≤ 5`, or `null`. */
+  markLabel: string | null;
+}
+
+/**
+ * Where a diverging bar grows from: the middle of its own range, which is
+ * drug-likeness 0 and drug score 0.
+ */
+const DIVERGING_ORIGIN = 0.5;
+
+/**
+ * Lay out one property's bar.
+ * @param key - Which of the ten properties.
+ * @param value - The predicted number, or `null` when the predictor could not answer.
+ * @returns The geometry, or `null` when there is no bar to draw.
+ */
+export function barGeometry(
+  key: PropertyKey,
+  value: number | null,
+): BarGeometry | null {
+  const position = propertyPosition(key, value);
+  if (position === null) return null;
+
+  const scale = propertyScale(key);
+  const origin = scale.diverging ? DIVERGING_ORIGIN : 0;
+  const mark =
+    scale.threshold === null
+      ? null
+      : propertyPosition(key, scale.threshold.value);
+
+  return {
+    start: Math.min(origin, position),
+    length: Math.abs(position - origin),
+    fitness: propertyFitness(key, value) ?? 0,
+    origin,
+    mark,
+    markLabel: scale.threshold?.label ?? null,
+  };
+}

package/src/osiris/core/computeProperties.ts

@@ -0,0 +1,175 @@
+/**
+ * Everything the tool predicts about one molecule, in one pass.
+ *
+ * The order of the reads is not arbitrary. `MoleculeProperties`' constructor
+ * normalises ambiguous bonds on the molecule it is handed, so the work is done
+ * on a copy and the caller's molecule — the one the editor is still drawing —
+ * is never touched. Its fields are prototype getters that rerun the whole
+ * predictor on every read, at 13 µs each, and the object cannot be spread or
+ * serialised at all, so each field is read exactly once into a plain object,
+ * and that plain object is what crosses the worker boundary.
+ *
+ * Nothing here trusts OpenChemLib to fail loudly. An empty molecule answers a
+ * full set of innocent numbers and a drug score of 0.63; a failed predictor
+ * answers -999, -1 or 0, never `NaN`; and `DrugScoreCalculator` consumes every
+ * one of those and returns something plausible. So the empty molecule is
+ * refused first, every sentinel becomes `null`, and a drug score is computed
+ * only when all of its inputs are real.
+ */
+
+import type * as OCL from 'openchemlib';
+
+import {
+  NO_FRAGMENT_MATCHED,
+  RISK_TYPE_CODES,
+  UNKNOWN_NUMBER,
+  UNKNOWN_SURFACE_AREA,
+  riskCodeOf,
+  riskLevelOf,
+} from './constants.ts';
+import type { OsirisPredictors } from './predictors.ts';
+import type { OsirisProperties, RiskLevel, RiskType } from './types.ts';
+import { RISK_TYPES } from './types.ts';
+
+/** What a caller knows about the molecule that the molecule does not. */
+export interface ComputePropertiesOptions {
+  /**
+   * The name the source carried. The canonical SMILES is used when there is
+   * none, so a row always has something to be called.
+   * @default the canonical SMILES
+   */
+  label?: string;
+}
+
+/** A structure with no atoms, which has nothing to predict. */
+export const EMPTY_MOLECULE_MESSAGE =
+  'This structure has no atoms, so there is nothing to predict.';
+
+/**
+ * Predict everything the tool shows for one molecule.
+ * @param molecule - The molecule. It is copied before anything touches it, so the caller keeps it exactly as it was.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param options - See {@link ComputePropertiesOptions}.
+ * @returns The ten numbers, the four risks, and what to call the molecule.
+ * @throws {Error} When the molecule has no atoms.
+ */
+export function computeProperties(
+  molecule: OCL.Molecule,
+  predictors: OsirisPredictors,
+  options: ComputePropertiesOptions = {},
+): OsirisProperties {
+  if (molecule.getAllAtoms() === 0) throw new Error(EMPTY_MOLECULE_MESSAGE);
+
+  const working = molecule.getCompactCopy();
+  const idCode = working.getIDCode();
+  const smiles = working.toIsomericSmiles();
+  const { formula, relativeWeight } = working.getMolecularFormula();
+
+  const properties = new predictors.MoleculeProperties(working);
+  const logP = real(properties.logP, UNKNOWN_NUMBER);
+  const logS = real(properties.logS, UNKNOWN_NUMBER);
+  const polarSurfaceArea = real(
+    properties.polarSurfaceArea,
+    UNKNOWN_SURFACE_AREA,
+  );
+  const acceptorCount = properties.acceptorCount;
+  const donorCount = properties.donorCount;
+  const stereoCenterCount = properties.stereoCenterCount;
+  const rotatableBondCount = properties.rotatableBondCount;
+
+  const assessed = predictors.druglikeness.assessDruglikeness(working);
+  const druglikeness =
+    assessed === UNKNOWN_NUMBER || assessed === NO_FRAGMENT_MATCHED
+      ? null
+      : assessed;
+
+  const risks = assessRisks(working, predictors);
+
+  return {
+    idCode,
+    smiles,
+    label: options.label ?? smiles,
+    molecularFormula: formula,
+    molecularWeight: relativeWeight,
+    logP,
+    logS,
+    polarSurfaceArea,
+    druglikeness,
+    drugScore: drugScore(predictors, {
+      logP,
+      logS,
+      relativeWeight,
+      druglikeness,
+      risks,
+    }),
+    acceptorCount,
+    donorCount,
+    stereoCenterCount,
+    rotatableBondCount,
+    risks,
+  };
+}
+
+function assessRisks(
+  molecule: OCL.Molecule,
+  predictors: OsirisPredictors,
+): Record<RiskType, RiskLevel> {
+  const risks = {} as Record<RiskType, RiskLevel>;
+  for (const risk of RISK_TYPES) {
+    risks[risk] = riskLevelOf(
+      predictors.toxicity.assessRisk(molecule, RISK_TYPE_CODES[risk]),
+    );
+  }
+  return risks;
+}
+
+interface DrugScoreInputs {
+  logP: number | null;
+  logS: number | null;
+  relativeWeight: number;
+  druglikeness: number | null;
+  risks: Record<RiskType, RiskLevel>;
+}
+
+/**
+ * The drug score, or `null` when any of its five inputs was unknown.
+ *
+ * `calculate` never refuses: a drug-likeness of -999 simply makes that factor
+ * exactly 0.5 and the score comes back looking ordinary, and an unassessed risk
+ * applies no penalty where a high one would have applied 0.6. Both read as good
+ * news, which is why they are refused here instead.
+ *
+ * The second argument is the **solubility**. The legacy explorer passed the
+ * polar surface area, which is a different number in a different unit; see the
+ * test that pins both.
+ * @param predictors - OpenChemLib with its resources registered and checked.
+ * @param inputs - The four predicted numbers and the four risks.
+ * @returns The score, or `null` when it cannot be trusted.
+ */
+function drugScore(
+  predictors: OsirisPredictors,
+  inputs: DrugScoreInputs,
+): number | null {
+  const { logP, logS, relativeWeight, druglikeness, risks } = inputs;
+  if (logP === null || logS === null || druglikeness === null) return null;
+
+  const codes: number[] = [];
+  for (const risk of RISK_TYPES) {
+    const level = risks[risk];
+    if (level === 'unknown') return null;
+    codes.push(riskCodeOf(level));
+  }
+
+  return predictors.DrugScoreCalculator.calculate(
+    logP,
+    logS,
+    relativeWeight,
+    druglikeness,
+    codes,
+  );
+}
+
+function real(value: number, sentinel: number): number | null {
+  if (value === sentinel || !Number.isFinite(value)) return null;
+  return value;
+}

package/src/osiris/core/constants.ts

@@ -0,0 +1,110 @@
+/**
+ * The numbers OpenChemLib speaks, and the words this site says instead.
+ *
+ * Two translations live here and nowhere else. The first is the library's risk
+ * numbering, which is easy to get backwards: `ToxicityPredictor.RISK_NAMES` is
+ * indexed by risk *type*, not by risk *level*, and the library exports no level
+ * names at all — so reading a level out of `RISK_NAMES` gives a confident,
+ * wrong answer. The second is the set of sentinels every predictor returns
+ * instead of failing: none of them is `NaN`, and `DrugScoreCalculator` consumes
+ * every one of them and hands back a plausible number.
+ */
+
+import type { RiskLevel, RiskType } from './types.ts';
+
+/**
+ * Where each risk sits in the library's numbering — `TYPE_MUTAGENIC` 0 through
+ * `TYPE_REPRODUCTIVE_EFFECTIVE` 3. It is also the order `DrugScoreCalculator`
+ * expects its `toxRisks` array in.
+ */
+export const RISK_TYPE_CODES: Record<RiskType, number> = {
+  mutagenic: 0,
+  tumorigenic: 1,
+  irritant: 2,
+  reproductive: 3,
+};
+
+/**
+ * What `assessRisk` returns, read as a word: `RISK_UNKNOWN` 0, `RISK_NO` 1,
+ * `RISK_LOW` 2, `RISK_HIGH` 3.
+ */
+export const RISK_LEVELS: readonly RiskLevel[] = [
+  'unknown',
+  'none',
+  'low',
+  'high',
+];
+
+/**
+ * What the library calls each risk, matching `ToxicityPredictor.RISK_NAMES`.
+ * Written out here so reading a label costs no import of a megabyte of
+ * OpenChemLib on a page that only draws a table.
+ */
+export const RISK_LABELS: Record<RiskType, string> = {
+  mutagenic: 'Mutagenicity',
+  tumorigenic: 'Tumorigenicity',
+  irritant: 'Irritating effects',
+  reproductive: 'Reproductive effects',
+};
+
+/**
+ * How each level reads on screen. OSIRIS's own three words, plus one for the
+ * state where the tables did not load — which is not "no risk" and must never
+ * be shown as one.
+ */
+export const RISK_LEVEL_LABELS: Record<RiskLevel, string> = {
+  unknown: 'Not assessed',
+  none: 'No risk',
+  low: 'Medium risk',
+  high: 'High risk',
+};
+
+/**
+ * What each level multiplies the drug score by, decoded from
+ * `DrugScoreCalculator.calculate`. `unknown` applies no factor at all, which is
+ * why a score is refused rather than shown when a risk came back unassessed.
+ */
+export const DRUG_SCORE_RISK_FACTORS: Record<RiskLevel, number> = {
+  unknown: 1,
+  none: 1,
+  low: 0.8,
+  high: 0.6,
+};
+
+/**
+ * What cLogP, solubility and drug-likeness answer when the predictor failed
+ * outright. `CLogPPredictor` returns it on an internal exception, and both
+ * `SolubilityPredictor.cSolubilityUnknown` and
+ * `DruglikenessPredictor.DRUGLIKENESS_UNKNOWN` are this value.
+ */
+export const UNKNOWN_NUMBER = -999;
+
+/** What the polar surface area answers when it is unknown — not `-999`. */
+export const UNKNOWN_SURFACE_AREA = -1;
+
+/**
+ * What `assessDruglikeness` answers when the molecule matched none of the 5294
+ * fragments. It is a real return value, not a failure, and it is
+ * indistinguishable from a drug-likeness that happens to be exactly -1.
+ */
+export const NO_FRAGMENT_MATCHED = -1;
+
+/**
+ * The word for a risk the library answered with a number.
+ * @param code - What `assessRisk` returned, 0 to 3.
+ * @returns The level, `unknown` for anything outside the four the library defines.
+ */
+export function riskLevelOf(code: number): RiskLevel {
+  return RISK_LEVELS[code] ?? 'unknown';
+}
+
+/**
+ * The number the library uses for a level, for the `toxRisks` argument of
+ * `DrugScoreCalculator.calculate`.
+ * @param level - The level.
+ * @returns 0 to 3.
+ */
+export function riskCodeOf(level: RiskLevel): number {
+  const code = RISK_LEVELS.indexOf(level);
+  return code === -1 ? 0 : code;
+}