react-msaview 7.0.0 → 8.1.0

package/src/renderToSvg.tsx

@@ -5,15 +5,30 @@ import { when } from 'mobx'
 
 import { visibleRowRange } from './components/getVisibleLeaves.ts'
 import MinimapSVG from './components/minimap/MinimapSVG.tsx'
+import { legendRows } from './components/msa/legendRows.ts'
 import { rasterImageHref, rasterSupported } from './components/msa/msaRaster.ts'
 import { renderBoxFeatureCanvasBlock } from './components/msa/renderBoxFeatureCanvasBlock.ts'
 import { renderPersistentHighlights } from './components/msa/renderHighlights.ts'
 import { renderMSABlock } from './components/msa/renderMSABlock.ts'
 import { visibleColRange } from './components/msa/visibleColRange.ts'
+import { headerRunsAcross } from './components/rowpanels/headerLayout.ts'
+import { renderRowPanels } from './components/rowpanels/renderRowPanel.ts'
 import { renderAllTracks } from './components/tracks/drawTracks.ts'
+import {
+  bracketGap,
+  cladeHeight,
+  cladeInGutter,
+  cladeLabelHorizontal,
+  cladeLabelOffset,
+} from './components/tree/cladeBrackets.ts'
 import { renderTreeCanvas } from './components/tree/renderTreeCanvas.ts'
+import { renderTreeOverview } from './components/tree/renderTreeOverview.ts'
+import { treeScaleBarHeight } from './constants.ts'
+import { measureTextCanvas } from './measureTextCanvas.ts'
 import { renderToStaticMarkup, svgSafeColors } from './renderToStaticMarkup.ts'
+import { outlineColor } from './util.ts'
 
+import type { LegendRow } from './components/msa/legendRows.ts'
 import type { MsaViewModel } from './model.ts'
 import type { Context as ContextType } from '@jbrowse/svgcanvas'
 import type { Theme } from '@mui/material'
@@ -25,28 +40,29 @@ export interface ExportSvgOptions {
   exportType: 'entire' | 'viewport'
 }
 
-// domain-legend geometry, shared by the width calculation and the renderer so
-// the reserved column on the right exactly fits the drawn legend
+// legend geometry, shared by the width calculation and the renderer so the
+// reserved column on the right exactly fits the drawn legends
 const LEGEND_PAD = 8
 const LEGEND_ROW_H = 16
 const LEGEND_SWATCH = 12
 const LEGEND_FONT = 12
 const LEGEND_CHAR_W = 7
 
+// the width of a character as a fraction of the font size, close enough for a
+// sans-serif average
+const CHAR_WIDTH = 0.6
+
 const LEGEND_MAX_W = 360
 const LEGEND_TEXT_X = LEGEND_PAD + LEGEND_SWATCH + 6
 
