react-cheminfo 0.8.0 → 0.10.0

package/README.md

@@ -37,7 +37,9 @@ only when it drags a heavy dependency behind it.
 | `react-cheminfo/vite`              | the prerender plugin and the OG card              | nothing; React on the card |
 | `react-cheminfo/orbital`           | the 3D atomic-orbital viewer                      | React, molstar             |
 | `react-cheminfo/structure`         | the structure editor and renderer                 | React, react-ocl, OCL      |
+| `react-cheminfo/slides`            | the deck format and the slideshow player          | React, react-markdown      |
 | `react-cheminfo/styles/chrome.css` | the shared tokens and site-header stylesheet      | nothing                    |
+| `react-cheminfo/styles/slides.css` | the deck stylesheet, themed on the site's colours | nothing                    |
 
 A backend serving an RIS endpoint, a prerender script writing a sitemap, and
 every unit test of that logic therefore load no React at all — and a worker
@@ -55,24 +57,30 @@ through a wildcard subpath exactly as `react-science` serves its own.
 
 ## What is in it
 
-| Area                    | `…/core`                                                                                                                                                                                                          | `…/ui`                                                                                                                                           |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Site identity**       | `siteById`, `findSiteByHost`, `siteTokensCss`, `siteThemeColor`, `renderEcosystemLinksHtml`                                                                                                                       | `SiteMark`, `Wordmark`, `SiteTheme`, `SiteTile`, `EcosystemButton`, `EcosystemLinks`                                                             |
-| **Chrome**              | —                                                                                                                                                                                                                 | `SiteHeader`, `SiteFooter`, `NavLink`, `NavMenuButton`, `MenuButton`, `useCompactHeader`                                                         |
-| **Citation**            | `formatCitation`, `formatCitations`, `citationSegments`, `downloadCitation`, `citedReferences`, `doiUrl`                                                                                                          | `CiteButton`, `CitationMenu`, `CitationPreview`                                                                                                  |
-| **Share & embed**       | `parseShareConfig`, `applyShareConfig`, `buildShareUrl`, `buildEmbedCode`, `isHidden`, the param codecs                                                                                                           | `ShareDialog`, `ShareButton`, `HiddenPartsProvider`, `PagePart`, `useIsHidden`                                                                   |
-| **Routing & head**      | `createTabRouter`, `createPageAddresses`, `adoptLegacyHashAddress`, `writeDocumentMeta`, `canonicalLink`                                                                                                          | —                                                                                                                                                |
-| **Indexing**            | `injectPageMeta`, `pageHeadTags`, `pageDocumentMeta`, `fill`, `PAGE_HEAD_MARKER`, `PAGE_BODY_MARKER`, `robotsTxt`, `sitemapXml`, `noscriptIndex`, `structuredDataScript`, `assertRoutes`, `routeFor`, `homeRoute` | `cheminfoPrerender`, `ogCardHtml`, `OG_WIDTH`, `OG_HEIGHT` (all `/vite`)                                                                         |
-| **Pedagogy**            | `parseGlossaryMarkers`, `localStorageProgressStore`, `progressSummary`, `finishValidation`                                                                                                                        | `GlossaryText`, `SyntaxTooltip`, `HintLadder`, `ExerciseActions`, `ExerciseProgressHeader`, `TutorialStepStrip`, `ReferenceGrid`, `TestCaseList` |
-| **Clipboard & files**   | `writeToClipboard`, `downloadBlob`, `downloadText`, `sanitizeFileName`, `toDelimited`, `readDelimited`                                                                                                            | `CopyButton`, `CodeBlock`, `DelimitedTextDialog`                                                                                                 |
-| **Formatting & colour** | `formatInteger`, `formatDecimal`, `formatBytes`, `pluralize`, `readableInk`, `contrastRatio`                                                                                                                      | `ColorScaleLegend`                                                                                                                               |
-| **Widgets**             | `CREDITS`, `credits`                                                                                                                                                                                              | `ErrorBoundary`, `CollapsibleSection`, `CapsuleFilter`, `HelpTooltip`, `CreditsList`                                                             |
-| **Hooks & state**       | `createWorkerChannel`                                                                                                                                                                                             | `persistBucket`, `useDebouncedValue`, `useContainerSize`, `useListKeyboardNavigation`, `useDisclosure`                                           |
-| **Chemistry**           | `atomicOrbitalsOf`, `configurationOf`, `classifyMolfile`, `readStructure`                                                                                                                                         | `AtomicOrbitalViewer` (`/orbital`), `StructureEditor`, `Structure` (`/structure`)                                                                |
-| **Periodic table**      | `PERIODIC_ELEMENTS`, `elementBySymbol`, `elementByAtomicNumber`, `cellOf`, `placedElements`, `elementByArrowKey`, `categorySwatch`, `CATEGORY_LABELS`                                                             | `PeriodicTable`, `ElementCell`, `CategoryLegend`                                                                                                 |
-
-Everything in that table is exported from `./core`, `./ui`, `./vite` or
-`./structure` and nothing else is: the sub-components a component is built
+| Area                    | `…/core`                                                                                                                                                                                                                      | `…/ui`                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Site identity**       | `siteById`, `findSiteByHost`, `siteTokensCss`, `siteThemeColor`, `renderEcosystemLinksHtml`                                                                                                                                   | `SiteMark`, `Wordmark`, `SiteTheme`, `SiteTile`, `EcosystemButton`, `EcosystemLinks`                                                                                                    |
+| **Chrome**              | —                                                                                                                                                                                                                             | `SiteHeader`, `SiteFooter`, `NavLink`, `NavMenuButton`, `MenuButton`, `useCompactHeader`                                                                                                |
+| **Citation**            | `formatCitation`, `formatCitations`, `citationSegments`, `downloadCitation`, `citedReferences`, `doiUrl`                                                                                                                      | `CiteButton`, `CitationMenu`, `CitationPreview`                                                                                                                                         |
+| **Share & embed**       | `parseShareConfig`, `applyShareConfig`, `buildShareUrl`, `buildEmbedCode`, `isHidden`, the param codecs                                                                                                                       | `ShareDialog`, `ShareButton`, `HiddenPartsProvider`, `PagePart`, `useIsHidden`                                                                                                          |
+| **Routing & head**      | `createTabRouter`, `createPageAddresses`, `adoptLegacyHashAddress`, `writeDocumentMeta`, `canonicalLink`                                                                                                                      | —                                                                                                                                                                                       |
+| **Indexing**            | `injectPageMeta`, `pageHeadTags`, `pageDocumentMeta`, `fill`, `PAGE_HEAD_MARKER`, `PAGE_BODY_MARKER`, `robotsTxt`, `sitemapXml`, `noscriptIndex`, `structuredDataScript`, `assertRoutes`, `routeFor`, `homeRoute`             | `cheminfoPrerender`, `ogCardHtml`, `OG_WIDTH`, `OG_HEIGHT` (all `/vite`)                                                                                                                |
+| **Pedagogy**            | `parseGlossaryMarkers`, `localStorageProgressStore`, `progressSummary`, `finishValidation`                                                                                                                                    | `GlossaryText`, `SyntaxTooltip`, `HintLadder`, `ExerciseActions`, `ExerciseProgressHeader`, `TutorialStepStrip`, `ReferenceGrid`, `TestCaseList`                                        |
+| **Clipboard & files**   | `writeToClipboard`, `downloadBlob`, `downloadText`, `sanitizeFileName`, `toDelimited`, `readDelimited`, `downloadFigure`, `figureSvg`, `figurePng`, `figureSize`                                                              | `CopyButton`, `CodeBlock`, `DelimitedTextDialog`, `FigureDownload`                                                                                                                      |
+| **Formatting & colour** | `formatInteger`, `formatDecimal`, `formatBytes`, `pluralize`, `readableInk`, `contrastRatio`, `COLOR_SCALES`, `resolveColorScale`, `formatColorScale`, `colorAt`, `swatchAt`, `sampleScale`, `colorScaleGradient`, `rgbToHsv` | `ColorScaleLegend`, `ColorScaleSelect`, `ColorScaleEditor`, `ColorScaleBar`                                                                                                             |
+| **Widgets**             | `CREDITS`, `credits`                                                                                                                                                                                                          | `ErrorBoundary`, `CollapsibleSection`, `CapsuleFilter`, `HelpTooltip`, `CreditsList`                                                                                                    |
+| **Hooks & state**       | `createWorkerChannel`                                                                                                                                                                                                         | `persistBucket`, `useDebouncedValue`, `useContainerSize`, `useListKeyboardNavigation`, `useDisclosure`                                                                                  |
+| **Chemistry**           | `atomicOrbitalsOf`, `configurationOf`, `classifyMolfile`, `readStructure`                                                                                                                                                     | `AtomicOrbitalViewer` (`/orbital`), `StructureEditor`, `Structure` (`/structure`)                                                                                                       |
+| **Spectra**             | `FILTER_CATALOG`, `filterMenu`, `settingsProblems`, `normalizationFilters`, `addFilter`, `moveFilter`, `setFilterOption`, `principalComponentChoices`, `clampPrincipalComponents`, `EMPTY_SETTINGS`                           | `SpectraSettingsEditor`, `FilterChainEditor`, `PrincipalComponentSelect`                                                                                                                |
+| **About**               | `resolveAbout`, `aboutProblems`                                                                                                                                                                                               | `AboutPage`                                                                                                                                                                             |
+| **Slideshows**          | `parseTalk`, `splitDemoLinks`, `slideActionForKey`, `parseTalkOrigin`, `buildTalkManifest` (all `/slides`)                                                                                                                    | `Slideshow`, `SlideView`, `TalkList`, `BackToSlides` (all `/slides`), `cheminfoTalks` (`/vite`)                                                                                         |
+| **Token guard**         | `findTokenViolations`                                                                                                                                                                                                         | `cheminfo-check-tokens` (the bin)                                                                                                                                                       |
+| **Figures**             | `chartScale`, `chartAxisScale`, `chartAxisTitle`, `chartShare`, `chartColumnExtent`, `chartBinCounts`, `chartSeriesColor`, `rowMatrix`, `stackedMatrix`, `emptiestCorner`, `placeOverlayCard`, `overlayMetrics`               | `ChartFrame`, `ChartAxis`, `TrackedLineChart`, `OverlayBar`, `OverlaySelect`, `OverlaySegmented`, `OverlayToggle`, `OverlayNumber`, `OverlayLegend`, `OverlayCaption`, `OverlayReadout` |
+| **Projections**         | `pcaResult`, `embeddingResult`, `projectionTabs`, `loadingProfiles`, `explainedShares`, `confidenceEllipse`, `projectEllipse`, `pointsInPolygon`, `resolveProjectionGroups`, `PROJECTION_COPY`                                | `PcaViewer`, `ProjectionViewer`, `ScatterPlot`, `ScatterMatrix`                                                                                                                         |
+| **Periodic table**      | `PERIODIC_ELEMENTS`, `elementBySymbol`, `elementByAtomicNumber`, `cellOf`, `placedElements`, `elementByArrowKey`, `categorySwatch`, `CATEGORY_LABELS`                                                                         | `PeriodicTable`, `ElementCell`, `CategoryLegend`                                                                                                                                        |
+
+Everything in that table is exported from `./core`, `./ui`, `./slides`,
+`./vite` or `./structure` and nothing else is: the sub-components a component is built
 from, the parsers a helper calls and the internals of a hook stay inside the
 package, reachable only by their own path. If it is exported, it is supported.
 
