react-cheminfo 0.64.1 → 0.66.0

package/README.md

@@ -33,10 +33,12 @@ only when it drags a heavy dependency behind it.
 | Import                             | Holds                                                 | Costs                                            |
 | ---------------------------------- | ----------------------------------------------------- | ------------------------------------------------ |
 | `react-cheminfo/core`              | every framework-free helper — 140 value exports       | nothing                                          |
+| `react-cheminfo/formula`           | formulas: read, compared, drawn and copied            | mf-parser, react-mf; React on the components     |
 | `react-cheminfo/ui`                | every React component and hook — 60 value exports     | React                                            |
 | `react-cheminfo/vite`              | the prerender plugin and the OG card                  | nothing; React on the card                       |
 | `react-cheminfo/pages`             | the Cloudflare Pages analytics middleware             | nothing                                          |
 | `react-cheminfo/server`            | the prerendered build, served from Node               | fastify, @fastify/static; Node only              |
+| `react-cheminfo/card`              | the card an answer is shown as in a chat              | React; cheminfo-mcp-server, an optional peer     |
 | `react-cheminfo/orbital`           | the 3D atomic-orbital viewer                          | React, molstar                                   |
 | `react-cheminfo/molecule3d`        | the 3D molecule viewer and its toolbar                | React, molstar                                   |
 | `react-cheminfo/structure`         | the structure editor and renderer                     | React, react-ocl, OCL                            |
@@ -44,11 +46,13 @@ only when it drags a heavy dependency behind it.
 | `react-cheminfo/slides`            | the deck format and the slideshow player              | React, react-markdown                            |
 | `react-cheminfo/spectra`           | the spectra processing settings editors               | React; types only from spectra-processor, ml-pca |
 | `react-cheminfo/ir`                | the infrared chart, band table and editor             | React, ir-spectrum, convert-to-jcamp             |
+| `react-cheminfo/raman`             | the Raman editor: the infrared one, read for Raman    | the same as `react-cheminfo/ir`                  |
 | `react-cheminfo/xtb`               | GFN2-xTB as a geometry relaxer                        | nothing on import; xtb-wasm on the first call    |
 | `react-cheminfo/host`              | data handed over by a page that frames the tool       | nothing on import; ajv once the page is framed   |
 | `react-cheminfo/host-testing`      | a stand-in host and SciPeaks' messages, for e2e tests | nothing; Node only                               |
 | `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                                          |
+| `react-cheminfo/styles/card.css`   | the card’s stylesheet, on the family’s tokens         | 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
@@ -65,11 +69,15 @@ module scope: a site that never imports that door bundles none of it.
 usual reason: reading a spectrum drags the formats one may arrive in —
 `ir-spectrum` for the band correlations and the absorbance/transmittance pair,
 `convert-to-jcamp` for writing them back out, and a JCAMP or SPC reader fetched
-only once the bytes turn out to need it. The chart it is drawn with is **not**
-behind that door: scales, ticks, plot geometry, the zoom gestures, the label
-placement and the panel chrome are in `core` and `ui`, because a spectrum of any
-kind is drawn with them and the next viewer built on them should find them
-already there rather than reach through an infrared package for them.
+only once the bytes turn out to need it. `react-cheminfo/raman` opens the same
+viewer for Raman spectra — one value axis, the Raman shift running left to
+right, the bands picked on intensity and no correlation table — so a page
+imports each technique's viewer by name while both share one shell. The chart
+it is drawn with is **not** behind that door: scales, ticks, plot geometry, the
+zoom gestures, the label placement and the panel chrome are in `core` and `ui`,
+because a spectrum of any kind is drawn with them and the next viewer built on
+them should find them already there rather than reach through an infrared
+package for them.
 
 `react-cheminfo/xtb` is the door a page opens only when a visitor asks for a
 better number. `refineConformers` in
@@ -100,16 +108,21 @@ through a wildcard subpath exactly as `react-science` serves its own.
 | **Routing & head**         | `createTabRouter`, `readRoute`, `writeRoute`, `subscribeToRoute`, `adoptLegacyHashAddress`, `writeDocumentMeta`, `pageLocation`, `pageHistory`                                                                                                                                                                                         | `useTabRoute`                                                                                                                                                                                                                                                                                       |
 | **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`                                                                                                                                                    |
