react-cheminfo 0.64.1 → 0.65.0

package/src/worker/core/workerChannelParts.ts

@@ -1,8 +1,12 @@
 import { toError } from '../../error/core/toError.ts';
 
-import type { WorkerLike } from './messages.ts';
+import type {
+  WorkerEventLike,
+  WorkerLike,
+  WorkerResponseMessage,
+} from './messages.ts';
 import { isProgressMessage, isResponseMessage } from './messages.ts';
-import type { WorkerJobContext } from './workerChannelTypes.ts';
+import type { WorkerFailure, WorkerJobContext } from './workerChannelTypes.ts';
 
 /** How long a request waits when neither the call nor the channel says. */
 export const DEFAULT_TIMEOUT_MS = 120_000;
@@ -62,10 +66,13 @@ export type Outcome<TResponse> =
 interface WorkerMessageHandlers {
   /** News about a running job. */
   progress: (id: number, progress: unknown) => void;
-  /** The end of a job. */
-  answer: (id: number, outcome: Outcome<unknown>) => void;
-  /** The worker failed outright, with what it said, possibly nothing. */
-  failure: (detail: string) => void;
+  /** The end of a job, as the worker posted it. */
+  answer: (id: number, message: WorkerResponseMessage<unknown>) => void;
+  /**
+   * The worker failed outright, with what it said — possibly nothing — and
+   * the error event itself.
+   */
+  failure: (detail: string, event: WorkerEventLike) => void;
 }
 
 /**
@@ -121,19 +128,32 @@ export function subscribeToWorker(
     if (isProgressMessage(message)) {
       handlers.progress(message.id, message.progress);
     } else if (isResponseMessage(message)) {
-      handlers.answer(
-        message.id,
-        message.ok
-          ? { ok: true, response: message.response }
-          : { ok: false, error: new Error(message.message) },
-      );
+      handlers.answer(message.id, message);
     }
   });
   target.addEventListener('error', (event) => {
-    handlers.failure(event.message ?? '');
+    handlers.failure(event.message ?? '', event);
   });
 }
 
+/**
+ * The error a failure rejects its requests with when the channel is given no
+ * `failure` of its own: the job's own error or message, `<name> failed: …` for
+ * a worker that died, and what creating the worker threw.
+ * @param failure - What went wrong.
+ * @returns The error.
+ */
+export function defaultFailureError(failure: WorkerFailure): Error {
+  if (failure.kind === 'worker') {
+    const suffix = failure.message === '' ? '' : `: ${failure.message}`;
+    return new Error(`${failure.name} failed${suffix}`);
+  }
+  if (failure.cause instanceof Error) return failure.cause;
+  return failure.kind === 'job'
+    ? new Error(failure.message)
+    : toError(failure.cause);
+}
+
 /**
  * Run one job on this thread as a worker would: with a signal the channel
  * aborts, progress routed back, and every outcome — a throw included —

package/src/worker/core/workerChannelTypes.ts

@@ -63,14 +63,59 @@ export interface WorkerChannelOptions<TRequest, TResponse, TProgress = never> {
   cooperativeCancel?: boolean;
   /**
    * The same job run on this thread, used instead of the worker where the page
-   * has no `Worker` at all — Node.js, a unit test. Only a channel built from a
-   * function that creates the worker falls back to it.
+   * has no `Worker` at all — Node.js, a unit test — or where creating one
+   * throws, as a browser refuses a page framed under an opaque origin a worker
+   * from its own server; every later job then runs here too. Only a channel
+   * built from a function that creates the worker falls back to it.
    * @default undefined — every job goes to the worker
    */
   runInProcess?: (
     request: TRequest,
     context: WorkerJobContext<TProgress>,
   ) => Promise<TResponse>;
