react-msaview 6.4.2 → 7.0.0

package/src/rawImports.d.ts

@@ -0,0 +1,9 @@
+// Vite resolves a `?raw` import to the file's text. The lib does not build with
+// Vite, but realResidueMapping.test.ts reads the examples package's alignment
+// files that way (they are files, not string constants), so tsc has to be told
+// what the suffix means. tsconfig.build.json excludes this, and tsc emits
+// nothing for a .d.ts anyway, so it stays out of the published types.
+declare module '*?raw' {
+  const content: string
+  export default content
+}

package/src/renderToStaticMarkup.ts

@@ -1,3 +1,4 @@
+import { colord } from 'colord'
 import { flushSync } from 'react-dom'
 import { createRoot } from 'react-dom/client'
 
@@ -37,11 +38,37 @@ export function renderToStaticMarkup(node: React.ReactElement) {
     // export ever taken. The markup is a string by here and needs no DOM.
     root.unmount()
   }
-  // SVG 1.1 presentation attributes (`fill`, `stroke`) take a <color>, which
-  // excludes rgba() -- alpha belongs in a separate fill-opacity. Illustrator and
-  // older Inkscape drop an element whose fill they cannot parse, so alpha is
-  // stripped rather than left to break the shape. MUI palette values are the
-  // usual source. Dropping rather than converting is what the figure snapshots
-  // encode.
-  return html.replaceAll(/\brgba\((.+?),[^,]+?\)/g, 'rgb($1)')
+  return html
+}
+
+const tag = /<[a-zA-Z][^>]*>/g
+const colorAttr = /\b(fill|stroke|stop-color)="([^"]+)"/g
+
+/**
+ * Rewrites every color an SVG 1.1 presentation attribute cannot hold.
+ *
+ * `fill`, `stroke` and `stop-color` take a <color>, which is a keyword, a hex
+ * triplet or rgb() -- not rgba(), which MUI palette values are full of, and not
+ * hsl(), which the percent-identity scheme colors with. Illustrator and older
+ * Inkscape drop an element whose fill they cannot parse, so the minimap thumb
+ * came out opaque and the identity coloring came out missing. Alpha moves to
+ * the matching -opacity attribute, unless the element already carries one.
+ */
+export function svgSafeColors(html: string) {
+  return html.replaceAll(tag, el =>
+    el.replaceAll(colorAttr, (match, attr: string, value: string) => {
+      if (!/^(rgba|hsl)/i.test(value)) {
+        return match
+      }
+      const color = colord(value)
+      if (!color.isValid()) {
+        return match
+      }
+      const alpha = color.alpha()
+      const hex = color.alpha(1).toHex()
+      return alpha === 1 || el.includes(`${attr}-opacity=`)
+        ? `${attr}="${hex}"`
+        : `${attr}="${hex}" ${attr}-opacity="${alpha}"`
+    }),
+  )
 }

package/src/renderToSvg.tsx

@@ -7,13 +7,12 @@ import { visibleRowRange } from './components/getVisibleLeaves.ts'
 import MinimapSVG from './components/minimap/MinimapSVG.tsx'
 import { rasterImageHref, rasterSupported } from './components/msa/msaRaster.ts'
 import { renderBoxFeatureCanvasBlock } from './components/msa/renderBoxFeatureCanvasBlock.ts'
-import { renderHighlights } from './components/msa/renderHighlights.ts'
+import { renderPersistentHighlights } from './components/msa/renderHighlights.ts'
 import { renderMSABlock } from './components/msa/renderMSABlock.ts'
 import { visibleColRange } from './components/msa/visibleColRange.ts'
 import { renderAllTracks } from './components/tracks/drawTracks.ts'
 import { renderTreeCanvas } from './components/tree/renderTreeCanvas.ts'
-import { renderToStaticMarkup } from './renderToStaticMarkup.ts'
-import { colorContrast } from './util.ts'
+import { renderToStaticMarkup, svgSafeColors } from './renderToStaticMarkup.ts'
 
 import type { MsaViewModel } from './model.ts'
 import type { Context as ContextType } from '@jbrowse/svgcanvas'