+| **Graded series**          | `pickSeeded`, `freshSeed`, `parseSeed`, `seedParam`, `createAttemptStore`, `createProgressController`, `readAnswerNumber`, `emptyCase`, `unreadableCase`                                                                                                                                                                               | `ExerciseSeries`, `QuestionCard`, `AnswerFields`, `ExerciseList`, `useAttemptRecords`                                                                                                                                                                                                               |
+| **Formulas**               | `readFormula`, `normalizeFormula`, `canonicalFormula`, `atomCounts`, `formulaHtml`, `formulaText` (all `/formula`)                                                                                                                                                                                                                     | `CopyableFormula`, `QuestionFormula`, `FormulaInput` (all `/formula`)                                                                                                                                                                                                                               |
+| **Site shell**             | `pageContentOf`; the `pages` option of `cheminfoPrerender` (`/vite`)                                                                                                                                                                                                                                                                   | `SiteShell`, `ShareControl`                                                                                                                                                                                                                                                                         |
+| **Properties**             | `copyableText`                                                                                                                                                                                                                                                                                                                         | `PropertyTable`                                                                                                                                                                                                                                                                                     |
 | **Clipboard & files**      | `writeToClipboard`, `downloadBlob`, `downloadText`, `sanitizeFileName`, `toDelimited`, `readDelimited`, `downloadFigure`, `figureSvg`, `figurePng`, `figureSize`                                                                                                                                                                       | `ClickToCopy`, `CopyButton`, `CopyableValue`, `CodeBlock`, `DelimitedTextDialog`, `FigureDownload`                                                                                                                                                                                                  |
 | **Formatting & colour**    | `formatInteger`, `formatDecimal`, `formatBytes`, `pluralize`, `readableInk`, `contrastRatio`, `COLOR_SCALES`, `resolveColorScale`, `formatColorScale`, `colorAt`, `swatchAt`, `sampleScale`, `colorScaleGradient`, `rgbToHsv`                                                                                                          | `ColorScaleLegend`, `ColorScaleSelect`, `ColorScaleEditor`, `ColorScaleBar`                                                                                                                                                                                                                         |
 | **Number entry**           | `readNumber`, `numberText`, `isPartialNumber`, `stepNumber`, `snapToStep`                                                                                                                                                                                                                                                              | `NumberInput`                                                                                                                                                                                                                                                                                       |
 | **Range filter**           | `isRangeBounded`, `isRangeDomain`, `rangeHandles`, `movedRange`, `settleHandles`, `sameRange`, `rangeHistogramPath`, `OPEN_RANGE`                                                                                                                                                                                                      | `RangeSlider`                                                                                                                                                                                                                                                                                       |
 | **Widgets**                | `CREDITS`, `credits`                                                                                                                                                                                                                                                                                                                   | `ErrorBoundary`, `CollapsibleSection`, `CapsuleFilter`, `HelpTooltip`, `CreditsList`                                                                                                                                                                                                                |
 | **Hooks & state**          | `createWorkerChannel`, `persistBucket`, `persistSignalBucket`                                                                                                                                                                                                                                                                          | `useDebouncedValue`, `useContainerSize`, `useListKeyboardNavigation`, `useDisclosure`                                                                                                                                                                                                               |
+| **Requests**               | `fetchJson`, `ApiError`, `readApiError`, `keySetParam`, `readHiddenParts`, `formatHiddenParts`, `fitDescription`, `DESCRIPTION_MIN`, `DESCRIPTION_MAX`, `openingRoute`, `anchorHref`                                                                                                                                                   | `useAsync` (signal, `pending`)                                                                                                                                                                                                                                                                      |
 | **Chemistry**              | `atomicOrbitalsOf`, `configurationOf`, `classifyMolfile`, `readStructure`, `toMolfileExport`                                                                                                                                                                                                                                           | `AtomicOrbitalViewer` (`/orbital`), `StructureEditor`, `Structure` (`/structure`)                                                                                                                                                                                                                   |
 | **Conformers**             | `generateConformers`, `continueConformers`, `refineConformers`, `conformerShape`, `isSameMinimum`, `rankByEnergy`, `minimiseConformer`, `DEFAULT_CONFORMER_OPTIONS`, `CONFORMER_STRATEGIES` (all `/conformers`); `GeometryRelaxer`, `readRelaxableGeometry`, `centredRmsd`                                                             | —                                                                                                                                                                                                                                                                                                   |
 | **Spectrum charts**        | `chartScale`, `chartAxisScale`, `plotRect`, `zoomDomain`, `zoomSelection`, `labelStackBaselines`, `layoutAnnotationBoxes`, `profilePath`, `stickPath`, `guidePlacement`, `readoutPlacement`, `stackCapacity`, `nextSpectrumColor`, `panelStyles`, `statusBar`                                                                          | `Axes`, `AxisGuide`, `ChartTracker`, `ChartStack`, `SelectionRect`, `TraceLegend`, `PlotCaption`, `useChartZoom`, `useChartPointer`, `useChartSize`, `SidePanelStack`, `PanelRail`, `Section`, `FilterInput`, `AboutDialogFrame`, `DocumentationDialogFrame`, `FigureDownload`, `useFigureDownload` |