@@ -82,11 +90,11 @@ second, your own code last.** The full import table and the checklist live in
 
 ## Seeing it
 
-Storybook is the demo, and every exported component has one — 210 stories:
+Storybook is the demo, and every exported component has one — 287 stories:
 
 ```console
 npm run dev              # the book on http://localhost:10815
-npm run test-e2e         # Playwright opens all 210 and fails on any console error
+npm run test-e2e         # Playwright opens all 287 and fails on any console error
 ```
 
 The **Brand** toolbar at the top retunes `--brand` / `--brand-alt`, so any story
@@ -260,6 +268,287 @@ The colours a name is set in are the site's own and are not retuned to reach the
 4.5:1 of body text: ChemCalc's teal and NMRium's orange both land just under it,
 which is why a name is set bold, where 3:1 is the threshold.
 
+### `ColorScaleSelect`
+
+The colours a quantity is read with, chosen by looking at them rather than by
+reading their names — and, behind the last entry, built from anchors of the
+reader's own.
+
+```tsx
+import { COLOR_SCALES, resolveColorScale, swatchAt } from 'react-cheminfo/core';
+import { ColorScaleSelect } from 'react-cheminfo/ui';
+
+<ColorScaleSelect label="Colour scale" value={scale} onChange={setScale} />;
+
+const { scale } = resolveColorScale(text); // 'plasma', or 'hsv-long,0-0000ff,1-ff0000'
+swatchAt(scale, 0.5); // { background, foreground }
+```
+
+- **The choice is one string**, which is what goes in the state and in the
+  address: the id of one of `COLOR_SCALES`, or a scale spelled out. Nothing else
+  has to be carried, and `resolveColorScale` never throws — a scale renamed
+  since a course page was written falls back to viridis rather than blanking the
+  figure.
+- **Ten scales are offered**: viridis, plasma, magma, inferno, cividis and
+  turbo; greys for a photocopier; cool-warm and blue-red for a quantity read
+  away from a middle; and the rainbow, which orders nothing but is what a course
+  usually draws.
+- **A custom scale is anchors plus a path.** `rgb` mixes the three channels,
+  which is what a browser gradient does; `hsv` turns along the colour wheel the
+  short way, keeping the saturation instead of fading through the grey in the
+  middle; `hsv-long` turns the other way, which is how two anchors of one hue
+  draw a whole rainbow. `ColorScaleEditor` is that editor on its own, for a site
+  that wants it inline.
+- **A scale that turns is sampled, never handed to CSS as its two ends** — a
+  browser only interpolates the straight line between two colours.
+  `colorScaleGradient` and `ColorScaleBar` do the sampling.
+
+### `SpectraSettingsEditor`
+
+Everything [`spectra-processor`](https://github.com/cheminfo/spectra-processor)
+can be told, laid out in the order it happens — and the principal components a
+score plot is then drawn against.
+
+```tsx
+import { EMPTY_SETTINGS, settingsProblems } from 'react-cheminfo/core';
+import { SpectraSettingsEditor } from 'react-cheminfo/ui';
+
+<SpectraSettingsEditor
+  value={settings}
+  onChange={setSettings}
+  spectrumIds={processor.getIDs()}
+  principalComponents={{
+    selection,
+    onSelectionChange: setSelection, // { x: 0, y: 1 } — columns of the score matrix
+    count: scores.columns,
+    explainedVariance: pca.getExplainedVariance(),
+    settings: pcaOptions,
+    onSettingsChange: setPcaOptions,
+  }}
+/>;
+
+processor.setNormalization(settings.processor.normalization);
+processor.getPostProcessedData(settings.postProcessing);
+```
+
+- **The types come from the packages that own them**, not from a copy.
+  `src/spectra/core/settings.ts` is the only file naming `spectra-processor` or
+  `ml-signal-processing`, and it reads the shapes off their public surface —
+  `ConstructorParameters<typeof SpectraProcessor>[0]`, `FilterXYType`. Both are
+  optional peers and every import is `import type`, so a site that does not use
+  this component downloads neither.
+- **All 23 chain steps are offered**, grouped as a chain is built — baseline,
+  smoothing and derivatives, scaling, the two axes, housekeeping — with every
+  option each one takes, down to the nested peak picking of `calibrateX`. The
+  catalog is a `Record` keyed by the step name, so the day `ml-signal-processing`
+  adds a filter this package stops compiling instead of quietly not offering it.
+- **The order is the meaning, so it is editable and it is checked.** A step moves
+  with two arrow buttons — no drag dependency, and it works from the keyboard.
+  Scaling placed before the baseline it depends on, a second resampling, a crop
+  that leaves the spectra on grids that no longer line up: each is named where it
+  sits.
+- **Nothing blocks.** A reader mid-thought may hold settings the processor would
+  throw on. `settingsProblems` says which value it would throw on — separating
+  what fails from what merely looks unintended — and the editor still takes the
+  edit.
+- **A cleared box means "whatever upstream does"**, never `undefined` written
+  into the settings, which is the only way back to a default once it has been
+  typed over. A half-typed `1e-` is kept as typed rather than parsed away.
+- **The components are named `PC1` and handed back as `0`.** The label is what a
+  chemist writes; the number is the column of the score matrix, because that is
+  what indexes it. `clampPrincipalComponents` keeps a selection saved on other
+  data inside the components that exist, and keeps the two axes apart so a plot
+  never collapses onto its diagonal. `FilterChainEditor` and
+  `PrincipalComponentSelect` are each usable on their own.
+
+### `PcaViewer`
+
+A finished principal component analysis, read by somebody who has never met one.
+
+```tsx
+import { PCA } from 'ml-pca';
+import { PcaViewer } from 'react-cheminfo/ui';
+
+const pca = new PCA(rows, { scale: true });
+
+<PcaViewer
+  pca={pca}
+  rows={rows}
+  scaled
+  projected={newBatch} // placed into the finished model, drawn hollow
+  variables={{
+    kind: 'named',
+    names: ['Sepal length', 'Sepal width', 'Petal length', 'Petal width'],
+    unit: 'cm',
+  }}
+  samples={{
+    ids,
+    groups: species,
+    groupLabel: 'Species',
+    fields: (index) => [
+      { label: 'Sepal length', value: `${rows[index][0]} cm` },
+    ],
+  }}
+  onSelectionChange={(ids) => setPicked(ids)}
+  onTrackVariable={(track) => setHovered(track?.readout ?? null)}
+/>;
+```
+
+- **Four tabs, and only the ones the data can fill.** `projectionTabs` reads the
+  result rather than a prop: a principal component analysis publishes a share of
+  the variance and a set of weights, so it gets the map, every pair, what differs
+  and how much each explains. A UMAP embedding publishes neither, so it gets the
+  map alone — one tab and no tab strip, instead of three empty ones.
+- **It never imports `ml-pca`.** `PcaLike` is a structural type — `predict`,
+  `getExplainedVariance`, `getEigenvalues`, `getLoadings` — which `ml-pca`'s
+  `PCA` satisfies as it stands, with no adapter and no cast. The package has no
+  runtime dependency on it, and `embeddingResult` is the same door for
+  coordinates from anywhere else.
+- **An outline says what share of a group it holds, not how many standard
+  deviations it is.** In two dimensions those are not the numbers anybody
+  remembers: an ellipse at one standard deviation holds about 39% of the points,
+  not 68%. The picker therefore offers `50% of samples` … `99% of samples`, and
+  the legend writes the same words, so the figure cannot promise a coverage it
+  does not have.
+- **The outline is projected, not rotated.** The two axes almost never carry the
+  same units per pixel, so an ellipse turned by an angle in the data is not
+  turned by that angle on the screen. Handing an SVG `<ellipse>` the data-space
+  angle draws every tilted group slightly wrong and never says so.
+- **A sample the model was built from is filled; one placed into it afterwards is
+  hollow.** `pcaResult(pca, { rows, projected })` appends the second kind and
+  records where they start, because the two are not equally trustworthy: a fitted
+  sample helped choose where the axes point and is bound to land somewhere
+  reasonable, while a projected one can land anywhere — and landing far out is
+  the finding, not a fault.
+- **Colour means one thing per tab and the legend says which.** Groups on the map
+  and the pair grid, components on the other two, drawn from two orders of the
+  Okabe–Ito palette that are disjoint over their first four, so blue-is-setosa on
+  one tab is never blue-is-PC1 on the next. `OverlayLegend` has no default title:
+  a legend that does not name its encoding is how a reader carries the wrong
+  meaning from one tab to the next.
+- **The direction of a component is arbitrary, so it is never a colour.** Sign is
+  carried by geometry — above or below the zero line — and each component is
+  flipped so its strongest measurement comes out positive, because otherwise
+  refitting on one more sample mirrors the whole map and reads as a fault.
+- **Selecting is a drag.** Plain drag replaces the selection, shift adds, alt
+  removes, and the caption says which while the pointer is still down.
+  `onSelectionChange` hands back sample **ids**, so a caller never keeps a second
+  index. Pointer capture, cancellation and lost capture all funnel into one path,
+  which is what stops a lasso being left half-drawn.
+
+### `ProjectionViewer` and the floating options
+
+`PcaViewer` is a thin adapter over `ProjectionViewer`, which draws any
+dimension-reduction result — a k-means run with its centroids, a UMAP embedding,
+coordinates read from a file — from one `ProjectionResult`. The pieces below it
+are meant to be built on:
+
+| Domain           | Holds                                                                                                |
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `src/chart`      | `MatrixLike` read where it stands, linear scales, round ticks, the SVG frame, the tracked line chart |
+| `src/overlay`    | The card of controls that floats over a figure, and the caption, legend and readout that explain one |
+| `src/scatter`    | Lasso selection, hover, confidence ellipses, the plot and the pair grid                              |
+| `src/projection` | The result model, the two adapters, and the viewer                                                   |
+
+The overlay domain is the part most likely to turn up elsewhere. A card rests at
+three quarters strength and wakes when the pointer reaches the figure or the
+keyboard reaches one of its controls; **only its ground fades, never its text**,
+because a label at three quarters over a busy scatter is unreadable exactly when
+it is wanted. One or two controls stay in the strip and everything an expert
+changes lives behind a cog — concealment is the default, and a control is visible
+only because somebody put it there deliberately. Below about 420 pixels the whole
+bar folds into that cog, and the tab order is the same folded or open.
+
+```tsx
+<OverlayLayer width={width} density="compact">
+  <OverlayBar placement={emptiestCorner(points)} more={<Expert />}>
+    <OverlaySelect caption="Across" value={x} options={axes} onChange={setX} />
+  </OverlayBar>
+</OverlayLayer>
+```
+
+### Saving a figure
+
+Every projection viewer carries a save glyph in its bar: a reader picks PNG or
+SVG, picks a resolution, and gets the figure as a file. The panel writes out the
+pixels each resolution would produce, and `fileName` names what arrives — the
+view is appended, so `fileName="ecstasy"` saves `ecstasy-map.png`.
+
+The control behind it is `FigureDownload`, and it is not tied to the viewer: it
+takes the **`id` of the box a figure sits in**, so it can stand in a bar, a
+toolbar or a menu without the component that drew the figure handing anything
+over.
+
+```tsx
+<FigureDownload targetId="pca-figure" fileName="ecstasy-map" />
+<div id="pca-figure">
+  <PcaViewer pca={pca} rows={rows} samples={samples} />
+</div>
+```
+
+Three things it does that a screenshot does not. Everything inside the box is
+saved, so a view that is really sixteen charts arrives as one picture with each
+placed back where the reader saw it. The tokens the figure is drawn from are
+resolved first — a `var(--border)` that left the site would draw a chart with no
+axes. And the chrome floating over the picture is left behind: an `OverlayLayer`
+marks itself, so the cog in the corner never lands in the middle of the scatter.
+
+`downloadFigure(target, options)`, `figureSvg` and `figurePng` are the same thing
+without the button, for a site saving a figure from its own menu.
+
+## Carrying talks
+
+A deck is one Markdown file in the repository of the site whose subject it
+teaches — front matter, slides separated by a `---` line, and a
+`<!-- layout: … -->` comment where the default is not what is wanted. The
+format and the player are `react-cheminfo/slides`; the addresses and the
+authoring rules are in `rules/slideshows.md`.
+
+```tsx
+import { parseTalk, Slideshow } from 'react-cheminfo/slides';
+import 'react-cheminfo/styles/slides.css';
+
+const talk = parseTalk(source);
+
+<Slideshow
+  talk={talk}
+  talkId="20260824_IMSC"
+  index={slide}
+  onIndex={(next) => navigate(`/talks/${id}?slide=${next}`)}
+  layouts={{ octochemdb: OctoChemDbFlow }}
+/>;
+```
+
+The index is **controlled**: the site owns the address, so a link can open one
+slide and a demo link can come back to it. Arrow keys, space and PageUp/Down
+navigate, `Home` and `End` jump, `f` is fullscreen, `b` and `w` blank the
+screen, `n` shows the speaker's notes. A layout name the player does not know
+falls back to `content` rather than breaking a deck in front of a room, and a
+site adds its own through `layouts`.
+
+The `embed` layout puts a **live tool** on the slide — the last bare URL of the
+body is framed — which is what our `?embed` mode exists for.
+
+The format itself is framework-free and is also exported from
+`react-cheminfo/core`, so a backend gathering the family's manifests reads them
+without loading React.
+
+A site that fullscreens its own shell — so a slide can open the live tool and
+come back still presenting — passes `fullscreen={{ isFullscreen, onToggle }}`,
+and the `f` key and the bar's button drive that instead of the player's own
+element.
+
+Publishing a site's decks to the family is one plugin:
+
+```ts
+import { cheminfoTalks } from 'react-cheminfo/vite';
+
+plugins: [cheminfoTalks({ site: 'chemcalc' })];
+```
+
+It writes `dist/talks.json` and `dist/talks/<id>.md`, which is what
+learn.cheminfo.org reads to list and play every site's talks beside its own.
+
 ## Prerendering a site
 
 A static site has no server to rewrite a head per request, so a crawler gets

package/bin/check-tokens.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/*
+ * Report every colour a site writes that belongs to the family rather than to
+ * the site: Blueprint's greys and blues, the family's own token values re-typed
+ * as literals, and a palette declared by hand instead of rendered from
+ * `<SiteTheme siteId>`.
+ *
+ * Wire it as an npm script:
+ *   "check-tokens": "node node_modules/react-cheminfo/bin/check-tokens.mjs src"
+ *
+ * Usage: check-tokens.mjs [directory...] [--allow=#aabbcc,#ddeeff] [--quiet]
+ *   directory   what to walk, `src` when none is given
+ *   --allow     colours the project legitimately owns
+ *   --quiet     say nothing when the scan is clean
+ *
+ * Exits 1 when anything is reported, 2 when it was called wrongly, 0 otherwise.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import process from 'node:process';
+
+import { findTokenViolations } from '../lib/core.js';
+
+const EXTENSIONS = new Set(['.css', '.ts', '.tsx', '.jsx', '.js']);
+const SKIPPED = new Set(['node_modules', 'dist', 'lib', 'coverage']);
+const ALLOW_PREFIX = '--allow=';
+
+const roots = [];
+const allow = [];
+let quiet = false;
+
+for (const argument of process.argv.slice(2)) {
+  if (argument.startsWith(ALLOW_PREFIX)) {
+    for (const colour of argument.slice(ALLOW_PREFIX.length).split(',')) {
+      if (colour.trim() !== '') allow.push(colour.trim());
+    }
+  } else if (argument === '--quiet') {
+    quiet = true;
+  } else if (argument.startsWith('-')) {
+    fail(`unknown option: ${argument}`);
+  } else {
+    roots.push(argument);
+  }
+}
+if (roots.length === 0) roots.push('src');
+
+const files = [];
+for (const root of roots) collect(root, files);
+
+const violations = findTokenViolations(files, { allow });
+let report = '';
+for (const violation of violations) {
+  report += `${violation.file}:${violation.line}:${violation.column}  ${violation.kind}  ${violation.text}  -> ${violation.hint}\n`;
+}
+
+if (violations.length > 0) {
+  report += `${count(violations.length, 'violation')} in ${count(files.length, 'file')}\n`;
+  process.stdout.write(report);
+  process.exit(1);
+}
+if (!quiet) {
+  process.stdout.write(
+    `no token violation in ${count(files.length, 'file')}\n`,
+  );
+}
+
+/**
+ * Add every file worth reading under a path to the list, walking directories
+ * and leaving the generated ones alone.
+ * @param {string} path - A file or a directory.
+ * @param {Array<{ path: string, text: string }>} files - Collected so far.
+ */
+function collect(path, files) {
+  const stats = statSync(path, { throwIfNoEntry: false });
+  if (stats === undefined) fail(`no such path: ${path}`);
+  if (stats.isDirectory()) {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || SKIPPED.has(entry.name)) continue;
+      collect(join(path, entry.name), files);
+    }
+    return;
+  }
+  if (!EXTENSIONS.has(extname(path))) return;
+  files.push({ path, text: readFileSync(path, 'utf8') });
+}
+
+/**
+ * A count with its noun, so a summary line reads as a sentence.
+ * @param {number} total - How many.
+ * @param {string} noun - What of, in the singular.
+ * @returns {string} The two, with the plural `s` when it is needed.
+ */
+function count(total, noun) {
+  return `${total} ${noun}${total === 1 ? '' : 's'}`;
+}
+
+/**
+ * Stop on a call the script cannot honour, which is not a clean scan.
+ * @param {string} message - What was wrong with it.
+ * @returns {never} It never comes back: the process ends here.
+ */
+function fail(message) {
+  process.stderr.write(`check-tokens: ${message}\n`);
+  process.exit(2);
+}

