react-cheminfo 0.13.0 → 0.15.0

package/src/build/vite/buildInfo.ts

@@ -0,0 +1,178 @@
+/**
+ * Tell a site which build of itself it is running.
+ *
+ * Every site of the family carries an About page, and the one thing that page
+ * cannot state from a hand-written record is the release it is serving. So the
+ * build states it: the plugin resolves the version, the day and the commit
+ * once, hands them to the page through a virtual module, and writes the same
+ * record to `build-info.json` so the whole family can be asked what it is
+ * running with one request each.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import type { BuildInfo } from '../core/buildInfo.ts';
+
+import { commitFromEnvironment, readGitHead } from './gitHead.ts';
+
+/** The module a site imports its build record from. */
+export const BUILD_INFO_MODULE = 'react-cheminfo/build-info';
+
+/** What the build writes about itself. */
+export interface BuildInfoOptions {
+  /**
+   * Where the record is written in the build, so a deployment can be asked
+   * what it is running. `false` writes none.
+   * @default 'build-info.json'
+   */
+  fileName?: string | false;
+}
+
+/**
+ * Resolve the build's own version, instant and commit, and publish them.
+ *
+ * The site reads them from the module the plugin fills in:
+ *
+ * ```ts
+ * import { BUILD_INFO } from 'react-cheminfo/build-info';
+ * ```
+ *
+ * That module exists on disk and exports `undefined`, so a Playwright spec or
+ * a unit test importing the same About record in plain Node still resolves it —
+ * a virtual specifier does not, and the whole suite dies on the import.
+ * @param options - See {@link BuildInfoOptions}.
+ * @returns The Vite plugin.
+ */
+export function cheminfoBuildInfo(options: BuildInfoOptions = {}): Plugin {
+  const { fileName = 'build-info.json' } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+  let info: BuildInfo = resolveBuildInfo(root);
+
+  return {
+    name: 'cheminfo-build-info',
+    // Vite's own resolver runs first and would hand back the module on disk,
+    // which exports `undefined`; and the dependency optimizer pre-bundles a
+    // bare specifier without asking a plugin at all.
+    enforce: 'pre',
+    config() {
+      return { optimizeDeps: { exclude: [BUILD_INFO_MODULE] } };
+    },
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+      info = resolveBuildInfo(root);
+    },
+    resolveId(id) {
+      return id === BUILD_INFO_MODULE ? RESOLVED_MODULE : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED_MODULE) return undefined;
+      return `export const BUILD_INFO = ${JSON.stringify(info)};\n`;
+    },
+    closeBundle() {
+      if (fileName === false) return;
+      const target = resolve(root, outDir, fileName);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, `${JSON.stringify(info, null, 2)}\n`);
+    },
+  };
+}
+
+/**
+ * What the build knows about itself, read off the checkout it runs in.
+ * @param root - The project Vite is building, which may sit under the
+ *   repository root as `frontend` does.
+ * @returns The record, with whatever it could not resolve left out.
+ */
+export function resolveBuildInfo(root: string): BuildInfo {
+  const repository = findRepositoryRoot(root);
+
+  return {
+    version: readVersion(repository) ?? readVersion(root) ?? UNRELEASED,
+    builtAt: buildInstant(),
+    commit: readGitHead(repository) ?? commitFromEnvironment(),
+    reactCheminfo: readOwnVersion(),
+  };
+}
+
+/**
+ * The topmost directory of the run of ancestors that all hold a `package.json`.
+ *
+ * It is the repository root, and it is where the released version lives:
+ * release-please bumps the root `package.json`, while the `frontend` workspace
+ * of a site that has one keeps the `0.0.0` it was scaffolded with.
+ * @param start - Where to start climbing.
+ * @returns The highest such directory, or `start` when it holds none itself.
+ */
+export function findRepositoryRoot(start: string): string {
+  let directory = resolve(start);
+  let highest = directory;
+
+  for (;;) {
+    if (readPackage(directory) !== undefined) highest = directory;
+    const parent = dirname(directory);
+    // The run has ended: a directory with no package.json is above the project,
+    // and so is everything above it.
+    if (parent === directory || readPackage(parent) === undefined) {
+      return highest;
+    }
+    directory = parent;
+  }
+}
+
+function readVersion(directory: string): string | undefined {
+  const version = readPackage(directory)?.version;
+  return typeof version === 'string' && version.length > 0
+    ? version
+    : undefined;
+}
+
+/**
+ * The version of this package, so a site can be asked which chrome it runs.
+ * @returns The version, or `undefined` when the manifest is out of reach.
+ */
+function readOwnVersion(): string | undefined {
+  let directory = import.meta.dirname;
+
+  for (;;) {
+    const manifest = readPackage(directory);
+    if (manifest?.name === OWN_NAME && typeof manifest.version === 'string') {
+      return manifest.version;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function readPackage(
+  directory: string,
+): { name?: unknown; version?: unknown } | undefined {
+  try {
+    return JSON.parse(
+      readFileSync(join(directory, 'package.json'), 'utf8'),
+    ) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * When the build ran, honouring `SOURCE_DATE_EPOCH` so a reproducible build
+ * stays reproducible.
+ * @returns The instant, to the second, as `2026-09-16T09:41:07Z`.
+ */
+function buildInstant(): string {
+  const epoch = Number(process.env.SOURCE_DATE_EPOCH);
+  const when = Number.isFinite(epoch) && epoch > 0 ? epoch * 1000 : Date.now();
+  return `${new Date(when).toISOString().slice(0, SECOND_LENGTH)}Z`;
+}
+
+const RESOLVED_MODULE = `\0${BUILD_INFO_MODULE}`;
+const OWN_NAME = 'react-cheminfo';
+const UNRELEASED = '0.0.0';
+const SECOND_LENGTH = 19;

package/src/build/vite/gitHead.ts

@@ -0,0 +1,114 @@
+/**
+ * Read the commit a build is made from, without running git.
+ *
+ * The image build cannot run git: `.dockerignore` keeps `.git` out of the
+ * context and `node:alpine` ships no git binary, while the shared
+ * `docker-image` workflow passes no build argument a commit could arrive in.
+ * What a site does instead is let three paths back into the context —
+ * `.git/HEAD`, `.git/refs` and `.git/packed-refs`, a few kilobytes — and those
+ * three are enough to resolve the hash by reading files.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+/**
+ * The commit `HEAD` names, read from the repository above a directory.
+ * @param start - Where to start looking; every ancestor is tried in turn.
+ * @returns The full hash, or `undefined` when the repository is out of reach —
+ *   which is what a build sees when the three paths were not let back in.
+ */
+export function readGitHead(start: string): string | undefined {
+  const gitDir = findGitDir(start);
+  if (gitDir === undefined) return undefined;
+
+  const head = readText(join(gitDir, 'HEAD'));
+  if (head === undefined) return undefined;
+
+  // A checkout made by `actions/checkout` is detached, so `HEAD` is the hash
+  // itself and neither `refs` nor `packed-refs` is read at all.
+  if (!head.startsWith('ref:')) return asCommit(head);
+
+  const ref = head.slice('ref:'.length).trim();
+  const loose = readText(join(gitDir, ref));
+  return (
+    asCommit(loose) ??
+    commitInPackedRefs(readText(join(gitDir, 'packed-refs')), ref)
+  );
+}
+
+/**
+ * The commit named by the environment, for a build that cannot see `.git`.
+ * @returns The hash, or `undefined` when no variable names one.
+ */
+export function commitFromEnvironment(): string | undefined {
+  return (
+    asCommit(process.env.GITHUB_SHA) ??
+    asCommit(process.env.SOURCE_COMMIT) ??
+    asCommit(process.env.GIT_COMMIT)
+  );
+}
+
+/**
+ * The `.git` directory governing a path.
+ * @param start - Where to start looking.
+ * @returns Its absolute path, or `undefined` when there is none above `start`.
+ */
+export function findGitDir(start: string): string | undefined {
+  let directory = resolve(start);
+
+  for (;;) {
+    const candidate = join(directory, '.git');
+    const text = readText(candidate);
+    // A worktree and a submodule write a file naming the real directory; a
+    // plain repository has the directory itself, which reads as `undefined`.
+    if (text?.startsWith('gitdir:')) {
+      const target = text.slice('gitdir:'.length).trim();
+      return isAbsolute(target) ? target : resolve(directory, target);
+    }
+    if (readText(join(candidate, 'HEAD')) !== undefined) return candidate;
+
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+/**
+ * The hash a packed `refs` file gives a ref.
+ * @param packed - The contents of `packed-refs`, when there is one.
+ * @param ref - The ref to look up, e.g. `refs/heads/main`.
+ * @returns The hash, or `undefined` when the file does not carry the ref.
+ */
+function commitInPackedRefs(
+  packed: string | undefined,
+  ref: string,
+): string | undefined {
+  if (packed === undefined) return undefined;
+
+  for (const line of packed.split('\n')) {
+    // `#` is the header and `^` the object a tag points at: neither is a ref.
+    if (line.startsWith('#') || line.startsWith('^')) continue;
+    const space = line.indexOf(' ');
+    if (space === -1 || line.slice(space + 1).trim() !== ref) continue;
+    return asCommit(line.slice(0, space));
+  }
+
+  return undefined;
+}
+
+function asCommit(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text !== undefined && COMMIT.test(text) ? text : undefined;
+}
+
+function readText(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8').trim();
+  } catch {
+    return undefined;
+  }
+}
+
+// Forty hexadecimal characters, or sixty-four in a repository on sha256.
+const COMMIT = /^[\da-f]{40}(?:[\da-f]{24})?$/;

package/src/build/vite/index.ts

@@ -0,0 +1,8 @@
+export type { BuildInfoOptions } from './buildInfo.ts';
+export {
+  BUILD_INFO_MODULE,
+  cheminfoBuildInfo,
+  findRepositoryRoot,
+  resolveBuildInfo,
+} from './buildInfo.ts';
+export { commitFromEnvironment, findGitDir, readGitHead } from './gitHead.ts';

package/src/build-info.ts

@@ -0,0 +1,2 @@
+export type { BuildInfo } from './build/core/buildInfo.ts';
+export { BUILD_INFO } from './build/core/current.ts';

package/src/core.ts

@@ -1,4 +1,5 @@
 export * from './about/core/index.ts';
+export * from './build/core/index.ts';
 export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';

package/src/credits/core/credits.ts

@@ -194,6 +194,27 @@ export const CREDITS = [
     description: 'the dragging that arranges things into an order.',
     license: 'MIT',
   },
+  {
+    id: 'react-roi',
+    name: 'react-roi',
+    href: 'https://github.com/zakodium-oss/react-roi',
+    description: 'the box a region of an image is drawn with.',
+    license: 'MIT',
+  },
+  {
+    id: 'file-collection',
+    name: 'file-collection',
+    href: 'https://github.com/cheminfo/file-collection',
+    description: 'the reader that takes dropped files, folders and archives.',
+    license: 'MIT',
+  },
+  {
+    id: 'zip-js',
+    name: 'zip.js',
+    href: 'https://github.com/gildas-lormeau/zip.js',
+    description: 'the ZIP archives that are read and written in the browser.',
+    license: 'BSD-3-Clause',
+  },
   {
     id: 'preact-signals',
     name: 'Preact Signals',

package/src/ecosystem/ui/Wordmark.tsx

@@ -3,12 +3,22 @@ import type { CSSProperties, ReactElement } from 'react';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { siteById } from '../core/lookup.ts';
 import { siteNameColors } from '../core/nameColors.ts';
-import type { SiteId } from '../core/sites.ts';
+import type { EcosystemSite, SiteId } from '../core/sites.ts';
 
 /** What a site's written name needs. */
 export interface WordmarkProps {
-  /** The site whose name is written. */
-  siteId: SiteId;
+  /**
+   * The site whose name is written, passed rather than named — for a site that
+   * is deliberately not one of `ECOSYSTEM_SITES`. One of `site` and `siteId` is
+   * required.
+   * @default undefined
+   */
+  site?: EcosystemSite;
+  /**
+   * The same site, named rather than passed, which is what a header knows.
+   * @default undefined
+   */
+  siteId?: SiteId;
   /**
    * Size of the name, in pixels. The weight comes from the surrounding
    * context, so the same wordmark suits a header bar and a heading.
@@ -32,12 +42,17 @@ export interface WordmarkProps {
  * its address.
  * @param props - The site, the size of the name, and extra class names.
  * @returns The name, as one inline element that never wraps mid-address.
+ * @throws {Error} When neither `site` nor `siteId` is given.
  */
 export function Wordmark(props: WordmarkProps): ReactElement {
-  const { siteId, size = 17, className } = props;
-  const site = siteById(siteId);
-  const { lead, alt, dot } = site.name;
-  const colors = siteNameColors(site);
+  const { site, siteId, size = 17, className } = props;
+  const written = site ?? (siteId === undefined ? undefined : siteById(siteId));
+  if (written === undefined) {
+    throw new Error('Wordmark needs one of its `site` and `siteId` props');
+  }
+
+  const { lead, alt, dot } = written.name;
+  const colors = siteNameColors(written);
 
   return (
     <span

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -44,6 +44,7 @@ export interface MoleculeCanvas3DProps extends Omit<
 export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
   const {
     molfile,
+    frameNewMolecule = 'keep',
     tools: toolsProp,
     settings: settingsProp,
     defaultSettings,
@@ -134,10 +135,11 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
       // Framed on a new molecule or a new viewer, never on a restyle: a slider
       // that snapped the camera back would undo the reader's orientation.
       const framed = framedRef.current;
-      const frameCamera =
+      const isNew =
         molfile !== null &&
         (framed?.molfile !== molfile || framed.viewer !== viewer);
       framedRef.current = molfile === null ? null : { molfile, viewer };
+      const frameCamera = isNew ? frameNewMolecule : 'none';
       void drawScene(viewer, molfile, settings, measurements, frameCamera)
         .then(() => {
           if (!cancelled) latest.current.onFailureChange(null);
@@ -153,7 +155,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
       cancelled = true;
       cancelAnimationFrame(frame);
     };
-  }, [container, molfile, settings, measurements]);
+  }, [container, molfile, frameNewMolecule, settings, measurements]);
 
   useEffect(() => {
     void viewerRef.current?.setSpin(spinning, spinSpeed);

package/src/molecule3d/ui/camera.ts

@@ -28,6 +28,10 @@ const SPIN_AXIS = Vec3.create(0, 1, 0);
 /** Smallest radius framed, in ångström, so a single atom is not a close-up. */
 const MIN_FRAMING_RADIUS = 0.5;
 
+/** Screen up and viewing direction when the model is seen as its file lays it. */
+const FRONT_UP = Vec3.create(0, 1, 0);
+const FRONT_DIRECTION = Vec3.create(0, 0, -1);
+
 /**
  * Frame everything currently in the scene.
  *
@@ -38,19 +42,25 @@ const MIN_FRAMING_RADIUS = 0.5;
  * after that commit.
  * @param plugin - The molstar context.
  * @param durationMilliseconds - Transition length. Pass 0 for an instant jump.
+ * @param fromFront - Look down -z with y up, instead of keeping the current
+ * direction.
  */
 export function resetCamera(
   plugin: PluginContext,
   durationMilliseconds = DEFAULT_CAMERA_DURATION,
+  fromFront = false,
 ): void {
   plugin.canvas3d?.requestCameraReset({
     durationMs: durationMilliseconds,
     snapshot: (scene, camera) => {
       const { center, radius } = scene.boundingSphereVisible;
-      return camera.getFocus(
-        center,
-        Math.max(radius * (1 + FRAMING_MARGIN), MIN_FRAMING_RADIUS),
+      const framed = Math.max(
+        radius * (1 + FRAMING_MARGIN),
+        MIN_FRAMING_RADIUS,
       );
+      return fromFront
+        ? camera.getFocus(center, framed, FRONT_UP, FRONT_DIRECTION)
+        : camera.getFocus(center, framed);
     },
   });
 }

package/src/molecule3d/ui/drawScene.ts

@@ -11,7 +11,9 @@ import type { Molecule3DViewer } from './viewer.ts';
  * @param molfile - What to draw, or `null` to empty the scene.
  * @param settings - How to draw it.
  * @param measurements - What to draw over it.
- * @param frameCamera - Whether to frame the camera once everything is there.
+ * @param frameCamera - How to frame the camera once everything is there:
+ * `keep` glides to it along the current direction, `front` jumps to it looking
+ * down -z, `none` leaves the camera alone.
  * @returns Nothing; resolves once the scene is complete.
  */
 export async function drawScene(
@@ -19,7 +21,7 @@ export async function drawScene(
   molfile: Molecule3DFile | null,
   settings: Molecule3DSettings,
   measurements: readonly Measurement[],
-  frameCamera: boolean,
+  frameCamera: 'none' | 'keep' | 'front',
 ): Promise<void> {
   if (molfile === null) {
     await viewer.hideMolecule();
@@ -39,5 +41,6 @@ export async function drawScene(
     });
   }
   await viewer.showMeasurements(measurements);
-  if (frameCamera) await viewer.resetCamera();
+  if (frameCamera === 'keep') await viewer.resetCamera();
+  if (frameCamera === 'front') await viewer.resetCamera(0, true);
 }

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -18,6 +18,14 @@ import type {
 export interface MoleculeViewer3DProps {
   /** The molecule to draw, with 3D coordinates, or `null` for none. */
   molfile: Molecule3DFile | null;
+  /**
+   * How the camera meets a new molecule. `keep` glides to it along the current
+   * direction, which suits conformers of one molecule; `front` jumps to it
+   * looking down -z with y up, so unrelated molecules, each laid out in its
+   * file the way it reads best, never swing in from the previous view.
+   * @default 'keep'
+   */
+  frameNewMolecule?: 'keep' | 'front';
   /**
    * Which buttons the toolbar over the canvas shows; tools not named stay on.
    * @default every tool

package/src/molecule3d/ui/viewer.ts

@@ -182,11 +182,15 @@ export class Molecule3DViewer {
   /**
    * Frame everything on screen.
    * @param durationMilliseconds - Transition length; 0 jumps.
+   * @param fromFront - Look down -z with y up instead of keeping the direction.
    * @returns Nothing; resolves once the move has been ordered.
    */
-  resetCamera(durationMilliseconds = DEFAULT_CAMERA_DURATION): Promise<void> {
+  resetCamera(
+    durationMilliseconds = DEFAULT_CAMERA_DURATION,
+    fromFront = false,
+  ): Promise<void> {
     return this.#run((plugin) => {
-      resetCamera(plugin, durationMilliseconds);
+      resetCamera(plugin, durationMilliseconds, fromFront);
     });
   }
 

package/src/vite.ts

@@ -1,2 +1,3 @@
+export * from './build/vite/index.ts';
 export * from './seo/vite/index.ts';
 export * from './slides/vite/index.ts';