+  /**
+   * Turn what went wrong into the error the requests reject with, so a page
+   * can say it in its own words — a translated message, an error class of its
+   * own. Answering `undefined` keeps the default error. Cancellations and
+   * timeouts are not failures: they keep their own error classes.
+   * @default undefined — the job's message, or `<name> failed: …`
+   */
+  failure?: (failure: WorkerFailure) => Error | undefined;
+  /**
+   * Post a job again, once, on a fresh worker when its worker failed before
+   * answering, rather than reporting the failure: a worker whose module graph
+   * was still loading when the channel replaced it dies without having run
+   * anything. A job posted with buffers to transfer is not posted twice. Only
+   * a channel built from a function that creates the worker can do it.
+   * @default false
+   */
+  retryAfterWorkerFailure?: boolean;
+}
+
+/** What went wrong, before it becomes the error a request rejects with. */
+export interface WorkerFailure {
+  /**
+   * `job`: the job failed — its worker answered with a failure, or its
+   * in-process run threw. `worker`: the worker itself failed outright; an
+   * empty `message` means it never ran at all, its module graph not loading.
+   * `start`: creating the worker threw, and no in-process run stood in.
+   */
+  kind: 'job' | 'worker' | 'start';
+  /** The channel's name, e.g. `conformers`. */
+  name: string;
+  /** What was said: the job's message, the error event's, or the thrown error's. */
+  message: string;
+  /**
+   * The `detail` a failed answer carried, as `serveWorkerRequests` was told to
+   * write it — the key of a translatable message, say.
+   * @default undefined
+   */
+  detail?: unknown;
+  /**
+   * What the failure came with: the failed answer the worker posted, the error
+   * the in-process run threw, the error event, or what the factory threw.
+   */
+  cause: unknown;
 }
 
 /** What one call may ask of the channel. */

package/src/worker/core/workerSlot.ts

