react-cheminfo 0.2.0 → 0.4.0

package/src/orbital/ui/renderVolume.ts

@@ -0,0 +1,203 @@
+/**
+ * Signed isosurfaces of a scalar field the caller sampled itself.
+ *
+ * Molstar can collocate an orbital on the GPU from a Gaussian basis, but that
+ * path cannot draw an *atomic* orbital: a hydrogen-like radial function has
+ * nodes, and an f orbital an angular momentum, that a valence STO-3G basis
+ * simply does not carry. So `core/atomicGrid.ts` samples the wavefunction
+ * itself, in ångström, and this module wraps the result in the `Volume`
+ * molstar's isosurface renderer wants.
+ *
+ * The two phases come from one field and one isovalue, so they can never
+ * disagree about where the node is. The representations live outside the state
+ * tree and are tracked per plugin, because every change of orbital replaces
+ * them wholesale.
+ */
+
+import type { Volume } from 'molstar/lib/mol-model/volume.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import { createVolumeRepresentationParams } from 'molstar/lib/mol-plugin-state/helpers/volume-representation-params.js';
+import type { Representation } from 'molstar/lib/mol-repr/representation.js';
+import { Theme } from 'molstar/lib/mol-theme/theme.js';
+import { Color } from 'molstar/lib/mol-util/color/color.js';
+
+import type { OrbitalGrid } from '../core/grid.ts';
+import type { OrbitalContour } from '../core/isovalue.ts';
+
+import { DISPLAY_REACH, toVolume } from './volumeField.ts';
+
+/** Colours and opacity of one signed isosurface pair. */
+export interface VolumeStyle {
+  /**
+   * Lobe where the wavefunction is positive, as `#rrggbb`.
+   * @default '#2563eb'
+   */
+  positiveColour?: string;
+  /**
+   * Lobe where the wavefunction is negative, as `#rrggbb`.
+   * @default '#dc2626'
+   */
+  negativeColour?: string;
+  /**
+   * Isovalue as a multiple of the contour's own cutoff. Larger means a
+   * tighter, smaller surface.
+   * @default 1
+   */
+  relativeIsovalue?: number;
+  /**
+   * Surface opacity. Below 1 the far lobes show through the near ones.
+   * @default 0.72
+   */
+  alpha?: number;
+}
+
+/**
+ * Replace the isosurface pair drawn from a sampled field.
+ * @param plugin - The molstar context.
+ * @param field - The field, as `sampleAtomicOrbital` produced it.
+ * @param contour - The isovalue and reach measured on that field, as
+ * `runAtomicSample` returned them.
+ * @param style - See {@link VolumeStyle}.
+ * @returns How far the drawn surface reaches from the centre of the box,
+ * ångström — what a camera has to frame to fill the viewport with it.
+ * @throws {Error} When the canvas is not ready.
+ */
+export async function renderSampledVolume(
+  plugin: PluginContext,
+  field: OrbitalGrid,
+  contour: OrbitalContour,
+  style: VolumeStyle = {},
+): Promise<number> {
+  const canvas3d = plugin.canvas3d;
+  if (canvas3d === undefined) {
+    throw new Error('renderSampledVolume: the molstar canvas is not ready.');
+  }
+  const {
+    positiveColour = '#2563eb',
+    negativeColour = '#dc2626',
+    relativeIsovalue = 1,
+    alpha = 0.72,
+  } = style;
+  clearSampledVolume(plugin);
+
+  const { cutoff, reach } = contour;
+  // Molstar's camera clamps both its target distance and its near plane, so it
+  // cannot get close to a small object: uranium's 4f reaches 0.35 Å and would
+  // stay a dot in the corner whatever the camera is asked to frame. Every
+  // orbital is therefore drawn at one canonical size, and the true extent is
+  // reported as ⟨r⟩ and on the radial plot instead of by the picture's scale.
+  const volume = toVolume(field, reach > 0 ? DISPLAY_REACH / reach : 1);
+  // A nodeless orbital — every 1s — has no negative lobe at all, and asking for
+  // its isosurface would draw an empty mesh at value 0.
+  const surfaces = await Promise.all([
+    maybeSurface(
+      plugin,
+      volume,
+      field.max >= cutoff ? cutoff : undefined,
+      relativeIsovalue,
+      { colour: positiveColour, alpha },
+    ),
+    maybeSurface(
+      plugin,
+      volume,
+      field.min <= -cutoff ? -cutoff : undefined,
+      relativeIsovalue,
+      { colour: negativeColour, alpha },
+    ),
+  ]);
+  const drawn = surfaces.filter(
+    (surface): surface is Representation.Any => surface !== null,
+  );
+  representations.set(plugin, drawn);
+  for (const representation of drawn) canvas3d.add(representation);
+  // add() only queues; nothing appears until the queue is committed.
+  canvas3d.commit();
+  return reach > 0 ? DISPLAY_REACH : 0;
+}
+
+/**
+ * Remove the sampled isosurfaces, leaving anything else on the canvas.
+ * @param plugin - The molstar context.
+ */
+export function clearSampledVolume(plugin: PluginContext): void {
+  const previous = representations.get(plugin);
+  if (previous === undefined) return;
+  representations.delete(plugin);
+  for (const representation of previous) {
+    plugin.canvas3d?.remove(representation);
+  }
+  plugin.canvas3d?.commit();
+}
+
+/**
+ * One phase's surface, or nothing when the field never reaches that sign.
+ * @param plugin - The molstar context.
+ * @param volume - The volume the surface is built from.
+ * @param isovalue - Absolute isovalue of the surface.
+ * @param relativeIsovalue - Multiplier applied to it.
+ * @param style - Colour and opacity of the surface.
+ * @param style.colour - Surface colour, as `#rrggbb`.
+ * @param style.alpha - Surface opacity.
+ * @returns The surface representation.
+ */
+async function maybeSurface(
+  plugin: PluginContext,
+  volume: Volume,
+  isovalue: number | undefined,
+  relativeIsovalue: number,
+  style: { colour: string; alpha: number },
+): Promise<Representation.Any | null> {
+  if (isovalue === undefined || isovalue === 0) return null;
+  return createSurface(
+    plugin,
+    volume,
+    isovalue * relativeIsovalue,
+    style.colour,
+    style.alpha,
+  );
+}
+
+async function createSurface(
+  plugin: PluginContext,
+  volume: Volume,
+  isovalue: number,
+  colour: string,
+  alpha: number,
+): Promise<Representation.Any> {
+  const params = createVolumeRepresentationParams(plugin, volume, {
+    type: 'isosurface',
+    typeParams: {
+      isoValue: { kind: 'absolute', absoluteValue: isovalue },
+      alpha,
+      xrayShaded: true,
+      // Molstar's GPU marching cubes pits the outer lobe of a diffuse orbital
+      // with voxel-sized dimples — caesium's 6s and every 7s, 6d and 7p above
+      // it — and quantises the field to 255 steps on upload unless told
+      // otherwise, which terraces xenon's 4p. The surface is a thin shell
+      // whatever the box holds, so the CPU path costs 13–44 ms and returns
+      // 27 k vertices even on the 152³ grid the highest quality asks for.
+      tryUseGpu: false,
+    },
+    color: 'uniform',
+    colorParams: { value: Color.fromHexStyle(colour) },
+  });
+  const provider = plugin.representation.volume.registry.get(params.type.name);
+  const representation = provider.factory(
+    { webgl: plugin.canvas3d?.webgl, ...plugin.representation.volume.themes },
+    provider.getParams,
+  );
+  representation.setTheme(
+    Theme.create(plugin.representation.volume.themes, { volume }, params),
+  );
+  await plugin.runTask(
+    representation.createOrUpdate(params.type.params ?? {}, volume),
+  );
+  representation.setState({ pickable: false });
+  return representation;
+}
+
+/**
+ * One pair of surfaces per plugin. They are outside the state tree, like the
+ * cartoon lobes, because every change of orbital replaces them entirely.
+ */
+const representations = new WeakMap<PluginContext, Representation.Any[]>();

