research: visualisation library for the SmartEM front end - comparative analysis and ADR

Read apps/smartem/package.json and the thirteen listed TSX components, starting with weights/WeightsTimeline.tsx. Compare the mandatory @diamondlightsource/davidia candidate and keeping hand-rolled SVG against the existing spatial overlays, timeline, migration cost, accessibility, and related image-visualisation work. Done means a DLS-wide decision is recorded in docs/decision-records/decisions/0022-visualisation-library.md.

Updated. The analysis this issue calls for is still wanted, and the candidate list and
comparison axes below still stand. Three things have changed since it was written, and the
scope has widened as a result.

What changed

The blocking relationship no longer exists. This issue stated that implementation blocks on
the ADR landing. It did not: smartem-frontend#67 closed on 2026-06-15 with the model-weight
display shipped.

No library was chosen, and none was added. apps/smartem/package.json contains no charting
dependency of any kind. The weight display, and everything since, was hand-rolled in SVG.

The ADR number is taken. 0018 is now 0018-smartem-agent-keycloak-auth.md, and the
sequence has reached 0021-micrograph-preview-image-ingestion-and-serving.md. The next
available number is 0022.

The situation this issue warned about has arrived by a different route

The original rationale was that choosing a library casually creates a de-facto standard and
therefore lock-in. What happened instead is that not choosing became the de-facto standard.
Hand-written <svg> now appears in thirteen components:

weights/WeightsTimeline.tsx           spatial/AtlasMap.tsx
spatial/SquareMap.tsx                 spatial/LatentSpacePanel.tsx
spatial/AcquisitionPathOverlay.tsx    predictions/PredictionsView.tsx
foilhole/FoilholeDetail.tsx           workspace/WorkspaceView.tsx
dashboard/MockDashboard.tsx           session/ContextStrip.tsx
session/MockContextStrip.tsx          shell/Header.tsx
widgets/CommandPalette/CommandPalette.tsx

WeightsTimeline.tsx is the component this ADR was intended to precede.

This is not automatically the wrong outcome - bespoke SVG has served the spatial views well, and
the overlays are genuinely bespoke. But it was arrived at by default rather than by decision,
and it is accumulating. That is precisely what an ADR exists to prevent, whichever way it lands.

Consequences for scope

The existing components are now requirements, not a blank slate. Any candidate must be
assessed against what already exists, not only against the original sparkline-and-drill-down
brief. Specifically:

• Can it subsume the spatial overlays - clickable foilhole and grid-square geometry drawn over
  a raster image, with gradient sequence colouring and interaction - or would those stay bespoke
  regardless? A library that cannot is not a full answer, and would mean maintaining two
  visualisation approaches indefinitely.
• Can it express the weight-evolution timeline that already exists, without regression?
• What is the migration cost of thirteen components, and is partial adoption acceptable? A
  clear "charts use library X, spatial overlays stay bespoke" split is a legitimate and
  probably likely conclusion - but it should be stated, not drifted into.

"Keep hand-rolling" is now a first-class candidate and must be evaluated on the same axes as
the libraries, rather than treated as the absence of a decision. It has real advantages already
demonstrated in this codebase - zero bundle cost, exact control, no theme-integration friction -
and real costs in maintenance and accessibility. Note the accessibility dimension is not
hypothetical: the hand-rolled spatial views are the subject of an open keyboard-access issue.

This overlaps with the image-visualisation work. Improving front-end image visualisation
involves choosing between bespoke SVG over raster images and a tiled viewer component. That is
the same decision seen from another angle. Deciding the two separately risks two incompatible
answers, and they should at minimum be cross-referenced.

Unchanged

The candidate list, the comparison axes, the constraints, and the process below all still apply.
In particular, @diamondlightsource/davidia remains a mandatory candidate, and choosing
otherwise still needs defending on concrete grounds rather than preference. The intended
audience is still DLS-wide rather than SmartEM-only.

Only the ADR filename changes: docs/decision-records/decisions/0022-visualisation-library.md.