-| **Infrared**               | `loadIrSpectra`, `toIrSpectrum`, `pickBands`, `assignBands`, `BAND_ASSIGNMENTS`, `irSpectrumToJcamp`, `IR_MODE_RULES`, `nearestBandAt`, `planBandLabels`, `irReducer` (all `/ir`)                                                                                                                                                      | `IrEditor`, `IrChart`, `BandsPanel`, `SpectraPanel`, `MetadataPanel`, `useIrEditor` (all `/ir`)                                                                                                                                                                                                     |
+| **Infrared and Raman**     | `loadIrSpectra`, `toIrSpectrum`, `pickBands`, `assignBands`, `BAND_ASSIGNMENTS`, `irSpectrumToJcamp`, `IR_MODE_RULES`, `IR_TECHNIQUE_RULES`, `nearestBandAt`, `planBandLabels`, `irReducer` (all `/ir`)                                                                                                                                | `IrEditor`, `IrChart`, `BandsPanel`, `SpectraPanel`, `MetadataPanel`, `useIrEditor` (all `/ir`); `RamanEditor` (`/raman`)                                                                                                                                                                           |
 | **Spectra**                | `FILTER_CATALOG`, `filterMenu`, `settingsProblems`, `normalizationFilters`, `addFilter`, `moveFilter`, `setFilterOption`, `principalComponentChoices`, `clampPrincipalComponents`, `EMPTY_SETTINGS` (all `/spectra`)                                                                                                                   | `SpectraSettingsEditor`, `FilterChainEditor`, `PrincipalComponentSelect` (all `/spectra`)                                                                                                                                                                                                           |
 | **About**                  | `resolveAbout`, `aboutProblems`                                                                                                                                                                                                                                                                                                        | `AboutPage`                                                                                                                                                                                                                                                                                         |
 | **Which build is running** | `formatBuiltAt`, `shortCommit`, `BuildInfo`                                                                                                                                                                                                                                                                                            | `AboutVersion`, `cheminfoBuildInfo` (`/vite`)                                                                                                                                                                                                                                                       |
@@ -121,6 +134,7 @@ through a wildcard subpath exactly as `react-science` serves its own.
 | **Periodic table**         | `PERIODIC_ELEMENTS`, `elementBySymbol`, `elementByAtomicNumber`, `cellOf`, `placedElements`, `elementByArrowKey`, `EMPTY_BLOCK`, `categorySwatch`, `CATEGORY_LABELS`                                                                                                                                                                   | `PeriodicTable`, `ElementCell`, `CategoryLegend`                                                                                                                                                                                                                                                    |
 | **Taxonomy**               | `TAXON_RANKS`, `PRINCIPAL_RANKS`, `rankOrder`, `isPrincipalRank`, `isGenusOrBelow`, `isAboveGenus`, `principalLineage`, `lineageFromNodes`, `lineageFromRanks`, `genusOrBelow`, `ncbiTaxonomyUrl`, `splitOrganismName`                                                                                                                 | `TaxonLineage`, `OrganismName`, `useRankLabel`                                                                                                                                                                                                                                                      |
 | **Framed by a host**       | `hostStructureLoader`, `readHostMolecule`, `STRUCTURE_KINDS`, `connectHost`, `selectInputs`, `checkValue`, `kindAccepts`, `parseRequest` (all `/host`); `startStandInHost`, `SCIPEAKS_ETHYLBENZENE_LOAD` (`/host-testing`)                                                                                                             | `useHostConnection` (`/host`)                                                                                                                                                                                                                                                                       |
+| **Answer cards**           | `CARD_PARAM`, `isCardAddress`, `sitePageUrl`, `cardPageUrl`, `framedPageUrl`, `roomForPanels`; `answerAddresses`, `joinAddress`, `viewOrigins`, `cardMeta`, `pageAnswer`, `siteView` (all `/server`)                                                                                                                                   | `CardFrame`, `CardDetailsButton`, `CardFigure`, `CopyTableButton`, `fitCardToFrame`, `useFitCardToFrame`, `useOverlayRoom`, `holdRoomForPanels` (all `/card`); `StructureExportButton`, `useStructureDraft` (`/structure`)                                                                          |
 
 Everything in that table is exported from `./core`, `./ui`, `./slides`,
 `./vite` or `./structure` and nothing else is: the sub-components a component is built