-function getLegendWidth(model: MsaViewModel) {
-  const maxLen = model.visibleDomainTypes.reduce(
-    (a, d) => Math.max(a, d.name.length),
-    0,
-  )
+function getLegendWidth(rows: LegendRow[]) {
+  const maxLen = rows.reduce((a, r) => Math.max(a, r.label.length), 0)
   const w = LEGEND_TEXT_X + LEGEND_PAD + maxLen * LEGEND_CHAR_W
   return Math.min(LEGEND_MAX_W, Math.max(120, w))
 }
 
-function legendHeight(domainTypes: unknown[]) {
-  return LEGEND_PAD * 2 + domainTypes.length * LEGEND_ROW_H
+function legendHeight(rows: LegendRow[]) {
+  return LEGEND_PAD * 2 + rows.length * LEGEND_ROW_H
 }
 
 // resolved sizes/offsets (in svg user units) for the chosen export, shared by
@@ -58,6 +74,9 @@ interface Layout {
   height: number
   contentHeight: number
   trackHeight: number
+  // the band the minimap, the row panel headers and the tree overview stacked
+  // on the scale bar share across the top
+  topHeight: number
   offsetX: number
   offsetY: number
   includeMinimap: boolean
@@ -71,11 +90,15 @@ function getLayout(model: MsaViewModel, opts: ExportSvgOptions): Layout {
     totalWidth,
     totalHeight,
     treeAreaWidth,
+    rowPanelsWidth,
+    rowPanelsHeaderHeight,
     totalTrackAreaHeight,
     minimapHeight,
     msaAreaHeight,
     msaCanvasWidth,
     showHorizontalScrollbar,
+    treeOverviewHeight,
+    treeScaleBar,
   } = model
   const trackHeight = opts.includeTracks ? totalTrackAreaHeight : 0
   // the minimap reflects the live viewport scroll position, so it's only
@@ -86,10 +109,14 @@ function getLayout(model: MsaViewModel, opts: ExportSvgOptions): Layout {
     opts.exportType === 'viewport' &&
     !!opts.includeMinimap &&
     showHorizontalScrollbar
-  const legendWidth =
-    model.actuallyShowDomains && model.visibleDomainTypes.length > 0
-      ? getLegendWidth(model)
-      : 0
+  const rows = legendRows(model.legends)
+  const legendWidth = rows.length > 0 ? getLegendWidth(rows) : 0
+  const topHeight = Math.max(
+    includeMinimap ? minimapHeight : 0,
+    rowPanelsHeaderHeight,
+    treeOverviewHeight + (treeScaleBar ? treeScaleBarHeight : 0),
+  )
+  const gutterWidth = treeAreaWidth + rowPanelsWidth
 
   // width stays content-only; the legend occupies an extra column added at the
   // svg root in MsaSvg. The viewport export takes the alignment canvas's own
@@ -98,23 +125,24 @@ function getLayout(model: MsaViewModel, opts: ExportSvgOptions): Layout {
   // columns the scrollbars hide on screen
   return opts.exportType === 'entire'
     ? {
-        width: totalWidth + treeAreaWidth,
+        width: totalWidth + gutterWidth,
         msaAreaWidth: totalWidth,
-        height: totalHeight + trackHeight,
+        height: totalHeight + trackHeight + topHeight,
         contentHeight: totalHeight,
         trackHeight,
+        topHeight,
         offsetX: 0,
         offsetY: 0,
         includeMinimap,
         legendWidth,
       }
     : {
-        width: msaCanvasWidth + treeAreaWidth,
+        width: msaCanvasWidth + gutterWidth,
         msaAreaWidth: msaCanvasWidth,
-        height:
-          msaAreaHeight + (includeMinimap ? minimapHeight : 0) + trackHeight,
+        height: msaAreaHeight + topHeight + trackHeight,
         contentHeight: msaAreaHeight,
         trackHeight,
+        topHeight,
         offsetX: -scrollX,
         offsetY: -scrollY,
         includeMinimap,
@@ -147,7 +175,7 @@ export async function renderToSvg(model: MsaViewModel, opts: ExportSvgOptions) {
   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
+      return ctx ? `<g id="${id}">${ctx.getSvg().innerHTML}</g>` : match
     }),
   )
 }
@@ -165,15 +193,18 @@ function MsaSvg({
   layout: Layout
   layers: LayerMap
 }) {
-  const { width, trackHeight, includeMinimap, legendWidth } = layout
-  const { treeAreaWidth, minimapHeight, visibleDomainTypes } = model
+  const { width, trackHeight, includeMinimap, legendWidth, topHeight } = layout
+  const { treeAreaWidth, rowPanelsWidth } = model
   const totalWidth = width + legendWidth
-  const legendTop = includeMinimap ? minimapHeight : 0
-  // a short alignment with many domain types has a key taller than its rows,
+  const legendTop = topHeight
+  // a short alignment with many legend entries has a key taller than its rows,
   // and the page has to hold the whole key
   const height =
     legendWidth > 0
-      ? Math.max(layout.height, legendTop + legendHeight(visibleDomainTypes))
+      ? Math.max(
+          layout.height,
+          legendTop + legendHeight(legendRows(model.legends)),
+        )
       : layout.height
   const props = { Context, model, theme, layout, layers }
 
@@ -204,18 +235,37 @@ function MsaSvg({
         height="100%"
         fill={theme.palette.background.default}
       />
-      {includeMinimap ? (
+      {topHeight > 0 ? (
         <>
-          <g transform={`translate(${treeAreaWidth} 0)`}>
-            <MinimapSVG model={model} theme={theme} />
-          </g>
-          <g transform={`translate(0 ${minimapHeight})`}>{body}</g>
+          {includeMinimap ? (
+            <g
+              id="minimap-panel"
+              transform={`translate(${treeAreaWidth + rowPanelsWidth} 0)`}
+            >
+              <MinimapSVG model={model} theme={theme} />
+            </g>
+          ) : null}
+          <RowPanelHeadersSVG
+            model={model}
+            theme={theme}
+            bandHeight={topHeight}
+          />
+          {model.showTreeOverview ? (
+            <TreeOverviewSVG
+              model={model}
+              theme={theme}
+              Context={Context}
+              layers={layers}
+            />
+          ) : null}
+          <TreeScaleBarSVG model={model} theme={theme} />
+          <g transform={`translate(0 ${topHeight})`}>{body}</g>
         </>
       ) : (
         body
       )}
       {legendWidth > 0 ? (
-        <g transform={`translate(${width} ${legendTop})`}>
+        <g id="legend-panel" transform={`translate(${width} ${legendTop})`}>
           <LegendSVG model={model} theme={theme} width={legendWidth} />
         </g>
       ) : null}
@@ -223,8 +273,185 @@ function MsaSvg({
   )
 }
 
-// the domain color key drawn as a reserved column to the right of the
-// alignment, mirroring the on-screen AnnotationLegend overlay
+// The tree overview in the top band, over the tree column, where the live view
+// puts it. It is part of the figure rather than chrome: the inset is what says
+// where the focused clade sits in the whole tree.
+function TreeOverviewSVG({
+  model,
+  theme,
+  Context,
+  layers,
+}: {
+  model: MsaViewModel
+  theme: Theme
+  Context: typeof ContextType
+  layers: LayerMap
+}) {
+  const { treeAreaWidth, overviewHeight, id } = model
+  const ctx = new Context(treeAreaWidth, overviewHeight)
+  renderTreeOverview({
+    model,
+    ctx,
+    theme,
+    width: treeAreaWidth,
+    height: overviewHeight,
+  })
+  return (
+    <ClipGroup
+      panelId="tree-overview"
+      clipId={`tree-overview-${id}`}
+      width={treeAreaWidth}
+      height={overviewHeight}
+      ctx={ctx}
+      layers={layers}
+    />
+  )
+}
+
+// The branch-length scale bar under the tree overview, where the live view puts
+// it (see TreeRuler). A phylogram whose branch lengths are drawn to a scale
+// nothing states is a figure a reader cannot measure, so the export carries the
+// bar even though it is chrome on screen.
+function TreeScaleBarSVG({
+  model,
+  theme,
+}: {
+  model: MsaViewModel
+  theme: Theme
+}) {
+  const { marginLeft, treeScaleBar: bar, treeOverviewHeight } = model
+  if (!bar) {
+    return null
+  }
+  const y = treeOverviewHeight + treeScaleBarHeight
+  const color = theme.palette.text.primary
+  return (
+    <g id="tree-scalebar">
+      <text x={marginLeft} y={y - 9} fontSize={10} fill={color}>
+        {bar.label}
+      </text>
+      <path
+        d={`M${marginLeft} ${y - 7} v6 h${bar.px} v-6`}
+        fill="none"
+        stroke={color}
+      />
+    </g>
+  )
+}
+
+// Each strip's header over the column it names, turned on its side, where the
+// live view puts it (see RowPanelHeaders). The baseline runs up the figure, so
+// the name sits to the left of it, the way TrackLabelsSVG offsets a horizontal
+// baseline by a third of the font size.
+function RowPanelHeadersSVG({
+  model,
+  theme,
+  bandHeight,
+}: {
+  model: MsaViewModel
+  theme: Theme
+  bandHeight: number
+}) {
+  const { resolvedRowPanels, treeAreaWidth, fontSize } = model
+  const y = bandHeight - 4
+  return resolvedRowPanels.length === 0 ? null : (
+    <g id="rowpanel-headers">
+      {resolvedRowPanels.map(panel => {
+        const across = headerRunsAcross(panel.width)
+        const size = across ? fontSize : Math.min(fontSize, panel.width)
+        const center = treeAreaWidth + panel.offsetX + panel.width / 2
+        const x = across ? center : center + size / 3
+        const room = across ? panel.width : y - LEGEND_PAD
+        const maxChars = Math.floor(room / (size * CHAR_WIDTH))
+        return size < 5 ? null : (
+          <text
+            key={panel.id}
+            x={x}
+            y={y}
+            {...(across
+              ? { textAnchor: 'middle' }
+              : { transform: `rotate(-90 ${x} ${y})` })}
+            fontSize={size}
+            fill={theme.palette.text.primary}
+          >
+            {panel.header.length > maxChars
+              ? `${panel.header.slice(0, Math.max(1, maxChars - 1))}…`
+              : panel.header}
+          </text>
+        )
+      })}
+    </g>
+  )
+}
+
+// A label past the room it has, cut to what fits with an ellipsis. The measure
+// is the one cladeGutterWidth sizes the gutter with, so a label the gutter
+// holds keeps every character.
+function clipCladeLabel(label: string, room: number, fontSize: number) {
+  const width = measureTextCanvas(label, fontSize)
+  if (width <= room) {
+    return label
+  }
+  const fits = Math.floor((label.length * room) / width)
+  return `${label.slice(0, Math.max(1, fits - 1))}…`
+}
+
+// Each bracket's label in the gutter beside its bar, where the live view puts
+// it (see CladeLabels). The canvas layer draws the bar; a label longer than the
+// gutter or the clade is clipped, since text that overruns runs off the figure.
+function CladeLabelsSVG({
+  model,
+  theme,
+  offsetY,
+}: {
+  model: MsaViewModel
+  theme: Theme
+  offsetY: number
+}) {
+  const {
+    resolvedClades,
+    cladeGutterWidth,
+    rowHeight,
+    treeAreaWidth,
+    fontSize,
+  } = model
+  if (cladeGutterWidth === 0) {
+    return null
+  }
+  const gutterLeft = treeAreaWidth - cladeGutterWidth
+  return (
+    <g id="clade-labels">
+      {resolvedClades.map((clade, index) => {
+        const { label, markColor, rows } = clade
+        if (!label || !cladeInGutter(clade)) {
+          return null
+        }
+        const left = gutterLeft + cladeLabelOffset(clade)
+        const top = rows[0] * rowHeight - offsetY
+        const height = cladeHeight(clade, rowHeight)
+        const horizontal = cladeLabelHorizontal(clade, rowHeight, fontSize)
+        const room = horizontal ? treeAreaWidth - left - bracketGap : height
+        const x = horizontal ? left : left + fontSize
+        const y = horizontal ? top + height / 2 + fontSize / 3 : top + height
+        return (
+          <text
+            key={`${rows[0]}-${rows[1]}-${index}`}
+            x={x}
+            y={y}
+            transform={horizontal ? undefined : `rotate(-90 ${x} ${y})`}
+            fontSize={fontSize}
+            fill={markColor ?? theme.palette.text.primary}
+          >
+            {clipCladeLabel(label, room, fontSize)}
+          </text>
+        )
+      })}
+    </g>
+  )
+}
+
+// the color keys drawn as a reserved column to the right of the alignment,
+// mirroring the on-screen AnnotationLegend overlay
 function LegendSVG({
   model,
   theme,
@@ -234,8 +461,8 @@ function LegendSVG({
   theme: Theme
   width: number
 }) {
-  const { visibleDomainTypes, fillPalette, strokePalette } = model
-  const boxHeight = legendHeight(visibleDomainTypes)
+  const rows = legendRows(model.legends)
+  const boxHeight = legendHeight(rows)
   // the column is capped at LEGEND_MAX_W, so a name too long for it has to be
   // clipped here -- text that overruns the reserved width runs off the figure
   const maxChars = Math.floor(
@@ -252,27 +479,30 @@ function LegendSVG({
         stroke={theme.palette.divider}
         rx={2}
       />
-      {visibleDomainTypes.map((d, i) => {
+      {rows.map((row, i) => {
         const y = LEGEND_PAD + i * LEGEND_ROW_H
         return (
-          <g key={d.accession}>
-            <rect
-              x={LEGEND_PAD}
-              y={y}
-              width={LEGEND_SWATCH}
-              height={LEGEND_SWATCH}
-              fill={fillPalette[d.accession]}
-              stroke={strokePalette[d.accession]}
-            />
+          <g key={row.key}>
+            {row.color ? (
+              <rect
+                x={LEGEND_PAD}
+                y={y}
+                width={LEGEND_SWATCH}
+                height={LEGEND_SWATCH}
+                fill={row.color}
+                stroke={outlineColor(row.color)}
+              />
+            ) : null}
             <text
-              x={LEGEND_TEXT_X}
+              x={row.color ? LEGEND_TEXT_X : LEGEND_PAD}
               y={y + LEGEND_SWATCH - 1}
               fontSize={LEGEND_FONT}
+              fontWeight={row.color ? undefined : 'bold'}
               fill={theme.palette.text.primary}
             >
-              {d.name.length > maxChars
-                ? `${d.name.slice(0, Math.max(1, maxChars - 1))}…`
-                : d.name}
+              {row.label.length > maxChars
+                ? `${row.label.slice(0, Math.max(1, maxChars - 1))}…`
+                : row.label}
             </text>
           </g>
         )
@@ -293,7 +523,7 @@ interface LayerProps {
 
 function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
   const { contentHeight, offsetX, offsetY, msaAreaWidth } = layout
-  const { treeAreaWidth, id } = model
+  const { treeAreaWidth, rowPanelsWidth, id } = model
 
   const treeCtx = new Context(treeAreaWidth, contentHeight)
   renderTreeCanvas({
@@ -305,11 +535,26 @@ function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
     highResScaleFactorOverride: 1,
   })
 
+  const rowPanelsCtx = rowPanelsWidth
+    ? new Context(rowPanelsWidth, contentHeight)
+    : undefined
+  if (rowPanelsCtx) {
+    renderRowPanels({
+      model,
+      theme,
+      ctx: rowPanelsCtx,
+      offsetY,
+      blockSizeYOverride: contentHeight,
+      highResScaleFactorOverride: 1,
+    })
+  }
+
   const raster = rasterBackground({ model, theme, layout })
 
   const msaCtx = new Context(msaAreaWidth, contentHeight)
   renderBoxFeatureCanvasBlock({
     model,
+    theme,
     ctx: msaCtx,
     offsetX,
     offsetY,
@@ -344,17 +589,31 @@ function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
   return (
     <>
       <ClipGroup
+        panelId="tree-panel"
         clipId={`tree-${id}`}
         width={treeAreaWidth}
         height={contentHeight}
         ctx={treeCtx}
         layers={layers}
       />
+      <CladeLabelsSVG model={model} theme={theme} offsetY={offsetY} />
+      {rowPanelsCtx ? (
+        <ClipGroup
+          panelId="rowpanels-panel"
+          clipId={`rowpanels-${id}`}
+          width={rowPanelsWidth}
+          height={contentHeight}
+          transform={`translate(${treeAreaWidth} 0)`}
+          ctx={rowPanelsCtx}
+          layers={layers}
+        />
+      ) : null}
       <ClipGroup
+        panelId="msa-panel"
         clipId={`msa-${id}`}
         width={msaAreaWidth}
         height={contentHeight}
-        transform={`translate(${treeAreaWidth} 0)`}
+        transform={`translate(${treeAreaWidth + rowPanelsWidth} 0)`}
         ctx={msaCtx}
         layers={layers}
         underlay={raster}
@@ -364,15 +623,13 @@ function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
 }
 
 /**
- * The alignment background as a single <image>, on the same terms the live
- * canvas uses it: no domain overlay painting its own boxes, background coloring
- * on, and a canvas we can actually read back.
+ * The alignment background as a single <image>, under the live canvas's
+ * conditions: no domain overlay boxes, background coloring on, and a canvas
+ * that reads back.
  *
- * One node replaces the <rect>-per-cell the vector path emits, which is what
- * lets an export of a real alignment finish at all. The image is one pixel per
- * cell drawn across the cells' own rectangle, so it upscales by whole cells --
- * image-rendering keeps those edges hard rather than smearing them, making it
- * pixel-for-pixel what the rects drew.
+ * The vector path's <rect> per cell exhausts the heap on a real alignment. The
+ * image is one pixel per cell, and image-rendering keeps the upscaled cell
+ * edges hard, so it matches the rects pixel for pixel.
  */
 function rasterBackground({
   model,
@@ -423,7 +680,7 @@ function rasterBackground({
 
 function TrackRendering({ model, theme, layout, Context, layers }: LayerProps) {
   const { trackHeight, offsetX, msaAreaWidth } = layout
-  const { treeAreaWidth, id } = model
+  const { treeAreaWidth, rowPanelsWidth, id } = model
 
   const ctx = new Context(msaAreaWidth, trackHeight)
   renderAllTracks({
@@ -438,8 +695,9 @@ function TrackRendering({ model, theme, layout, Context, layers }: LayerProps) {
   return (
     <>
       <TrackLabelsSVG model={model} theme={theme} />
-      <g transform={`translate(${treeAreaWidth} 0)`}>
+      <g transform={`translate(${treeAreaWidth + rowPanelsWidth} 0)`}>
         <ClipGroup
+          panelId="tracks-panel"
           clipId={`tracks-${id}`}
           width={msaAreaWidth}
           height={trackHeight}
@@ -465,14 +723,17 @@ function TrackLabelsSVG({
   if (!drawLabels) {
     return null
   }
-  let y = 0
+  const labels = turnedOnTracks.map((track, i) => {
+    const { id, name, height } = track.model
+    const size = Math.min(height, fontSize)
+    const top = turnedOnTracks
+      .slice(0, i)
+      .reduce((acc, t) => acc + t.model.height, 0)
+    return { id, name, size, baseline: top + height / 2 + size / 3 }
+  })
   return (
     <>
-      {turnedOnTracks.map(track => {
-        const { id, name, height } = track.model
-        const size = Math.min(height, fontSize)
-        const baseline = y + height / 2 + size / 3
-        y += height
+      {labels.map(({ id, name, size, baseline }) => {
         return size < 5 ? null : (
           <text
             key={id}
@@ -493,7 +754,12 @@ function TrackLabelsSVG({
 // 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.
+//
+// `panelId` names the spliced group in the output, the same name in every
+// export, so a figure can be taken apart in Illustrator or svgutils. `clipId`
+// carries the model id, which keeps two viewers on one page from colliding.
 function ClipGroup({
+  panelId,
   clipId,
   width,
   height,
@@ -502,6 +768,7 @@ function ClipGroup({
   layers,
   underlay,
 }: {
+  panelId: string
   clipId: string
   width: number
   height: number
@@ -510,7 +777,7 @@ function ClipGroup({
   layers: LayerMap
   underlay?: React.ReactNode
 }) {
-  layers.set(clipId, ctx)
+  layers.set(panelId, ctx)
   return (
     <>
       <defs>
@@ -520,7 +787,7 @@ function ClipGroup({
       </defs>
       <g clipPath={`url(#${clipId})`} transform={transform}>
         {underlay}
-        <g data-layer={clipId} />
+        <g data-layer={panelId} />
       </g>
     </>
   )

package/src/rowCoordinateCalculations.ts

@@ -79,9 +79,8 @@ function countBlanksBefore(blanks: number[], globalCol: number) {
  * that is its own visible index; for a hidden one it is the index of the next
  * visible column, i.e. where the hidden column collapses to.
  *
- * That total answer is what spans want: resolving both ends of a span through
- * globalColToVisibleCol instead loses the whole span whenever either end lands
- * in a hidden column.
+ * Spans use this, since globalColToVisibleCol drops a span whenever either end
+ * lands in a hidden column.
  *
  * @param blanks - Sorted array of global column indices that are hidden
  * @param globalCol - The global column index in the full MSA
@@ -94,9 +93,8 @@ export function visibleColsBefore(blanks: number[], globalCol: number) {
  * 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.
  *
- * 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.
+ * Binary-searches the row's ascending seqPos index; it runs on every mouse
+ * move, and scanning a 30k-column row per event takes the whole frame.
  *
  * @param index - The row's seqPos -> global column index (buildSeqPosIndex)
  * @param globalCol - The global column index in the full MSA