@@ -0,0 +1,181 @@
+import { errorMessage } from '../../error/core/toError.ts';
+
+import { CancelledRequestError } from './errors.ts';
+import type { WorkerLike, WorkerResponseMessage } from './messages.ts';
+import type { Outcome } from './workerChannelParts.ts';
+import {
+  defaultFailureError,
+  subscribeToWorker,
+} from './workerChannelParts.ts';
+import type {
+  WorkerFailure,
+  WorkerJobContext,
+  WorkerSource,
+} from './workerChannelTypes.ts';
+
+/**
+ * The one worker a channel posts to, kept, replaced and listened to.
+ *
+ * Handed a worker, the slot holds it until it is terminated. Handed a function,
+ * it creates the worker on first use and again after one failed or was let go,
+ * and runs the jobs on this thread instead — where there is no `Worker`, or
+ * where creating one throws — when the channel was given an in-process run.
+ * What a worker posts is heard only while it is the slot's current one, so a
+ * worker already let go cannot settle a job it no longer runs.
+ * @param source - The worker, or the function that creates it.
+ * @param options - What the slot reports to, and how failures are worded.
+ * @returns The slot.
+ */
+export function createWorkerSlot<TRequest, TResponse, TProgress>(
+  source: WorkerSource,
+  options: WorkerSlotOptions<TRequest, TResponse, TProgress>,
+): WorkerSlot<TRequest, TResponse, TProgress> {
+  const { name, runInProcess, failure, isWaited, report } = options;
+  const factory = typeof source === 'function' ? source : undefined;
+  let worker: WorkerLike | null = null;
+  let local =
+    factory !== undefined && !('Worker' in globalThis)
+      ? runInProcess
+      : undefined;
+  if (typeof source !== 'function') {
+    worker = source;
+    listen(source);
+  }
+
+  function fail(described: WorkerFailure): Error {
+    return failure?.(described) ?? defaultFailureError(described);
+  }
+
+  function acquire(): WorkerLike | null {
+    if (local !== undefined) return null;
+    if (worker !== null) return worker;
+    if (factory === undefined) {
+      throw new CancelledRequestError(`${name} was terminated`);
+    }
+    try {
+      worker = factory();
+    } catch (error) {
+      if (runInProcess === undefined) {
+        const message = errorMessage(error);
+        throw fail({ kind: 'start', name, message, cause: error });
+      }
+      local = runInProcess;
+      return null;
+    }
+    listen(worker);
+    return worker;
+  }
+
+  function outcomeOf(
+    id: number,
+    message: WorkerResponseMessage<unknown>,
+  ): Outcome<TResponse> {
+    if (message.ok) {
+      return { ok: true, response: message.response as TResponse };
+    }
+    if (!isWaited(id)) return { ok: false, error: new Error(message.message) };
+    const { detail } = message;
+    const described = { kind: 'job', name, message: message.message } as const;
+    return { ok: false, error: fail({ ...described, detail, cause: message }) };
+  }
+
+  function listen(target: WorkerLike): void {
+    subscribeToWorker(target, {
+      progress: (id, progress) => {
+        if (target === worker) report.progress(id, progress);
+      },
+      answer: (id, message) => {
+        if (target === worker) report.answer(id, outcomeOf(id, message));
+      },
+      failure: (detail, event) => {
+        if (target !== worker) return;
+        if (factory !== undefined) {
+          target.terminate();
+          worker = null;
+        }
+        report.failure(
+          fail({ kind: 'worker', name, message: detail, cause: event }),
+        );
+      },
+    });
+  }
+
+  return {
+    hasFactory: factory !== undefined,
+    get current() {
+      return worker;
+    },
+    acquire,
+    runLocally: (payload, context) =>
+      local === undefined
+        ? Promise.reject(new Error(`${name} has no in-process run`))
+        : local(payload, context),
+    jobFailed: (error) =>
+      fail({ kind: 'job', name, message: error.message, cause: error }),
+    abandon: () => {
+      if (factory === undefined || worker === null) return;
+      worker.terminate();
+      worker = null;
+    },
+    terminate: () => {
+      worker?.terminate();
+      if (factory !== undefined) worker = null;
+    },
+  };
+}
+
+/** What a slot is told about its channel. */
+export interface WorkerSlotOptions<TRequest, TResponse, TProgress> {
+  /** The channel's name, for its errors. */
+  name: string;
+  /**
+   * The job run on this thread instead of a worker.
+   * @default undefined — every job goes to the worker
+   */
+  runInProcess?: (
+    request: TRequest,
+    context: WorkerJobContext<TProgress>,
+  ) => Promise<TResponse>;
+  /**
+   * The channel's own wording of a failure.
+   * @default undefined — the default errors
+   */
+  failure?: (failure: WorkerFailure) => Error | undefined;
+  /** Whether somebody still waits for a request. */
+  isWaited: (id: number) => boolean;
+  /** Where what the current worker posts goes. */
+  report: {
+    /** News about a running job. */
+    progress: (id: number, progress: unknown) => void;
+    /** The end of a job. */
+    answer: (id: number, outcome: Outcome<TResponse>) => void;
+    /** The worker failed outright, and a factory's was let go. */
+    failure: (error: Error) => void;
+  };
+}
+
+/** The worker of a channel; see {@link createWorkerSlot}. */
+export interface WorkerSlot<TRequest, TResponse, TProgress> {
+  /** Whether the slot creates its workers, and can therefore replace one. */
+  readonly hasFactory: boolean;
+  /** The worker posted to now, if there is one. */
+  readonly current: WorkerLike | null;
+  /**
+   * The worker a job goes to, created if need be.
+   * @returns It, or `null` when the job runs on this thread instead.
+   * @throws {CancelledRequestError} When a worker handed over was terminated.
+   * @throws {Error} What creating the worker threw, worded by the channel.
+   */
+  acquire: () => WorkerLike | null;
+  /** Run a job on this thread, as the channel's in-process run. */
+  runLocally: (
+    payload: TRequest,
+    context: WorkerJobContext<TProgress>,
+  ) => Promise<TResponse>;
+  /** The error an in-process run that failed rejects with. */
+  jobFailed: (error: Error) => Error;
+  /** End a factory's worker, so the next job starts on a fresh one. */
+  abandon: () => void;
+  /** End the worker, whatever made it. */
+  terminate: () => void;
+}

package/styles/card.css