@@ -854,6 +868,60 @@ const included = useMemo(
   subject — a formula through `react-mf`, a structure, a name — and a readout of
   strings cannot hold any of that.
 
+## A graded series, and the shell around it
+
+A pedagogic site that asks a series of questions writes its pool and its
+grader, and nothing else. `SeriesTool` describes them; `ExerciseSeries` draws
+the list beside the open question, the progress over the series, the length
+picker and the new-series button. It reads no address: the page hands it the
+seed, the length and the share of the row, and is told when one changes.
+
+```tsx
+import { createAttemptStore, parseSeed } from 'react-cheminfo/core';
+import { ExerciseSeries } from 'react-cheminfo/ui';
+
+const ATTEMPTS = createAttemptStore({ key: 'atoms' }); // atoms:attempts:v1
+
+<ExerciseSeries
+  tool={ELECTRONS}
+  store={ATTEMPTS}
+  label={(ion) => <QuestionFormula formula={ion.formula} />}
+  prompt={(ion) => <p>How many electrons has {ion.name}?</p>}
+  seed={parseSeed(route.params.seed)}
+  onSeed={(seed, history) => writeSeed(tab, seed, history)}
+  count={questionCount}
+  onCount={setQuestionCount}
+  split={SERIES_SPLIT.parse(route.params.split ?? null)}
+  onSplit={(split) => writeSplit(tab, split)}
+/>;
+```
+
+`pickSeeded` draws the series. Its `draw` option names the generator call a
+site's links were written with — `getFloat` for atoms, inorganic and moles,
+`getUint32` with `wrap` for dbe — so every `?seed=` already handed out opens
+the same questions. `seedParam` reads a seed a link pins, and `?seed=each` for
+one series per student. `createProgressController(signal)` is the handful of
+actions an exercise page performs on progress kept in a signal.
+
+Formulas come from their own door, because they are read by `mf-parser` and
+drawn by `react-mf`: `readFormula` reads `NO3-`, `SO4--` and `CuSO4.5H2O` the
+way a student types them, which the parser alone reads as neutral or as a
+decimal; `CopyableFormula` copies a formula as text and as HTML, so a paste
+keeps its subscripts.
+
+`SiteShell` is the chrome around a page: the theme, the bar with About · Cite ·
+Tools · Contact · Share, the page, and the footer, with nothing but the page
+under `?embed`. A site fills the slots between the shared entries
+(`actionsAfterAbout`, `actionsAfterCite`, `actions`, `language`, `account`) and
+never re-orders them. Given the site's router, it marks the tab on show and
+serves the About tab as `AboutPage`. Its `share` takes what `ShareControl`
+takes — the Share entry and its dialog in one, which is also what a header's
+own `share` prop takes.
+
+A prerendered site that writes text for a few of its pages passes them as
+`pages` to `cheminfoPrerender`; every other address then says the name and the
+sentence its route is indexed under.
+
 ## Framed by a notebook
 
 A page that frames a tool — an electronic lab notebook such as SciPeaks, a
@@ -1016,6 +1084,39 @@ Still English, with the runtime in place and no catalog yet: the spectra
 settings editor and the projection panels (`react-cheminfo/spectra`, the
 projection viewers), which no site of the family reads in a second language yet.
 
+## Routing a translated site
+
+A router given `languages` reads the language off the prefix and writes it
+back, English bare, so the share vocabulary, the query and the mount stay where
+they were:
+
+```ts
+const router = createTabRouter<Tab>({
+  tabs: ['generator', 'exercises'],
+  home: 'generator',
+  languages: ['en', 'fr', 'de'],
+});
+
+router.parse('/fr/exercises?embed'); // { tab: 'exercises', language: 'fr', … }
+router.format({ tab: 'exercises', language: 'de' }); // '/de/exercises'
+```
+
+`readRoute` moves a `?lang=` a sibling handed over into the path, once, in
+place; a prefix the address already carries always wins, so a deep link is
+never steered. `openingRoute(router, preferred)` opens a bare `/` in the
+language the reader last chose, and nothing else. `writeRoute` keeps the
+language on screen when the route names none.
+
+Beside it: `persistSignalBucket` takes `legacyKeys` (adopted once, through a
+`migrate` when the shape changed) and `syncAcrossTabs`; `createSiteAddresses`
+answers `anchorHref` and `storedAssetSrc`; a vocabulary takes
+`legacyEmbedParts`, so `?hide=header` still opens framed; `keySetParam` writes
+`?flags=` with `none` for the empty set; `createWorkerChannel` takes a
+`failure` hook, `retryAfterWorkerFailure`, and runs in-process when a browser
+refuses the worker; `oclResourcesUrl()` comes from `./conformers`, and
+`resetCamera`, `focusPoint`, `sceneSphere` and `subscribeHoverLabel` from
+`./molstar/core`.
+
 ## Carrying talks
 
 A deck is one Markdown file in the repository of the site whose subject it
@@ -1253,6 +1354,192 @@ answers its own 404. Without a build, `staticSite` logs it and serves the API
 alone. `fastify` (5) and `@fastify/static` (10) are optional peers, installed
 by a site that has a server.
 
+`basePath` (`BASE_PATH`) serves one image at a mount chosen at startup, behind a
+proxy that takes the path off: it is written into the `<base href="/">` of every
+page when the build is read, and in front of every redirect.
+
+### A tool site's server, from its environment
+
+A site that serves its tools beside its pages has nothing of its own to write
+but the tools. `readServerConfig` reads the environment once and refuses a
+malformed value; `toolSiteServer` builds Fastify, registers the API the site
+passes, then `staticSite`; `startToolServer` listens and closes on `SIGTERM`
+and `SIGINT`, setting `process.exitCode = 1` when a close fails.
+
+```ts
+// server/main.ts
+import { join } from 'node:path';
+
+import {
+  readServerConfig,
+  startToolServer,
+  toolSiteServer,
+} from 'react-cheminfo/server';
+
+const config = readServerConfig(process.env, {
+  siteId: 'osiris',
+  port: 10_620,
+  root: join(import.meta.dirname, '../dist'),
+});
+
+await startToolServer(
+  (settings) =>
+    toolSiteServer({
+      siteId: 'osiris',
+      config: settings,
+      // name: 'osiris.cheminfo.org', version: the repository root's release
+      registerApi: (app, { name, version }) =>
+        registerTools(app, name, version),
+    }),
+  config,
+);
+```
+
+| Variable          | Read as                                                             | Default                      |
+| ----------------- | ------------------------------------------------------------------- | ---------------------------- |
+| `PORT`            | an integer from 1 to 65535                                          | the site's own port          |
+| `HOST`            | the interface listened on                                           | `0.0.0.0`                    |
+| `TRACKING_SCRIPT` | the analytics snippet, verbatim                                     | nothing loaded               |
+| `SITE_URL`        | the address answers link to, path kept, ending in `/`               | the site's own address       |
+| `PUBLIC_URL`      | this server's address, which a chat frames, ending in `/`           | `http://localhost:<PORT>/`   |
+| `TRUST_PROXY`     | an address, a CIDR, a list of either, or `true`; a hop count throws | `false`                      |
+| `SERVER_ROOT`     | the build served                                                    | the `root` option, or `dist` |
+| `BASE_PATH`       | the mount, behind a proxy that takes it off                         | none                         |
+
+The pieces are exported on their own for a backend that is not a tool site:
+`parseTrustProxy`, `readEnvNumber` (blank is unset, a malformed value throws),
+`readHttpAddress`, `readRepositoryVersion` (the root `package.json`, found as
+`cheminfoBuildInfo` finds it), `healthRoute` (`GET /health`, silent),
+`listenSite` (listen, and close on a signal, then run `onClose`), and the
+type-only `FastifyTyped` (`@fastify/type-provider-typebox` is an optional peer).
+
+### A single-page app, served by its backend
+
+A backend that serves a Vite single-page app answers every address the app
+routes with the built page, under the head of that address and a crawl path of
+its own. `spaSite` does that, and writes `sitemap.xml` and `robots.txt` from the
+route table at the address the site is served at; serves the build's files, with
+`assets/` kept for a year; leaves `/v1/` and `/docs` to the API; and answers
+`/health`.
+
+```ts
+await app.register(spaSite, {
+  root: join(import.meta.dirname, '../../frontend/dist'),
+  site: 'wikidata',
+  siteUrl: process.env.SITE_URL, // blank: the origin the request arrived on
+  trackingScript: process.env.TRACKING_SCRIPT,
+  noscript: { heading: 'wikidata.cheminfo.org', hrefs: 'relative' },
+  // A compound under its own name; undefined falls back to the table.
+  page: (url) => compoundPage(db, url),
+  sitemapPaths: () => db.pageIds().map((id) => `/compound/${id}`),
+});
+```
+
+The route table is the one the app reads, written beside the page at build time
+by `cheminfoRouteTable` from `react-cheminfo/vite`, which also runs
+`assertRoutes` when the build starts; `readRouteTable(root, fallback)` reads it
+back. `notFoundStatus: 404` with `knownRoute` answers an address the app does not
+route with a real 404, `structuredData` takes a function writing the whole block,
+and `indexed: false` keeps an admin site out of every index.
+
+```ts
+// frontend/vite.config.ts
+plugins: [react(), cheminfoRouteTable({ routes: ROUTES })],
+```
+
+### Writing to molecules.cheminfo.org
+
+`createMoleculesClient` from `react-cheminfo/core` is the client a site writes
+its source through: `startImport`, `importState`, `submit`, `lookup` and
+`purge`, each attempt with its own deadline, retried on 429, 502, 503, 504 or no
+answer with doubling, spread pauses that honour `Retry-After`, bodies gzipped.
+It reads no Node module.
+
+```ts
+const molecules = createMoleculesClient({
+  baseUrl: 'https://molecules.cheminfo.org',
+  token: process.env.MOLECULES_TOKEN_LOTUS,
+  onRetry: (details) =>
+    logger.warn(details, 'molecules.cheminfo.org: retrying'),
+});
+const { importKey } = await molecules.startImport();
+```
+
+## Answers shown in a chat
+
+A site's tool server answers mcp.cheminfo.org with a link to the page people
+share and a card: the same page on this server under `?embed=1&card=1`, which
+the chat frames inline, and the page itself over the full screen. The card and
+the page read the same parameters, so they never disagree about what was
+asked.
+
+The server writes both addresses with `react-cheminfo/server`. `siteUrl` and
+`publicUrl` may be an origin or an origin and a mount, with or without a
+trailing slash, and a page is named from the site's own root: every helper
+joins them with exactly one slash.
+
+```ts
+import {
+  answerAddresses,
+  cardMeta,
+  pageAnswer,
+  siteView,
+} from 'react-cheminfo/server';
+
+const addresses = answerAddresses({ siteUrl, publicUrl });
+// { link: 'https://equilibrium.cheminfo.org/titration?ind=thymol', meta }
+const answer = pageAnswer(addresses, '/titration', { ind: 'thymol' });
+// A query written by the site's own codec, and what only the card reads.
+const meta = cardMeta(addresses, `/?${libraryQuery}`, {
+  hide: ['editor'],
+  extra: { rows: '10' },
+});
+const view = siteView({ uri: 'ui://vcl/page', name, description, addresses });
+```
+
+A card address longer than `maxLength` (8000) is not carried: `meta` is then
+undefined and the chat draws the answer itself, while `link` still names the
+page. These helpers are built on `embedMeta` and `embedView`, so
+`cheminfo-mcp-server` (an optional peer) is installed by a site that imports
+`react-cheminfo/server`. The addresses alone — `CARD_PARAM`, `sitePageUrl`,
+`cardPageUrl`, `framedPageUrl` — are in `react-cheminfo/core`, for the page.
+
+The card itself is drawn with `react-cheminfo/card` and
+`react-cheminfo/styles/card.css`:
+
+```tsx
+import 'react-cheminfo/styles/card.css';
+import {
+  CardDetailsButton,
+  CardFigure,
+  CardFrame,
+  CopyTableButton,
+} from 'react-cheminfo/card';
+import { StructureExportButton } from 'react-cheminfo/structure';
+
+<CardFrame>
+  <p className="card__header card__title">pH 8.72 at equivalence</p>
+  <CardFigure
+    fileName="titration"
+    tools={<StructureExportButton smiles={smiles} />}
+  >
+    <TitrationChart />
+  </CardFigure>
+  <div className="card__end">
+    <CopyTableButton table={() => toDelimited(rows)} />
+    <CardDetailsButton address={{ cardParams: ['scale', 'ph'] }} />
+  </div>
+</CardFrame>;
+```
+
+`CardFrame` reports the card's height to the frame and grows the card while a
+dialog or a popover it opened is open, so the frame holds it — only when the
+page is framed. A card that keeps its own root uses `ref={fitCardToFrame}`, or
+`useFitCardToFrame(ref)`. `CardDetailsButton` opens the card's address without
+`card`, `embed`, `hide` and the parameters only the card reads, in a new tab
+when framed and in place otherwise. Their words come from the chrome's
+catalog, in the language of the page.
+
 ## Saying which build is running
 
 A report of something going wrong is worth answering only when we know what was

package/lib/card/core/cardAddress.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The card of an answer, as its address says it.
+ *
+ * A chat shows a tool's answer twice: inline, as a card drawing only what the
+ * question asked, and over the full screen, as the site's page. The card is
+ * that page with `card` in its query, always with `embed`, so the card and
+ * the page behind it read the same parameters and can never disagree about
+ * what was asked. `card` is read by its presence: `?card` and `?card=1` both
+ * ask for it.
+ *
+ * Pure string work: the page reads these addresses, and the tool server
+ * writes them, in Node.
+ */
+/** The parameter asking for the answer's card instead of the page. */
+export declare const CARD_PARAM = "card";
+/**
+ * Whether an address asks for a card.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns True when it names `card`, with a value or bare.
+ */
+export declare function isCardAddress(search: string): boolean;
+/**
+ * The address a card is at: `globalThis.location`, a `URL`, or any record of
+ * the three parts.
+ */
+export interface CardLocation {
+    /** Its origin, e.g. `https://equilibrium.cheminfo.org`. */
+    readonly origin: string;
+    /** Its path, the mount and a language prefix included. */
+    readonly pathname: string;
+    /** Its query string, with or without its `?`. */
+    readonly search: string;
+}
+/** How {@link sitePageUrl} tells the card's parameters from the page's. */
+export interface SitePageOptions {
+    /**
+     * The parameters only the site's card reads, beside `card` itself: what a
+     * card draws beyond the page, e.g. `['rows']`, `['scale', 'ph']`.
+     * @default []
+     */
+    cardParams?: readonly string[];
+    /**
+     * Read a `+` in a key as a plus rather than as a space, as
+     * `parseQueryEntries` does. A key carries no `+` on any site of the family,
+     * so this only matters to a site that writes its own addresses with
+     * `URLSearchParams`.
+     * @default true
+     */
+    literalPlus?: boolean;
+    /**
+     * A parameter the page at a given path does not read, though another page
+     * of the site does: a tutorial step reads no InChI, the converter does.
+     * @default undefined - nothing beyond `card`, `embed`, `hide` and
+     *   `cardParams` is left out
+     */
+    isCardOnly?: (key: string, pathname: string) => boolean;
+}
+/**
+ * The site's own page a card stands for, with its chrome: the card's address
+ * without `card`, `embed`, `hide` and what only the card reads. Every other
+ * parameter is kept exactly as it was written, so the `+` of a charged atom
+ * stays a plus and the commas of a list stay commas. This is the address an
+ * answer's `link` names, and the one the card's Details button opens.
+ * @param location - The card's address: `globalThis.location`, or
+ *   `new URL(href)` for an address held as text.
+ * @param options - What only the site's card reads.
+ * @returns The page's absolute address, without a fragment.
+ */
+export declare function sitePageUrl(location: CardLocation, options?: SitePageOptions): string;
+//# sourceMappingURL=cardAddress.d.ts.map

package/lib/card/core/cardAddress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardAddress.d.ts","sourceRoot":"","sources":["../../../src/card/core/cardAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,sEAAsE;AACtE,eAAO,MAAM,UAAU,SAAS,CAAC;AAEjC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAKrD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAeR"}

package/lib/card/core/cardAddress.js

@@ -0,0 +1,59 @@
+/**
+ * The card of an answer, as its address says it.
+ *
+ * A chat shows a tool's answer twice: inline, as a card drawing only what the
+ * question asked, and over the full screen, as the site's page. The card is
+ * that page with `card` in its query, always with `embed`, so the card and
+ * the page behind it read the same parameters and can never disagree about
+ * what was asked. `card` is read by its presence: `?card` and `?card=1` both
+ * ask for it.
+ *
+ * Pure string work: the page reads these addresses, and the tool server
+ * writes them, in Node.
+ */
+import { parseQueryEntries } from "../../router/core/query.js";
+import { EMBED_PARAM, HIDE_PARAM } from "../../share/core/config.js";
+/** The parameter asking for the answer's card instead of the page. */
+export const CARD_PARAM = 'card';
+/**
+ * Whether an address asks for a card.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns True when it names `card`, with a value or bare.
+ */
+export function isCardAddress(search) {
+    for (const [key] of parseQueryEntries(search)) {
+        if (key === CARD_PARAM)
+            return true;
+    }
+    return false;
+}
+/**
+ * The site's own page a card stands for, with its chrome: the card's address
+ * without `card`, `embed`, `hide` and what only the card reads. Every other
+ * parameter is kept exactly as it was written, so the `+` of a charged atom
+ * stays a plus and the commas of a list stay commas. This is the address an
+ * answer's `link` names, and the one the card's Details button opens.
+ * @param location - The card's address: `globalThis.location`, or
+ *   `new URL(href)` for an address held as text.
+ * @param options - What only the site's card reads.
+ * @returns The page's absolute address, without a fragment.
+ */
+export function sitePageUrl(location, options = {}) {
+    const { cardParams = [], literalPlus = true, isCardOnly } = options;
+    const dropped = new Set([CARD_PARAM, EMBED_PARAM, HIDE_PARAM, ...cardParams]);
+    const kept = [];
+    const search = location.search.startsWith('?')
+        ? location.search.slice(1)
+        : location.search;
+    for (const part of search.split('&')) {
+        const [entry] = parseQueryEntries(part, { literalPlus });
+        if (entry === undefined || dropped.has(entry[0]))
+            continue;
+        if (isCardOnly?.(entry[0], location.pathname))
+            continue;
+        kept.push(part);
+    }
+    const query = kept.join('&');
+    return `${location.origin}${location.pathname}${query === '' ? '' : `?${query}`}`;
+}
+//# sourceMappingURL=cardAddress.js.map

package/lib/card/core/cardAddress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardAddress.js","sourceRoot":"","sources":["../../../src/card/core/cardAddress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAErE,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9C,IAAI,GAAG,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;IACtC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAwCD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,QAAsB,EACtB,UAA2B,EAAE;IAE7B,MAAM,EAAE,UAAU,GAAG,EAAE,EAAE,WAAW,GAAG,IAAI,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACpE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;QAC5C,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1B,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,SAAS;QAC3D,IAAI,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;YAAE,SAAS;QACxD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,QAAQ,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;AACpF,CAAC"}

package/lib/card/core/cardPageUrl.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two addresses a chat frames for one answer: the card, inline, and the
+ * page itself, over the full screen. Both are the site's page under `embed`,
+ * so neither carries the site's chrome; the card adds `card` and what only it
+ * reads.
+ */
+/** How {@link framedPageUrl} frames a page. */
+export interface FramedPageOptions {
+    /**
+     * The parts of the page left out, on the card and on the full page alike:
+     * keys of the site's `hide` vocabulary, written `hide=a,b`.
+     * @default []
+     */
+    hide?: readonly string[];
+}
+/** What {@link cardPageUrl} adds to the framed page. */
+export interface CardPageOptions extends FramedPageOptions {
+    /**
+     * What `card` carries, for a site whose page draws more than one card:
+     * wikidata's `card=infobox`.
+     * @default '1'
+     */
+    card?: string;
+    /**
+     * What only the card reads, written after `card` in the order given, e.g.
+     * `{ rows: '10' }`. A value left `undefined` or empty is not written.
+     * @default {}
+     */
+    extra?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * The page under `embed=1`, and `hide` when parts are left out: what a chat
+ * shows over the full screen when the reader asks for more than the card.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out.
+ * @returns The framed page's address.
+ */
+export declare function framedPageUrl(page: string, options?: FramedPageOptions): string;
+/**
+ * The card of an answer: the framed page with `card`, and what only the card
+ * reads after it.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out, and what the card draws.
+ * @returns The card's address.
+ */
+export declare function cardPageUrl(page: string, options?: CardPageOptions): string;
+//# sourceMappingURL=cardPageUrl.d.ts.map

package/lib/card/core/cardPageUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardPageUrl.d.ts","sourceRoot":"","sources":["../../../src/card/core/cardPageUrl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAOR"}

package/lib/card/core/cardPageUrl.js

@@ -0,0 +1,59 @@
+/**
+ * The two addresses a chat frames for one answer: the card, inline, and the
+ * page itself, over the full screen. Both are the site's page under `embed`,
+ * so neither carries the site's chrome; the card adds `card` and what only it
+ * reads.
+ */
+import { formatQueryEntries } from "../../router/core/query.js";
+import { EMBED_PARAM, HIDE_PARAM } from "../../share/core/config.js";
+import { CARD_PARAM } from "./cardAddress.js";
+/**
+ * The page under `embed=1`, and `hide` when parts are left out: what a chat
+ * shows over the full screen when the reader asks for more than the card.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out.
+ * @returns The framed page's address.
+ */
+export function framedPageUrl(page, options = {}) {
+    const { hide = [] } = options;
+    const entries = [[EMBED_PARAM, '1']];
+    if (hide.length > 0)
+        entries.push([HIDE_PARAM, hide.join(',')]);
+    return withQueryEntries(page, entries);
+}
+/**
+ * The card of an answer: the framed page with `card`, and what only the card
+ * reads after it.
+ * @param page - The site's page as people open it, with its own query and
+ *   without `embed`, `hide` or `card`; absolute, or a path.
+ * @param options - The parts left out, and what the card draws.
+ * @returns The card's address.
+ */
+export function cardPageUrl(page, options = {}) {
+    const { card = '1', extra = {} } = options;
+    const entries = [[CARD_PARAM, card]];
+    for (const [key, value] of Object.entries(extra)) {
+        if (value !== undefined && value !== '')
+            entries.push([key, value]);
+    }
+    return withQueryEntries(framedPageUrl(page, options), entries);
+}
+/**
+ * Append parameters to an address, before its fragment.
+ * @param address - The address, with or without a query.
+ * @param entries - The parameters, in the order they are written.
+ * @returns The address carrying them.
+ */
+function withQueryEntries(address, entries) {
+    const hashIndex = address.indexOf('#');
+    const head = hashIndex === -1 ? address : address.slice(0, hashIndex);
+    const fragment = hashIndex === -1 ? '' : address.slice(hashIndex);
+    const separator = head.includes('?')
+        ? head.endsWith('?') || head.endsWith('&')
+            ? ''
+            : '&'
+        : '?';
+    return `${head}${separator}${formatQueryEntries(entries)}${fragment}`;
+}
+//# sourceMappingURL=cardPageUrl.js.map