package/src/orbital/ui/viewer.ts

@@ -0,0 +1,191 @@
+/**
+ * Lifecycle of one molstar canvas, and the only object the components hold on
+ * to.
+ *
+ * `createOrbitalViewer` is **synchronous** on purpose. React 19 runs an effect,
+ * its cleanup and the effect again on every mount in development, so an
+ * `await`ed constructor hands the cleanup nothing to dispose and leaks a WebGL
+ * context per mount — browsers drop the oldest one after about sixteen, and the
+ * viewer silently goes blank. Returning the handle immediately means
+ * `dispose()` can always be called, even before initialisation has finished;
+ * the work is queued behind `ready`.
+ *
+ * molstar's own UI is not mounted: the surrounding site owns every control.
+ */
+
+import { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+// Lowercased on import: it is a factory, not a constructor.
+import { DefaultPluginSpec as defaultPluginSpec } from 'molstar/lib/mol-plugin/spec.js';
+import { Color } from 'molstar/lib/mol-util/color/color.js';
+
+import type { OrbitalGrid } from '../core/grid.ts';
+import type { OrbitalContour } from '../core/isovalue.ts';
+
+import { DEFAULT_CAMERA_DURATION, frameOrbital, setSpin } from './camera.ts';
+import type { VolumeStyle } from './renderVolume.ts';
+import { clearSampledVolume, renderSampledVolume } from './renderVolume.ts';
+
+/** Settings fixed for the life of a viewer. */
+export interface OrbitalViewerOptions {
+  /**
+   * Scene background, as `#rrggbb`.
+   * @default '#ffffff'
+   */
+  background?: string;
+}
+
+/**
+ * Create a viewer inside `container` and start initialising it.
+ * @param container - An element with `position: relative`; molstar inserts its
+ * own canvas into it.
+ * @param options - See {@link OrbitalViewerOptions}.
+ * @returns A handle that is safe to dispose immediately.
+ */
+export function createOrbitalViewer(
+  container: HTMLElement,
+  options: OrbitalViewerOptions = {},
+): OrbitalViewer {
+  return new OrbitalViewer(container, options);
+}
+
+/**
+ * One molstar canvas showing one atomic orbital.
+ *
+ * Every method resolves to nothing once `dispose` has been called, so a
+ * render started by an unmounting component cannot throw into React.
+ */
+export class OrbitalViewer {
+  readonly #model: PluginViewModel;
+  #disposed = false;
+
+  /** Resolves once the canvas exists; every method awaits it internally. */
+  readonly ready: Promise<void>;
+
+  constructor(container: HTMLElement, options: OrbitalViewerOptions = {}) {
+    const { background = '#ffffff' } = options;
+    const spec = defaultPluginSpec();
+    this.#model = new PluginViewModel({
+      spec: {
+        ...spec,
+        canvas3d: {
+          ...spec.canvas3d,
+          renderer: { backgroundColor: Color.fromHexStyle(background) },
+          camera: { helper: { axes: { name: 'off', params: {} } } },
+        },
+      },
+    });
+    this.#model.mount(container);
+    this.ready = this.#model.initialized;
+  }
+
+  /**
+   * Whether `dispose` has been called.
+   * @returns True once the viewer has been disposed.
+   */
+  get disposed(): boolean {
+    return this.#disposed;
+  }
+
+  /**
+   * Replace the isosurface pair with one drawn from a sampled field.
+   * @param field - The sampled wavefunction, in ångström.
+   * @param contour - The isovalue and reach measured on that field.
+   * @param style - See {@link VolumeStyle}.
+   * @returns How far the drawn surface reaches, in scene units, for the camera
+   * to frame; `undefined` once the viewer has been disposed.
+   */
+  showOrbital(
+    field: OrbitalGrid,
+    contour: OrbitalContour,
+    style?: VolumeStyle,
+  ): Promise<number | undefined> {
+    return this.#run((plugin) =>
+      renderSampledVolume(plugin, field, contour, style),
+    );
+  }
+
+  /**
+   * Remove the isosurface pair.
+   * @returns Nothing, once the surfaces are gone.
+   */
+  hideOrbital(): Promise<void> {
+    return this.#run((plugin) => {
+      clearSampledVolume(plugin);
+    });
+  }
+
+  /**
+   * Frame the scene from an oblique angle with z up — how a lone atom's
+   * orbital has to be seen for its lobes to be told apart.
+   * @param orbitalRadius - Extent of the drawn surface; the scene's own
+   * bounding sphere is used when omitted.
+   * @param durationMs - Transition length; 0 jumps.
+   * @returns Nothing, once the camera has been set.
+   */
+  frame(
+    orbitalRadius?: number,
+    durationMs = DEFAULT_CAMERA_DURATION,
+  ): Promise<void> {
+    return this.#run((plugin) => {
+      frameOrbital(plugin, orbitalRadius, durationMs);
+    });
+  }
+
+  /**
+   * Turn the automatic spin on or off.
+   * @param spinning - Whether the scene should keep turning.
+   * @param speed - molstar's own spin unit.
+   * @returns Nothing, once the spin has been switched.
+   */
+  setSpin(spinning: boolean, speed = 1): Promise<void> {
+    return this.#run((plugin) => {
+      setSpin(plugin, spinning, speed);
+    });
+  }
+
+  /** Re-read the container's size. Call from a `ResizeObserver`. */
+  handleResize(): void {
+    if (this.#disposed) return;
+    this.#model.plugin.handleResize();
+  }
+
+  /**
+   * Tear the viewer down and release its WebGL context. Idempotent, and safe to
+   * call before initialisation has finished.
+   */
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    // `mount` creates the canvas synchronously, so the WebGL context exists
+    // even when initialisation went on to fail; releasing it is what stops the
+    // browser dropping an older viewer's context. A rejected `ready` must not
+    // escape here either — nobody is left to handle it.
+    void this.ready
+      .catch(() => undefined)
+      .then(() => {
+        this.#model.plugin.dispose();
+      });
+  }
+
+  /**
+   * Wait for initialisation, then run `action` on the plugin. Resolves to
+   * `undefined` when the viewer was disposed, before the call or while `action`
+   * was still running; an initialisation failure still reaches the caller.
+   * @param action - What to run once the canvas is ready.
+   * @returns What `action` returned, or `undefined` when disposed.
+   */
+  async #run<Result>(
+    action: (plugin: PluginContext) => Result | Promise<Result>,
+  ): Promise<Result | undefined> {
+    if (this.#disposed) return undefined;
+    await this.ready;
+    if (this.#disposed) return undefined;
+    try {
+      return await action(this.#model.plugin);
+    } catch (error) {
+      if (this.#disposed) return undefined;
+      throw error;
+    }
+  }
+}

package/src/orbital/ui/volumeField.ts

@@ -0,0 +1,84 @@
+/**
+ * Turning a field the caller sampled into the `Volume` molstar's isosurface
+ * renderer wants.
+ *
+ * It is arithmetic over the samples, which is why it is here rather than in
+ * `renderVolume.ts` — that module is about representations. How far the
+ * surface inside the box reaches is measured in `core/isovalue.ts`, beside the
+ * isovalue it is measured against.
+ */
+
+import { Mat4, Tensor, Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import { CustomProperties } from 'molstar/lib/mol-model/custom-property.js';
+import type { Grid, Volume } from 'molstar/lib/mol-model/volume.js';
+
+import type { OrbitalGrid } from '../core/grid.ts';
+
+// Lowercased on destructuring: both are factories, not constructors.
+const { Space: createTensorSpace, Data1: asTensorData } = Tensor;
+
+/**
+ * Radius, in scene units, every atomic orbital is drawn at.
+ *
+ * Comfortably clear of molstar's `minNear` of 5 and of the floor its camera
+ * puts under the target distance, both of which make a sub-ångström object
+ * impossible to fill the frame with.
+ */
+export const DISPLAY_REACH = 12;
+
+/**
+ * Wrap a sampled field in molstar's `Volume`.
+ *
+ * The grid-to-cartesian transform is built here rather than through the
+ * alpha-orbitals helper, which expects its box in bohr and converts on the way
+ * out; our fields are already in ångström and a round trip through two slightly
+ * different bohr constants is a needless source of drift.
+ * @param field - The sampled field.
+ * @param displayScale - Factor applied to every coordinate, so a tight orbital
+ * can be drawn at a size the camera can actually frame.
+ * @returns The volume, ready for an isosurface representation.
+ */
+export function toVolume(field: OrbitalGrid, displayScale: number): Volume {
+  const { data, dimensions, origin, spacing, min, max, mean, sigma } = field;
+  const step = spacing * displayScale;
+  const scale = Mat4.fromScaling(Mat4.zero(), Vec3.create(step, step, step));
+  const translate = Mat4.fromTranslation(
+    Mat4.zero(),
+    Vec3.create(
+      origin.x * displayScale,
+      origin.y * displayScale,
+      origin.z * displayScale,
+    ),
+  );
+  const grid: Grid = {
+    transform: {
+      kind: 'matrix',
+      matrix: Mat4.mul(Mat4.zero(), translate, scale),
+    },
+    // [0, 1, 2] is the axis order `evaluateGrid` writes: z varies fastest.
+    cells: Tensor.create(
+      createTensorSpace(dimensions, [0, 1, 2], Float32Array),
+      asTensorData(data),
+    ),
+    stats: {
+      min,
+      max,
+      mean,
+      // molstar's `sigma` is the root mean square, not the standard deviation,
+      // and its volume themes read it that way.
+      sigma: Math.hypot(sigma, mean),
+    },
+  };
+  return {
+    grid,
+    instances: [{ transform: Mat4.identity() }],
+    sourceData: {
+      name: 'react-cheminfo sampled orbital',
+      kind: 'atomic-orbital-field',
+      data,
+    },
+    customProperties: new CustomProperties(),
+    _propertyData: Object.create(null) as Record<string, unknown>,
+    _localPropertyData: Object.create(null) as Record<string, unknown>,
+  };
+}

package/src/orbital.ts

@@ -0,0 +1,11 @@
+/**
+ * The molstar-backed orbital viewer.
+ *
+ * A third entry point, and not part of `react-cheminfo/ui`, because molstar is
+ * several megabytes: a site that only wants the Tools menu must never be made
+ * to carry it. Everything here is React; the maths these components draw is in
+ * `react-cheminfo/core` and needs neither React nor molstar, so a worker can
+ * import it on its own.
+ */
+
+export * from './orbital/ui/index.ts';

package/src/pedagogy/core/glossary.ts

@@ -0,0 +1,122 @@
+/**
+ * The `[[term]]` marker language, parsed without a DOM.
+ *
+ * Authored prose — tutorial steps, exercise descriptions, hints — links its
+ * jargon by wrapping it in `[[double brackets]]`. A marker may be written
+ * `[[term|displayed text]]` when the sentence needs a different wording than
+ * the glossary key. Parsing and resolution live here, in plain TypeScript, so
+ * both are unit-tested without rendering anything.
+ */
+
+/** One worked example inside a glossary entry. */
+export interface GlossaryExample {
+  /** The construct itself: a pattern, a SMILES, a LaTeX fragment, a layer. */
+  code: string;
+  /**
+   * What the construct is shown working on, for a term whose examples take an
+   * input. Left out when the example is about notation only.
+   * @default undefined
+   */
+  input?: string;
+  /**
+   * What this example demonstrates, in one line.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** One glossary term, shown wherever a `[[marker]]` names it. */
+export interface GlossaryEntry {
+  /** The term, spelled out as the heading of the tooltip. */
+  title: string;
+  /** One short paragraph — the whole definition. */
+  summary: string;
+  /** Worked examples, shown under the summary. */
+  examples: GlossaryExample[];
+}
+
+/**
+ * Every term a site defines, keyed by the lowercased text inside a `[[...]]`.
+ *
+ * A key that no marker names is simply never shown, and a marker naming no key
+ * renders as plain prose — so the two sides may be written in either order.
+ */
+export type Glossary = Record<string, GlossaryEntry>;
+
+/**
+ * One piece of parsed prose: either a run of text, or one marker.
+ *
+ * `start` is the offset of the piece in the source string, which makes it a
+ * stable and unique React key — an array index is neither.
+ */
+export type GlossarySegment =
+  | { kind: 'text'; start: number; text: string }
+  | { kind: 'term'; start: number; term: string; text: string };
+
+/**
+ * Split authored prose into prose runs and markers.
+ *
+ * A marker yields the lowercased lookup `term` and the `text` to display, which
+ * are the same thing unless the marker used the `term|text` form. The term is
+ * never checked against any glossary here: an unknown term still produces a
+ * `term` segment, and the renderer falls back to showing its text as plain
+ * prose — an author may link a term months before it is written, and the page
+ * must never show the brackets. Text that never closes its brackets (`[[foo`)
+ * is not a marker at all and comes back verbatim inside a `text` segment.
+ * @param text - Authored prose, with or without markers.
+ * @returns The segments, in order, with no empty run between adjacent markers.
+ */
+export function parseGlossaryMarkers(text: string): GlossarySegment[] {
+  const segments: GlossarySegment[] = [];
+  // A fresh regexp per call: a /g/ literal carries `lastIndex` between calls.
+  const marker = new RegExp(MARKER_SOURCE, 'g');
+  let cursor = 0;
+  let match = marker.exec(text);
+  while (match !== null) {
+    if (match.index > cursor) {
+      segments.push({
+        kind: 'text',
+        start: cursor,
+        text: text.slice(cursor, match.index),
+      });
+    }
+    segments.push(toTermSegment(match.groups?.term ?? '', match.index));
+    cursor = match.index + match[0].length;
+    match = marker.exec(text);
+  }
+  if (cursor < text.length) {
+    segments.push({ kind: 'text', start: cursor, text: text.slice(cursor) });
+  }
+  return segments;
+}
+
+/**
+ * Resolve a marker term against a glossary, case-insensitively.
+ * @param glossary - The terms the site defines.
+ * @param term - The text before the pipe of a `[[marker]]`, in any case.
+ * @returns The entry, or `undefined` when no such term has been written yet.
+ */
+export function lookupGlossaryTerm(
+  glossary: Glossary,
+  term: string,
+): GlossaryEntry | undefined {
+  const key = term.trim().toLowerCase();
+  // `[[constructor]]` and `[[tostring]]` are prose, not inherited members.
+  return Object.hasOwn(glossary, key) ? glossary[key] : undefined;
+}
+
+const MARKER_SOURCE = String.raw`\[\[(?<term>[^\]]+)\]\]`;
+
+function toTermSegment(inner: string, start: number): GlossarySegment {
+  const pipe = inner.indexOf('|');
+  const rawTerm = pipe === -1 ? inner : inner.slice(0, pipe);
+  const rawText = pipe === -1 ? inner : inner.slice(pipe + 1);
+  const term = rawTerm.trim().toLowerCase();
+  const text = rawText.trim();
+  return {
+    kind: 'term',
+    start,
+    term,
+    text: text === '' ? rawTerm.trim() : text,
+  };
+}

package/src/pedagogy/core/index.ts

@@ -0,0 +1,28 @@
+export type {
+  Glossary,
+  GlossaryEntry,
+  GlossaryExample,
+  GlossarySegment,
+} from './glossary.ts';
+export { parseGlossaryMarkers } from './glossary.ts';
+export type {
+  ExerciseProgress,
+  LocalStorageProgressStoreOptions,
+  ProgressRecords,
+  ProgressStore,
+  ProgressSummary,
+} from './progress.ts';
+export { localStorageProgressStore, progressSummary } from './progress.ts';
+export type {
+  BaseExercise,
+  ExerciseLevel,
+  ExerciseSet,
+  ExerciseStatus,
+  TutorialStep,
+} from './types.ts';
+export type {
+  FinishValidationOptions,
+  TestCaseResult,
+  ValidationResult,
+} from './validation.ts';
+export { failedValidation, finishValidation } from './validation.ts';

package/src/pedagogy/core/jsonStorage.ts

@@ -0,0 +1,51 @@
+/**
+ * Best-effort JSON access to `localStorage`.
+ *
+ * A page framed in a course may have no storage at all — third-party storage is
+ * partitioned in Chrome and blocked in Safari — and a full quota must never
+ * take the page down with it. So both calls swallow everything: an unreadable
+ * entry reads as nothing stored, and a refused write is simply lost.
+ */
+
+/**
+ * Read one entry back as JSON.
+ * @param key - The storage key.
+ * @returns What was parsed, or `undefined` when there is nothing readable.
+ */
+export function readJsonEntry(key: string): unknown {
+  const storage = getStorage();
+  if (storage === null) return undefined;
+  try {
+    const raw = storage.getItem(key);
+    if (raw === null) return undefined;
+    return JSON.parse(raw) as unknown;
+  } catch {
+    // Corrupt JSON, or a store that refuses to be read.
+    return undefined;
+  }
+}
+
+/**
+ * Write one entry as JSON.
+ * @param key - The storage key.
+ * @param value - What to store.
+ */
+export function writeJsonEntry(key: string, value: unknown): void {
+  const storage = getStorage();
+  if (storage === null) return;
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {
+    // Quota exceeded, or a store that refuses to be written.
+  }
+}
+
+function getStorage(): Storage | null {
+  try {
+    const candidate = globalThis.localStorage as Storage | undefined;
+    return candidate ?? null;
+  } catch {
+    // Reading localStorage throws outright when storage is blocked.
+    return null;
+  }
+}