@@ -0,0 +1,145 @@
+/*
+ * The card an answer is shown as in a chat: a site's own page under
+ * `?embed=1&card=1`, which mcp.cheminfo.org frames inline. Imported once by
+ * the site's card, after `chrome.css`, whose tokens it reads; `CardFrame` and
+ * the components of `react-cheminfo/card` carry the classes.
+ */
+
+/* The frame is exactly as tall as the card reports, so nothing around the card
+   may add a pixel, and the page behind it takes the card's colour. */
+body:has(.card) {
+  margin: 0;
+  background: var(--surface);
+}
+
+.card {
+  box-sizing: border-box;
+  padding: 0.6rem 0.75rem;
+  background: var(--surface);
+  color: var(--text);
+  font-size: 0.875rem;
+}
+
+.card a:not(.bp6-button) {
+  color: var(--accent);
+}
+
+/* The chat floats its own full-screen control over the top right corner of
+   the frame, about 40px square: the first line of a card leaves it empty. */
+.card__header {
+  padding-right: 2.75rem;
+  margin: 0;
+}
+
+.card__title {
+  min-width: 0;
+  margin: 0;
+  font-size: 1.0625rem;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
+.card__muted {
+  color: var(--text-muted);
+}
+
+/* The last row of a card: a remark, then the actions — copying its table, the
+   way to the site's page — keeping its right edge together. */
+.card__end {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-end;
+  margin-top: 0.35rem;
+  gap: 0.25rem 0.5rem;
+}
+
+.card__note {
+  min-width: 0;
+  flex: 1;
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+}
+
+/* A dialog a card opens is as tall as what it holds: the card grows to hold
+   it, where Blueprint would cut its body to seven tenths of a frame that is
+   only as tall as the card. */
+body:has(.card) .bp6-dialog-body-scroll-container {
+  max-height: none;
+}
+
+/* The tooltip of a card's action names it in a few words: the family's help
+   card, at the width of its text rather than at the measure of a paragraph. */
+.help-tooltip.card-tooltip .bp6-popover-content {
+  width: auto;
+  max-width: 300px;
+}
+
+/* ── A figure, and the glyphs that take it away ─────────────────────────── */
+
+/* The glyphs stand in a column beside the figure's top right corner: over the
+   drawing they would hide part of a curve or an atom. */
+.card-figure {
+  position: relative;
+  width: fit-content;
+  min-width: 0;
+  max-width: 100%;
+  padding-right: 30px;
+}
+
+/* A grid of structures takes the width it is given. */
+.card-figure--fill {
+  width: auto;
+}
+
+/* Faded until the figure is pointed at, as the chat's own glyphs are, and at
+   full strength while one holds the focus or has its panel open. Inset by the
+   width of a focus ring, which the layer around them would otherwise cut. */
+.card-figure__tools {
+  position: absolute;
+  top: 3px;
+  right: 3px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  opacity: 0.6;
+  pointer-events: auto;
+  transition: opacity 120ms ease;
+}
+
+.card-figure:hover .card-figure__tools,
+.card-figure__tools:focus-within,
+.card-figure__tools:has([aria-expanded='true']) {
+  opacity: 1;
+}
+
+/* A finger has nothing to point with before it taps, and gets the larger
+   glyphs: the column widens with them. */
+@media (hover: none) {
+  .card-figure__tools {
+    opacity: 1;
+  }
+}
+
+@media (pointer: coarse) {
+  .card-figure {
+    padding-right: 46px;
+  }
+}
+
+/* ── Copying a table ────────────────────────────────────────────────────── */
+
+/* A heading of a few letters has room for the glyph alone; the label stays the
+   button's accessible name. */
+.card__copy-table--glyph .bp6-button-text {
+  display: none;
+}
+
+/* On a narrow frame the last row has no room for two labelled buttons: the
+   table's copy keeps its glyph, and its tooltip says what it does. */
+@media (width <= 30rem) {
+  .card__copy-table .bp6-button-text {
+    display: none;
+  }
+}

package/styles/chrome.css

@@ -1574,3 +1574,251 @@ span.taxon-lineage__name {
     display: none !important;
   }
 }