package/lib/about/core/about.d.ts

@@ -0,0 +1,95 @@
+import type { CitedWork } from '../../citation/core/works.ts';
+import type { CreditEntry, CreditId } from '../../credits/core/credits.ts';
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+/**
+ * What a site says about itself: the one page a visitor opens to find out what
+ * the tool is, what it stands on, and who to tell when it breaks.
+ *
+ * Every field is content, never markup. A site writes this record and the page
+ * is drawn from it, which is what keeps fourteen About pages in one order and
+ * one voice — the shape they were in before was fourteen hand-written pages,
+ * each crediting a different half of what it runs on.
+ */
+export interface AboutContent {
+    /** The site the page belongs to. */
+    siteId: SiteId;
+    /** One sentence: what this tool is. */
+    what: string;
+    /**
+     * At most two short paragraphs of context — what the site replaces, where
+     * its numbers come from, what it deliberately does not do.
+     * @default undefined
+     */
+    paragraphs?: readonly string[];
+    /** Three to six one-line entries: what a visitor can do here. */
+    can: readonly string[];
+    /** Ids into the shared credits registry, in display order. */
+    credits: readonly CreditId[];
+    /**
+     * Works to cite, from the citation module.
+     * @default undefined — the site asks for no citation of its own
+     */
+    cite?: readonly CitedWork[];
+    /**
+     * Licence the site itself is published under.
+     * @default 'MIT'
+     */
+    license?: string;
+    /**
+     * Where the sources live.
+     * @default the repository of the ECOSYSTEM_SITES record
+     */
+    repository?: string;
+    /**
+     * The running version, when the site knows it.
+     * @default undefined
+     */
+    version?: string;
+    /**
+     * Where a problem is reported.
+     * @default the repository's /issues
+     */
+    issues?: string;
+}
+/**
+ * The same record with nothing left to look up: every default filled in, and
+ * every credit id replaced by the entry it names.
+ */
+export interface ResolvedAbout {
+    /** The site's own record, which carries its name, tagline and colours. */
+    site: EcosystemSite;
+    what: string;
+    /** The context paragraphs, empty when the site writes none. */
+    paragraphs: readonly string[];
+    can: readonly string[];
+    /** The borrowed works themselves, in the order the site names them. */
+    credits: CreditEntry[];
+    /** The works to cite, empty when the site asks for none. */
+    cite: readonly CitedWork[];
+    license: string;
+    repository: string;
+    /** The running version, or `undefined` when the site does not know it. */
+    version: string | undefined;
+    issues: string;
+}
+/**
+ * Fill in what a site left to the family, and resolve what it named.
+ * @param content - What the site wrote about itself.
+ * @returns The record the About page is drawn from.
+ * @throws {Error} When the site is not one of the family, or when a credit id
+ *   is not in the registry: an About page that silently drops a borrowed work
+ *   credits nobody.
+ */
+export declare function resolveAbout(content: AboutContent): ResolvedAbout;
+/**
+ * What is wrong with a record before anyone reads the page it draws.
+ *
+ * Short and efficient prose is the house style, and prose is exactly what no
+ * test, lint rule or type ever checks: a `what` that runs to a paragraph and a
+ * `can` list of a dozen lines both compile. This is where that is caught, so a
+ * site can assert it in its own suite rather than discover it in review.
+ * @param content - What the site wrote about itself.
+ * @returns One line per problem, in reading order; empty when there is none.
+ */
+export declare function aboutProblems(content: AboutContent): string[];
+//# sourceMappingURL=about.d.ts.map