@@ -131,14 +130,26 @@ export async function renderToSvg(model: MsaViewModel, opts: ExportSvgOptions) {
     throw model.error
   }
   const { Context } = await import('@jbrowse/svgcanvas')
-  return renderToStaticMarkup(
+  // Each svgcanvas layer is already serialized SVG, and React would have to
+  // parse it into a second DOM only for the export to serialize it back out.
+  // The layers register themselves here instead, and their markup is spliced
+  // into the page as strings.
+  const layers = new Map<string, ContextType>()
+  const markup = renderToStaticMarkup(
     <MsaSvg
       model={model}
       theme={opts.theme}
       Context={Context}
       layout={getLayout(model, opts)}
+      layers={layers}
     />,
   )
+  return svgSafeColors(
+    markup.replaceAll(/<g data-layer="([^"]+)"><\/g>/g, (match, id: string) => {
+      const ctx = layers.get(id)
+      return ctx ? `<g>${ctx.getSvg().innerHTML}</g>` : match
+    }),
+  )
 }
 
 function MsaSvg({
@@ -146,11 +157,13 @@ function MsaSvg({
   theme,
   Context,
   layout,
+  layers,
 }: {
   model: MsaViewModel
   theme: Theme
   Context: typeof ContextType
   layout: Layout
+  layers: LayerMap
 }) {
   const { width, trackHeight, includeMinimap, legendWidth } = layout
   const { treeAreaWidth, minimapHeight, visibleDomainTypes } = model
@@ -162,8 +175,7 @@ function MsaSvg({
     legendWidth > 0
       ? Math.max(layout.height, legendTop + legendHeight(visibleDomainTypes))
       : layout.height
-  const contrastScheme = colorContrast(model.colorScheme, theme)
-  const props = { Context, model, theme, layout, contrastScheme }
+  const props = { Context, model, theme, layout, layers }
 
   const body = (
     <>
@@ -269,21 +281,17 @@ function LegendSVG({
   )
 }
 
+type LayerMap = Map<string, ContextType>
+
 interface LayerProps {
   model: MsaViewModel
   theme: Theme
   layout: Layout
   Context: typeof ContextType
-  contrastScheme: Record<string, string>
+  layers: LayerMap
 }
 
-function CoreRendering({
-  model,
-  theme,
-  layout,
-  Context,
-  contrastScheme,
-}: LayerProps) {
+function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
   const { contentHeight, offsetX, offsetY, msaAreaWidth } = layout
   const { treeAreaWidth, id } = model
 
@@ -315,7 +323,6 @@ function CoreRendering({
     model,
     theme,
     ctx: msaCtx,
-    contrastScheme,
     offsetX,
     offsetY,
     blockSizeXOverride: msaAreaWidth,
@@ -324,7 +331,7 @@ function CoreRendering({
     rasterTiles: !!raster,
   })
   msaCtx.resetTransform()
-  renderHighlights({
+  renderPersistentHighlights({
     ctx: msaCtx,
     model,
     theme,
@@ -341,6 +348,7 @@ function CoreRendering({
         width={treeAreaWidth}
         height={contentHeight}
         ctx={treeCtx}
+        layers={layers}
       />
       <ClipGroup
         clipId={`msa-${id}`}
@@ -348,6 +356,7 @@ function CoreRendering({
         height={contentHeight}
         transform={`translate(${treeAreaWidth} 0)`}
         ctx={msaCtx}
+        layers={layers}
         underlay={raster}
       />
     </>
@@ -412,13 +421,7 @@ function rasterBackground({
   ) : undefined
 }
 
-function TrackRendering({
-  model,
-  theme,
-  layout,
-  Context,
-  contrastScheme,
-}: LayerProps) {
+function TrackRendering({ model, theme, layout, Context, layers }: LayerProps) {
   const { trackHeight, offsetX, msaAreaWidth } = layout
   const { treeAreaWidth, id } = model
 
@@ -426,7 +429,6 @@ function TrackRendering({
   renderAllTracks({
     model,
     ctx,
-    contrastScheme,
     theme,
     offsetX,
     blockSizeXOverride: msaAreaWidth,
@@ -442,6 +444,7 @@ function TrackRendering({
           width={msaAreaWidth}
           height={trackHeight}
           ctx={ctx}
+          layers={layers}
         />
       </g>
     </>
@@ -487,8 +490,8 @@ function TrackLabelsSVG({
   )
 }
 
-// Clips a svgcanvas Context to its box and injects its markup verbatim (it is
-// already serialized SVG, not React). `underlay` draws beneath that markup,
+// Clips a svgcanvas Context to its box and leaves a placeholder for renderToSvg
+// to splice the layer's own markup into. `underlay` draws beneath that markup,
 // inside the same clip, for the parts of a layer React emits directly.
 function ClipGroup({
   clipId,
@@ -496,6 +499,7 @@ function ClipGroup({
   height,
   transform,
   ctx,
+  layers,
   underlay,
 }: {
   clipId: string
@@ -503,8 +507,10 @@ function ClipGroup({
   height: number
   transform?: string
   ctx: ContextType
+  layers: LayerMap
   underlay?: React.ReactNode
 }) {
+  layers.set(clipId, ctx)
   return (
     <>
       <defs>
@@ -514,7 +520,7 @@ function ClipGroup({
       </defs>
       <g clipPath={`url(#${clipId})`} transform={transform}>
         {underlay}
-        <g dangerouslySetInnerHTML={{ __html: ctx.getSvg().innerHTML }} />
+        <g data-layer={clipId} />
       </g>
     </>
   )

package/src/rowCoordinateCalculations.ts

@@ -1,5 +1,3 @@
-import { isBlank } from './util.ts'
-
 /**
  * MSA Coordinate Systems:
  *
@@ -93,65 +91,23 @@ export function visibleColsBefore(blanks: number[], globalCol: number) {
 }
 
 /**
- * Convert a visible column to a row-specific sequence position.
- * Returns undefined if the position is a gap in the sequence.
+ * The ungapped position a row holds at a global column, or undefined when that
+ * column is a gap in the row or past its end.
  *
- * @param seq - The row's sequence string (including gaps)
- * @param blanks - Sorted array of global column indices that are hidden
- * @param visibleCol - The visible column index
- * @returns The sequence position, or undefined if it's a gap
+ * A binary search of the row's seqPos index (ascending), not a scan of the row:
+ * this answers on every mouse move, and scanning a 30k-column row per event is
+ * the whole frame.
+ *
+ * @param index - The row's seqPos -> global column index (buildSeqPosIndex)
+ * @param globalCol - The global column index in the full MSA
  */
-export function visibleColToSeqPos({
-  seq,
-  blanks,
-  visibleCol,
-}: {
-  seq: string
-  blanks: number[]
-  visibleCol: number
-}) {
-  // First convert the visible column to global column
-  const globalCol = visibleColToGlobalCol(blanks, visibleCol)
-  const seqLen = seq.length
-
-  // Check if the position in the sequence is a gap
-  if (globalCol < seqLen && isBlank(seq[globalCol])) {
+export function seqPosOfGlobalCol(
+  index: Int32Array | undefined,
+  globalCol: number,
+) {
+  if (!index) {
     return undefined
   }
-
-  // Count non-gap characters up to the global position
-  let seqPos = 0
-  for (let i = 0; i < globalCol && i < seqLen; i++) {
-    if (!isBlank(seq[i])) {
-      seqPos++
-    }
-  }
-
-  return globalCol < seqLen ? seqPos : undefined
-}
-
-/**
- * Convert a visible column to a row-specific sequence position, with row lookup.
- *
- * @param rowName - The name of the row
- * @param visibleCol - The visible column index
- * @param rowMap - Map from row name to sequence string
- * @param blanks - Sorted array of global column indices that are hidden
- * @returns The sequence position, or undefined if row not found or position is a gap
- */
-export function visibleColToSeqPosForRow({
-  rowName,
-  visibleCol,
-  rowMap,
-  blanks,
-}: {
-  rowName: string
-  visibleCol: number
-  rowMap: Map<string, string>
-  blanks: number[]
-}) {
-  const seq = rowMap.get(rowName)
-  return seq !== undefined
-    ? visibleColToSeqPos({ seq, visibleCol, blanks })
-    : undefined
+  const seqPos = partitionPoint(index.length, i => index[i]! >= globalCol)
+  return index[seqPos] === globalCol ? seqPos : undefined
 }

package/src/seqPosToGlobalCol.ts

@@ -19,5 +19,7 @@ export function buildSeqPosIndex(row: string) {
       index[n++] = col
     }
   }
-  return index.subarray(0, n)
+  // slice, not subarray: a subarray keeps the whole row-length buffer alive,
+  // and a gappy alignment's indexes are held for as long as the parse is
+  return index.slice(0, n)
 }

package/src/types.ts

@@ -8,7 +8,7 @@ export interface Accession {
 // which renderer draws a track's content. Every track kind draws into the same
 // per-column coordinate space, so the kind picks the draw function rather than
 // the geometry -- see drawTracks.ts, which dispatches on it.
-export type TrackKind = 'text' | 'bar' | 'logo'
+export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler'
 
 export interface BasicTrackModel {
   id: string
@@ -16,6 +16,8 @@ export interface BasicTrackModel {
   associatedRowName?: string
   height: number
   kind: TrackKind
+  // hidden until the user asks for it, unless they have already chosen
+  defaultOff?: boolean
 }
 
 export interface TextTrackModel extends BasicTrackModel {
@@ -29,20 +31,45 @@ export interface BarTrackModel extends BasicTrackModel {
   barColor?: string
 }
 
+// a pair of columns joined by an arc, already resolved to 0-based visible
+// columns -- what the renderer consumes
+export interface Arc {
+  start: number
+  end: number
+  color?: string
+}
+
+// a track that joins pairs of columns with arcs (RNA base pairs, disulfide
+// bonds, residue contacts)
+export interface ArcTrackModel extends BasicTrackModel {
+  arcs?: Arc[]
+  arcColor?: string
+}
+
 export interface BasicTrack {
   ReactComponent: React.FC<any>
-  model: TextTrackModel & BarTrackModel
+  model: TextTrackModel & BarTrackModel & ArcTrackModel
+}
+
+// one arc of an arc track, in the snapshot's own coordinates: 1-based and
+// inclusive, alignment columns unless the track names a `row`
+export interface ArcSpec {
+  start: number
+  end: number
+  color?: string
 }
 
 // a track supplied as data in the snapshot rather than computed from the
 // alignment. `values` (bar) or `data` (text) index alignment columns, or the
-// 1-based residues of `row` when it names one
+// 1-based residues of `row` when it names one; `arcs` (arc) name two such
+// positions each
 export interface ColumnTrackSpec {
   id: string
   name: string
-  kind: 'bar' | 'text'
+  kind: 'bar' | 'text' | 'arc'
   values?: number[]
   data?: string
+  arcs?: ArcSpec[]
   max?: number
   color?: string
   colors?: Record<string, string>
@@ -50,6 +77,106 @@ export interface ColumnTrackSpec {
   height?: number
 }
 
+// One contiguous run where a row's residues and a structure's line up 1:1.
+// Segment-shaped because SIFTS is: a dozen numbers cover what a per-residue
+// array would spend kilobytes on, and it makes the refusal rule structural
+// rather than a vocabulary -- a position no segment covers is unmapped, and
+// there is no status field to disagree with.
+export interface ResidueSegment {
+  rowStart: number
+  rowEnd: number
+  structStart: number
+  structEnd: number
+}
+
+// the structure half of a mapping. `id` is whatever the producer calls the
+// entry (a PDB id, an AlphaFold accession); `asymId` names the chain, which is
+// what distinguishes two mappings onto the same entry
+export interface MappedStructure {
+  id: string
+  kind?: 'experimental' | 'predicted'
+  asymId?: string
+  url?: string
+}
+
+/**
+ * Which residue of which structure a row's residue is, as data. Computed by
+ * whatever knows how -- SIFTS, an AlphaFold model, a curator -- and carried in
+ * the snapshot, because the viewer cannot work it out: matching a row to a
+ * structure by sequence equality fails for a construct with an expression tag,
+ * a truncation, an engineered residue, or a row that is a subsequence of the
+ * entry, and it fails in the direction that looks like it worked.
+ *
+ * Positions are 1-based and inclusive on both sides, as GFF and `highlights`
+ * are. Structure positions are `label_seq_id`, the index into the entity's
+ * SEQRES; author numbering carries insertion codes and stays out.
+ *
+ * `unobserved` is in structure positions: present in SEQRES with no
+ * coordinates. Worth distinguishing from unmapped, because "the
+ * crystallographer could not see it" and "this protein does not have that
+ * residue" mean different things to a reader.
+ */
+export interface ResidueMapping {
+  row: string
+  accession?: string
+  structure: MappedStructure
+  segments: ResidueSegment[]
+  unobserved?: [number, number][]
+  /**
+   * ungapped length of the row this was computed against. Optional, and worth
+   * setting: a mapping outlives the alignment it was made for, and pointing at
+   * residue 58 of a sequence that has since been re-aligned, revised or swapped
+   * is the failure this whole layer exists to avoid. Declared here, the viewer
+   * can notice and refuse instead of answering from stale arithmetic.
+   */
+  rowLength?: number
+  generated?: {
+    by?: string
+    date?: string
+    sourceSha256?: string
+  }
+}
+
+// why a mapping, or one segment of it, is not being used. Refusing silently
+// leaves a host unable to tell "no structure for this row" from "the mapping
+// no longer matches what is loaded", which are different problems with
+// different fixes.
+export interface ResidueMappingProblem {
+  row: string
+  structureId: string
+  /**
+   * `mapping` means the whole mapping is out: the evidence is about the row it
+   * claims, so nothing it says can be trusted. `segment` takes only that
+   * segment, since the rest of the mapping still describes residues that exist.
+   */
+  scope: 'mapping' | 'segment'
+  reason: string
+}
+
+// what a lookup gives back: the structure residue a row residue is, or the row
+// residue a structure residue is. `observed` is false for a residue the
+// structure declares but did not resolve.
+export interface StructureResidue {
+  structure: MappedStructure
+  position: number
+  observed: boolean
+}
+
+export interface RowResidue {
+  rowName: string
+  seqPos: number
+}
+
+/**
+ * One loaded document that the snapshot leaves behind, and how big it is.
+ * `what` names it the way the import form does, since that is where the reader
+ * would go to load it differently.
+ */
+export interface UnshareableData {
+  what: 'alignment' | 'tree' | 'annotations' | 'row metadata' | 'data tracks'
+  bytes: number
+}
+
 // the overlay annotation itself lives in msa-parsers, alongside the adapters
 // that build it. TidyDomainAnnotation is its former name, kept because
 // downstream plugins name it in their emitted declarations.

package/src/util.ts

@@ -36,14 +36,37 @@ export function transform<T>(
   return Object.fromEntries(Object.entries(obj).map(cb))
 }
 
-export function colorContrast(
-  colorScheme: Record<string, string>,
-  theme: Theme,
-) {
-  return transform(colorScheme, ([letter, color]) => [
-    letter,
-    theme.palette.getContrastText(colord(color).toHex()),
-  ])
+const contrastTextCaches = new WeakMap<Theme, Map<string, string>>()
+
+/**
+ * Readable letter color over a given cell color, memoized per theme.
+ *
+ * A dynamic scheme colors a cell from its column, so there is no letter->color
+ * table to precompute a contrast table from; asking per cell color covers the
+ * dynamic schemes, the static ones and a track's own `colors` alike. An
+ * uncolored cell sits on the theme's background, where the theme's own text
+ * color is what stays readable -- `black` turned every gap and every uncolored
+ * cell invisible in the dark theme.
+ */
+export function contrastTextFn(theme: Theme) {
+  let cache = contrastTextCaches.get(theme)
+  if (!cache) {
+    cache = new Map()
+    contrastTextCaches.set(theme, cache)
+  }
+  const fallback = theme.palette.text.primary
+  return (color: string | undefined) => {
+    if (!color) {
+      return fallback
+    }
+    const hit = cache.get(color)
+    if (hit !== undefined) {
+      return hit
+    }
+    const out = theme.palette.getContrastText(colord(color).toHex())
+    cache.set(color, out)
+    return out
+  }
 }
 
 export function dropBlanks<T>(blanks: number[], arr: T[]) {
@@ -110,9 +133,3 @@ export function computeRowInsertions(blanks: number[], seq: string) {
 export function len(a: { end: number; start: number }) {
   return a.end - a.start
 }
-
-// https://sonnhammer.sbc.su.se/Stockholm.html
-// gaps can be a . or - in stockholm
-export function isBlank(s?: string) {
-  return s === '-' || s === '.'
-}

package/src/version.ts

@@ -1 +1 @@
-export const version = '6.4.2'
+export const version = '7.0.0'

package/src/wuss.ts

@@ -0,0 +1,62 @@
+// WUSS notation (Rfam's `#=GC SS_cons`) names a consensus secondary structure
+// by pairing columns. Nested helices use bracket pairs -- <>, (), [], {} --
+// each type kept on its own stack, and a pseudoknot, which by definition
+// crosses a helix it cannot nest inside, uses a letter pair instead: `A` opens
+// and `a` closes, `B`/`b` for a second one. Everything else (. , _ - : ~) is
+// unpaired.
+
+const closeToOpen: Record<string, string> = {
+  '>': '<',
+  ')': '(',
+  ']': '[',
+  '}': '{',
+}
+const opens = new Set(Object.values(closeToOpen))
+
+export interface BasePair {
+  /** 0-based column */
+  start: number
+  /** 0-based column */
+  end: number
+  /** the pair crosses a helix rather than nesting inside one */
+  pseudoknot: boolean
+}
+
+/**
+ * The base pairs a WUSS string encodes, as 0-based column indexes. Unmatched
+ * brackets are dropped rather than throwing: a hand-edited or truncated
+ * alignment should still draw the helices it does close.
+ */
+export function parseWuss(ss: string): BasePair[] {
+  const stacks = new Map<string, number[]>()
+  const pairs: BasePair[] = []
+  const push = (key: string, col: number) => {
+    const stack = stacks.get(key)
+    if (stack) {
+      stack.push(col)
+    } else {
+      stacks.set(key, [col])
+    }
+  }
+  const pop = (key: string, col: number, pseudoknot: boolean) => {
+    const start = stacks.get(key)?.pop()
+    if (start !== undefined) {
+      pairs.push({ start, end: col, pseudoknot })
+    }
+  }
+
+  for (let col = 0; col < ss.length; col++) {
+    const ch = ss[col]!
+    const opener = closeToOpen[ch]
+    if (opens.has(ch)) {
+      push(ch, col)
+    } else if (opener) {
+      pop(opener, col, false)
+    } else if (ch >= 'A' && ch <= 'Z') {
+      push(ch, col)
+    } else if (ch >= 'a' && ch <= 'z') {
+      pop(ch.toUpperCase(), col, true)
+    }
+  }
+  return pairs.sort((a, b) => a.start - b.start)
+}