+
+/* ── The footer's note ───────────────────────────────────────────────────── */
+
+/* One line a site adds under the family — what its links can be handed out as.
+   The footer stacks only when it carries one, so a footer without a note is
+   laid out as it always was, and no site re-declares `.app-footer__inner`. */
+.app-footer__inner:has(> .app-footer__note) {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.app-footer__note {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+}
+
+.app-footer__note a {
+  color: var(--accent);
+}
+
+/* ── The site shell ──────────────────────────────────────────────────────── */
+
+/* The bar and the page own the screen they open on, so the family links in
+   the footer are always reached by scrolling. */
+.site-shell {
+  display: flex;
+  min-height: 100dvh;
+  flex-direction: column;
+}
+
+.site-shell__main {
+  width: 100%;
+  max-width: var(--page-max);
+  flex: 1 1 auto;
+  padding: 16px 1.25rem 24px;
+  margin: 0 auto;
+}
+
+/* Under a bar that runs full width, the page does too. */
+.site-shell__main--full {
+  max-width: none;
+}
+
+/* Framed in another site: the frame is the margin, and it is usually narrow. */
+.site-shell__main--embedded {
+  max-width: none;
+  padding: 8px;
+}
+
+@media (max-width: 40rem) {
+  .site-shell__main:not(.site-shell__main--embedded) {
+    padding-inline: 0.5rem;
+  }
+}
+
+/* ── A graded series ─────────────────────────────────────────────────────── */
+
+.exercise-series {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.exercise-series__head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.exercise-series__title {
+  margin: 0;
+  font-size: 1rem;
+  font-weight: 700;
+}
+
+.exercise-series__controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+/* The list and the open question share the row at the share the address
+   names, so no width is written here: `SplitRow` divides it. */
+.exercise-series__list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.exercise-series__number {
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.series-question {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.series-question__meta {
+  display: flex;
+  align-items: center;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+  gap: 0.5rem;
+}
+
+.series-question__prompt p {
+  margin: 0;
+  font-size: 1.0625rem;
+}
+
+.series-question__solution {
+  margin: 0 0 0.5rem;
+}
+
+.series-question__next {
+  margin-left: 0.75rem;
+}
+
+.series-answers {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0 1rem;
+}
+
+.series-answers__field {
+  width: 10rem;
+}
+
+/* A formula is read character by character, so its box is set monospace. */
+.formula-input input {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+/* ── A list of exercises ─────────────────────────────────────────────────── */
+
+.exercise-list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.exercise-list__rows {
+  display: flex;
+  overflow: auto;
+  max-height: 30rem;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.exercise-list__item {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  padding: 5px 7px;
+  border: 1px solid transparent;
+  border-radius: var(--radius);
+  background: none;
+  color: var(--text-muted);
+  font: inherit;
+  font-size: 0.875rem;
+  gap: 6px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.exercise-list__item:hover {
+  background: var(--surface-sunken);
+  color: var(--text);
+}
+
+/* The brand tint says which one is open, as it says which page is. */
+.exercise-list__item--active,
+.exercise-list__item--active:hover {
+  border-color: color-mix(in oklab, var(--accent) 30%, white);
+  background: color-mix(in oklab, var(--accent) 12%, white);
+  color: var(--accent);
+}
+
+.exercise-list__title {
+  min-width: 0;
+  flex: 1 1 6rem;
+  font-weight: 600;
+}
+
+/* The tags travel together: left loose in the row, a long title strands the
+   level at the end of one line and drops the kind onto the next. */
+.exercise-list__tags {
+  display: inline-flex;
+  flex: 0 0 auto;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: 6px;
+}
+
+/* ── A table of properties ───────────────────────────────────────────────── */
+
+.properties__title {
+  margin: 0 0 0.35rem;
+  color: var(--text-muted);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.properties__table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.875rem;
+}
+
+.properties__table th {
+  padding: 0.3rem 0.75rem 0.3rem 0;
+  color: var(--text-muted);
+  font-weight: 500;
+  text-align: left;
+  vertical-align: top;
+}
+
+.properties__table td {
+  padding: 0.3rem 22px 0.3rem 0;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+  vertical-align: top;
+  word-break: break-all;
+}
+
+.properties__note {
+  display: block;
+  color: var(--text-faint);
+  font-size: 0.75rem;
+}
+
+.properties__table td code {
+  display: inline-block;
+  max-width: 100%;
+  font-size: 0.8125rem;
+  text-align: left;
+  word-break: break-all;
+}