package/lib/about/core/about.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"about.d.ts","sourceRoot":"","sources":["../../../src/about/core/about.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAE3E;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,iEAAiE;IACjE,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,8DAA8D;IAC9D,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC7B;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,4DAA4D;IAC5D,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAgBjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CA8C7D"}

package/lib/about/core/about.js

@@ -0,0 +1,78 @@
+import { credits } from "../../credits/core/credits.js";
+import { siteById } from "../../ecosystem/core/lookup.js";
+/**
+ * Fill in what a site left to the family, and resolve what it named.
+ * @param content - What the site wrote about itself.
+ * @returns The record the About page is drawn from.
+ * @throws {Error} When the site is not one of the family, or when a credit id
+ *   is not in the registry: an About page that silently drops a borrowed work
+ *   credits nobody.
+ */
+export function resolveAbout(content) {
+    const site = siteById(content.siteId);
+    const repository = content.repository ?? site.repository;
+    return {
+        site,
+        what: content.what,
+        paragraphs: content.paragraphs ?? [],
+        can: content.can,
+        credits: credits(content.credits),
+        cite: content.cite ?? [],
+        license: content.license ?? DEFAULT_LICENSE,
+        repository,
+        version: content.version,
+        issues: content.issues ?? `${withoutTrailingSlash(repository)}/issues`,
+    };
+}
+/**
+ * What is wrong with a record before anyone reads the page it draws.
+ *
+ * Short and efficient prose is the house style, and prose is exactly what no
+ * test, lint rule or type ever checks: a `what` that runs to a paragraph and a
+ * `can` list of a dozen lines both compile. This is where that is caught, so a
+ * site can assert it in its own suite rather than discover it in review.
+ * @param content - What the site wrote about itself.
+ * @returns One line per problem, in reading order; empty when there is none.
+ */
+export function aboutProblems(content) {
+    const problems = [];
+    if (content.what.length > WHAT_LIMIT) {
+        problems.push(`\`what\` is ${content.what.length} characters: one sentence of at most ${WHAT_LIMIT} says what the tool is.`);
+    }
+    const can = content.can;
+    if (can.length < CAN_MIN || can.length > CAN_MAX) {
+        problems.push(`\`can\` lists ${can.length} entries: between ${CAN_MIN} and ${CAN_MAX} is what a visitor reads before deciding to stay.`);
+    }
+    for (let index = 0; index < can.length; index++) {
+        const line = can[index] ?? '';
+        if (line.length > CAN_LINE_LIMIT) {
+            problems.push(`\`can\` entry ${index + 1} is ${line.length} characters: one line of at most ${CAN_LINE_LIMIT}, not a sentence about it.`);
+        }
+    }
+    const paragraphs = content.paragraphs ?? [];
+    if (paragraphs.length > PARAGRAPH_MAX) {
+        problems.push(`\`paragraphs\` holds ${paragraphs.length}: at most ${PARAGRAPH_MAX} short paragraphs of context, and the rest belongs in the README.`);
+    }
+    for (let index = 0; index < paragraphs.length; index++) {
+        const paragraph = paragraphs[index] ?? '';
+        if (paragraph.length > PARAGRAPH_LIMIT) {
+            problems.push(`paragraph ${index + 1} is ${paragraph.length} characters: at most ${PARAGRAPH_LIMIT}, or it is documentation rather than context.`);
+        }
+    }
+    if (content.credits.length === 0) {
+        problems.push('`credits` is empty: every page of ours stands on borrowed work, and naming it is what the section is for.');
+    }
+    return problems;
+}
+/** What a site is published under unless it says otherwise. */
+const DEFAULT_LICENSE = 'MIT';
+const WHAT_LIMIT = 160;
+const CAN_MIN = 3;
+const CAN_MAX = 6;
+const CAN_LINE_LIMIT = 90;
+const PARAGRAPH_MAX = 2;
+const PARAGRAPH_LIMIT = 400;
+function withoutTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+//# sourceMappingURL=about.js.map