jbrowse-plugin-msaview 3.0.0 → 3.2.0

package/src/MsaViewPanel/afterCreateAutoruns.ts

@@ -223,68 +223,123 @@ export function syncGenomeHoverToMsaColumn(self: JBrowsePluginMsaViewModel) {
 }
 
 /**
- * Mirror a connected 3D protein view's hovered residue onto the MSA's
- * highlighted columns. Returns the autorun body and keeps a flag tracking
- * whether the current highlight was set by THIS sync: when a protein hover ends
- * we restore the declarative highlightColumns seed (or clear) rather than
- * blindly wiping it.
+ * Translate genome regions published by a 3D protein view into this MSA's
+ * visible columns. The genome is the only coordinate space the two plugins
+ * share, so the hops are genome coord -> protein position (the transcript's g2p
+ * map) -> global alignment column -> visible column.
+ */
+function genomeHighlightsToVisibleColumns(
+  self: JBrowsePluginMsaViewModel,
+  field: 'hoverGenomeHighlights' | 'clickGenomeHighlights',
+) {
+  const { connectedViewId, transcriptToMsaMap, querySeqName } = self
+  if (!transcriptToMsaMap) {
+    return []
+  }
+  const { g2p } = transcriptToMsaMap
+  const columns = new Set<number>()
+
+  for (const view of getProteinViews(getSession(self).views)) {
+    for (const structure of view.structures) {
+      if (structure.connectedViewId !== connectedViewId) {
+        continue
+      }
+      for (const highlight of structure[field] ?? []) {
+        for (let coord = highlight.start; coord < highlight.end; coord++) {
+          const proteinPos = g2p[coord]
+          if (proteinPos !== undefined) {
+            columns.add(self.seqPosToGlobalCol(querySeqName, proteinPos))
+          }
+        }
+      }
+    }
+  }
+
+  return [...columns]
+    .map(col => self.globalColToVisibleCol(col))
+    .filter((col): col is number => col !== undefined)
+}
+
+function sameColumns(a: number[] | undefined, b: number[] | undefined) {
+  if (!a || !b) {
+    return a === b
+  }
+  return a.length === b.length && a.every((col, i) => col === b[i])
+}
+
+/**
+ * Mirror a connected 3D protein view's highlights onto the MSA's highlighted
+ * columns, from either of the two channels protein3d publishes:
+ *
+ * - `hoverGenomeHighlights` — the residue under the pointer, transient.
+ * - `clickGenomeHighlights` — the domain the user clicked, persistent. Also
+ *   what protein3d's declarative `initialSelection` lights on load, so a session
+ *   spec that pre-selects a domain in the structure now lands in the alignment
+ *   too, instead of the caller having to author the same range a second time as
+ *   the MSA's own `highlightColumns`.
+ *
+ * Highest-priority non-empty source wins: a hover reads as a transient probe on
+ * top of the standing selection, and letting it win means moving the pointer
+ * over the structure previews a residue without destroying what was selected.
+ * Releasing the hover falls back to the click selection, then to the declarative
+ * `highlightColumns` seed.
  *
- * Without the flag this autorun fires once on creation — with the view connected
- * to a *genome* LGV but no 3D protein structure attached — computes zero columns,
- * and calls setHighlightedColumns(undefined), clobbering the seed that
- * MSAModelF.afterCreate just set from the declarative `highlightColumns`. That is
- * the bug that made the BRAF/TP53 genome-browser links open with no V600/R248
- * column lit (SRC has no highlightColumns, so nothing was there to wipe).
+ * Resolving the seed as the last rung of that stack is what replaced a
+ * `proteinDriven` flag this function used to carry. The flag existed because the
+ * body could not otherwise tell "no protein highlight, leave the seed alone"
+ * from "the protein highlight ended, restore the seed", and getting that wrong
+ * wiped the seed on the very first run — the bug that made the BRAF/TP53
+ * genome-browser links open with no V600/R248 column lit. Now every source is in
+ * one expression, so the result depends only on what the sources currently say
+ * and there is no ordering to get wrong.
+ *
+ * A closure remains, but it decides nothing: `written` only suppresses a
+ * redundant redraw. Delete it and the highlight is identical, just recomputed
+ * more often — where deleting the old flag changed which columns lit.
  */
 export function observeProteinHighlights(self: JBrowsePluginMsaViewModel) {
-  let proteinDriven = false
+  // The columns this reaction last wrote, kept to skip a write that would not
+  // change anything: protein3d recomputes hoverGenomeHighlights on every mouse
+  // move over the structure, and moving within one codon yields a fresh array of
+  // the same columns, which would redraw the overlay canvas for nothing.
+  //
+  // Deliberately a closure rather than a read of `self.highlightedColumns` --
+  // reading it would put this reaction's own output in its dependency set, so
+  // every write would re-trigger it. It converges, but the dependencies should be
+  // the sources the highlight derives FROM, not the highlight itself.
+  let written: number[] | undefined
   return () => {
-    const { connectedViewId, transcriptToMsaMap, querySeqName } = self
+    const { connectedViewId, transcriptToMsaMap } = self
 
     if (!connectedViewId || !transcriptToMsaMap) {
       return
     }
 
-    const columns = new Set<number>()
-
-    for (const view of getProteinViews(getSession(self).views)) {
-      for (const structure of view.structures) {
-        if (structure.connectedViewId !== connectedViewId) {
-          continue
-        }
-
-        const highlights = structure.hoverGenomeHighlights
-        if (!highlights || highlights.length === 0) {
-          continue
-        }
-
-        const { g2p } = transcriptToMsaMap
-        for (const highlight of highlights) {
-          for (let coord = highlight.start; coord < highlight.end; coord++) {
-            const proteinPos = g2p[coord]
-            if (proteinPos !== undefined) {
-              const col = self.seqPosToGlobalCol(querySeqName, proteinPos)
-              columns.add(col)
-            }
-          }
-        }
-      }
-    }
+    const hover = genomeHighlightsToVisibleColumns(
+      self,
+      'hoverGenomeHighlights',
+    )
+    // Skipping the click channel while hovering is worth the subtlety it costs:
+    // a hover recomputes on every mouse move, and a clicked domain can be
+    // hundreds of residues, so translating a selection that cannot win would
+    // walk thousands of genome coordinates per pointer move.
+    //
+    // The subtlety is that not reading clickGenomeHighlights leaves it out of
+    // this reaction's dependencies until the hover clears. Changing the
+    // selection mid-hover therefore does not re-run us -- which is harmless,
+    // because the hover would have outranked it anyway, and releasing the hover
+    // re-runs and picks up whatever the selection now says.
+    const click = hover.length
+      ? []
+      : genomeHighlightsToVisibleColumns(self, 'clickGenomeHighlights')
+    const seed = self.highlightColumns ?? []
 
-    const visibleColumns = Array.from(columns)
-      .map(col => self.globalColToVisibleCol(col))
-      .filter((col): col is number => col !== undefined)
+    const winner = hover.length ? hover : click.length ? click : seed
+    const next = winner.length > 0 ? winner : undefined
 
-    if (visibleColumns.length > 0) {
-      self.setHighlightedColumns(visibleColumns)
-      proteinDriven = true
-    } else if (proteinDriven) {
-      // our protein-hover highlight ended — fall back to the declarative seed
-      // instead of wiping a column the URL/user asked to keep lit
-      self.setHighlightedColumns(
-        self.highlightColumns?.length ? self.highlightColumns : undefined,
-      )
-      proteinDriven = false
+    if (!sameColumns(written, next)) {
+      written = next
+      self.setHighlightedColumns(next)
     }
   }
 }

package/src/MsaViewPanel/observeProteinHighlights.test.ts

@@ -0,0 +1,264 @@
+import { getSession } from '@jbrowse/core/util'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { observeProteinHighlights } from './afterCreateAutoruns'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+
+// Mock only getSession; keep the rest of the util module real so the
+// afterCreateAutoruns import graph still loads.
+vi.mock('@jbrowse/core/util', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  getSession: vi.fn(),
+}))
+
+const mockGetSession = vi.mocked(getSession)
+
+const CONNECTED = 'lgv-1'
+
+interface Range {
+  start: number
+  end: number
+}
+
+/**
+ * A model with an identity genome->protein->column mapping, so an asserted
+ * column equals the genome coordinate that produced it and the test reads as
+ * "these genome coords lit these columns".
+ */
+function makeModel({ highlightColumns }: { highlightColumns?: number[] } = {}) {
+  const calls: (number[] | undefined)[] = []
+  const model = {
+    querySeqName: 'query',
+    connectedViewId: CONNECTED,
+    // g2p is indexed by genome coord; identity keeps the arithmetic out of the way
+    transcriptToMsaMap: {
+      g2p: Object.fromEntries([...Array(200).keys()].map(i => [i, i])),
+    },
+    highlightColumns,
+    highlightedColumns: undefined as number[] | undefined,
+    seqPosToGlobalCol: (_name: string, pos: number) => pos,
+    globalColToVisibleCol: (col: number) => col,
+    setHighlightedColumns: (cols?: number[]) => {
+      calls.push(cols)
+      model.highlightedColumns = cols
+    },
+  } as unknown as JBrowsePluginMsaViewModel & {
+    highlightedColumns: number[] | undefined
+  }
+  return { model, calls }
+}
+
+/** publish highlight channels on a ProteinView structure in the session */
+function session({
+  hover,
+  click,
+  connectedViewId = CONNECTED,
+}: {
+  hover?: Range[]
+  click?: Range[]
+  connectedViewId?: string
+}) {
+  mockGetSession.mockReturnValue({
+    views: [
+      {
+        type: 'ProteinView',
+        id: 'pv-1',
+        structures: [
+          {
+            connectedViewId,
+            hoverGenomeHighlights: hover,
+            clickGenomeHighlights: click,
+          },
+        ],
+      },
+    ],
+  } as unknown as ReturnType<typeof getSession>)
+}
+
+function noProteinView() {
+  mockGetSession.mockReturnValue({
+    views: [{ type: 'LinearGenomeView', id: CONNECTED }],
+  } as unknown as ReturnType<typeof getSession>)
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('the hover channel', () => {
+  test('a hovered residue lights its column', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({ hover: [{ start: 10, end: 13 }] })
+    run()
+    expect(calls).toEqual([[10, 11, 12]])
+  })
+
+  test('releasing the hover clears the highlight', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({ hover: [{ start: 10, end: 12 }] })
+    run()
+    session({ hover: [] })
+    run()
+    expect(calls).toEqual([[10, 11], undefined])
+  })
+})
+
+describe('the click channel', () => {
+  test('a clicked domain lights its columns', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({ click: [{ start: 30, end: 34 }] })
+    run()
+    expect(calls).toEqual([[30, 31, 32, 33]])
+  })
+
+  test('a hover wins over the standing click selection', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] })
+    run()
+    expect(calls).toEqual([[5]])
+  })
+
+  test('a selection changed during a hover is picked up when the hover releases', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    // the reaction skips the click channel while hovering, so it is not watching
+    // it; this pins that releasing the hover still lands on the CURRENT selection
+    // rather than on the one that was standing when the hover began
+    session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] })
+    run()
+    session({ click: [{ start: 60, end: 62 }], hover: [{ start: 5, end: 6 }] })
+    run()
+    session({ click: [{ start: 60, end: 62 }] })
+    run()
+    expect(calls).toEqual([[5], [60, 61]])
+  })
+
+  test('releasing the hover falls back to the click selection, not to nothing', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    // this is the whole point of the two channels: previewing a residue must not
+    // destroy the domain the user selected
+    session({ click: [{ start: 30, end: 32 }] })
+    run()
+    session({ click: [{ start: 30, end: 32 }], hover: [{ start: 5, end: 6 }] })
+    run()
+    session({ click: [{ start: 30, end: 32 }] })
+    run()
+    expect(calls).toEqual([[30, 31], [5], [30, 31]])
+  })
+})
+
+describe('the declarative highlightColumns seed', () => {
+  // the regression these guard: the observer used to compute zero columns on its
+  // first run and wipe the seed MSAModelF.afterCreate had just applied, which is
+  // what made the BRAF/TP53 links open with no V600/R248 column lit
+  test('a first run with no protein view leaves the seed alone', () => {
+    const { model, calls } = makeModel({ highlightColumns: [77] })
+    const run = observeProteinHighlights(model)
+
+    noProteinView()
+    run()
+    expect(calls).toEqual([[77]])
+    expect(model.highlightedColumns).toEqual([77])
+  })
+
+  test('repeated runs never clobber the seed', () => {
+    const { model } = makeModel({ highlightColumns: [77] })
+    const run = observeProteinHighlights(model)
+
+    noProteinView()
+    run()
+    run()
+    run()
+    expect(model.highlightedColumns).toEqual([77])
+  })
+
+  test('a hover overrides the seed, and releasing it restores the seed', () => {
+    const { model, calls } = makeModel({ highlightColumns: [77] })
+    const run = observeProteinHighlights(model)
+
+    session({ hover: [{ start: 1, end: 2 }] })
+    run()
+    session({ hover: [] })
+    run()
+    expect(calls).toEqual([[1], [77]])
+  })
+
+  test('a click selection outranks the seed', () => {
+    const { model, calls } = makeModel({ highlightColumns: [77] })
+    const run = observeProteinHighlights(model)
+
+    session({ click: [{ start: 40, end: 42 }] })
+    run()
+    expect(calls).toEqual([[40, 41]])
+  })
+
+  test('with no seed and no protein highlight, nothing is written at all', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    noProteinView()
+    run()
+    run()
+    expect(calls).toEqual([])
+  })
+})
+
+describe('scope and redundant writes', () => {
+  test('a structure connected to a different view is ignored', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({
+      hover: [{ start: 10, end: 12 }],
+      connectedViewId: 'some-other-view',
+    })
+    run()
+    expect(calls).toEqual([])
+  })
+
+  test('an unchanged highlight is not rewritten, so the overlay does not redraw', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    session({ hover: [{ start: 10, end: 12 }] })
+    run()
+    run()
+    run()
+    expect(calls).toEqual([[10, 11]])
+  })
+
+  test('a genome coord with no protein position contributes no column', () => {
+    const { model, calls } = makeModel()
+    const run = observeProteinHighlights(model)
+
+    // 500 is past the end of the identity g2p map built above
+    session({ hover: [{ start: 500, end: 503 }] })
+    run()
+    expect(calls).toEqual([])
+  })
+
+  test('nothing happens until the view is connected and mapped', () => {
+    const { calls } = makeModel()
+    const bare = {
+      connectedViewId: undefined,
+      transcriptToMsaMap: undefined,
+    } as unknown as JBrowsePluginMsaViewModel
+    const run = observeProteinHighlights(bare)
+
+    session({ hover: [{ start: 10, end: 12 }] })
+    run()
+    expect(calls).toEqual([])
+  })
+})

package/src/MsaViewPanel/structureConnection.ts

@@ -1,9 +1,16 @@
+// Structurally typed against jbrowse-plugin-protein3d rather than imported from
+// it: the two plugins ship independently, so a field the installed protein3d
+// lacks reads as undefined instead of failing to resolve. Both highlight
+// channels have been on its structure model since v0.4.0.
 export interface ProteinViewStructure {
   url?: string
   connectedViewId?: string
   uniprotId?: string
   structureSequences?: string[]
+  /** the residue under the pointer, transient */
   hoverGenomeHighlights?: { start: number; end: number }[]
+  /** the clicked domain, persistent; also what `initialSelection` lights */
+  clickGenomeHighlights?: { start: number; end: number }[]
 }
 
 export interface ProteinView {

package/src/index.ts

@@ -9,6 +9,7 @@ import BgzipFastaMsaAdapterF from './BgzipFastaMsaAdapter'
 import LaunchMsaViewF from './LaunchMsaView'
 import LaunchMsaViewExtensionPointF from './LaunchMsaViewExtensionPoint'
 import MsaViewF from './MsaViewPanel'
+import { launchMsaView } from './utils/launchMsaView'
 import { version } from './version'
 
 import type PluginManager from '@jbrowse/core/PluginManager'
@@ -32,7 +33,9 @@ export default class MsaViewPlugin extends Plugin {
         label: 'Multiple sequence alignment view',
         icon: GridOn,
         onClick: (session: AbstractSessionModel) => {
-          session.addView('MsaView', {})
+          // stacked, by default: nothing was launched from, so there is no
+          // connected view for it to sit beside
+          launchMsaView(session, {})
         },
       })
     }

package/src/utils/launchMsaView.ts

@@ -0,0 +1,30 @@
+import { placeMsaView } from './workspaces'
+
+import type { MsaViewPlacement } from './workspaces'
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+/**
+ * A launch, stated: what the view is, and where it goes. Everything but
+ * `placement` is a react-msaview or plugin-model snapshot property, passed
+ * through untouched so this never becomes a list that has to grow.
+ */
+export interface MsaViewLaunchSpec extends Record<string, unknown> {
+  /** default `stack`, the only thing an embedded session can do */
+  placement?: MsaViewPlacement
+}
+
+/**
+ * The one place a launch adds an MSA view -- the dialog's four tabs, the Add
+ * menu, and the `LaunchView-MsaView` extension point a session spec arrives on
+ * all come through here. Each of them used to run its own `addView` and none
+ * placed the result, which is how a launch from a gene feature landed stacked
+ * under the very genome view it was connected to.
+ */
+export function launchMsaView(
+  session: AbstractSessionModel,
+  { placement = 'stack', ...snapshot }: MsaViewLaunchSpec,
+) {
+  const view = session.addView('MsaView', { type: 'MsaView', ...snapshot })
+  placeMsaView(session, view.id, placement)
+  return view
+}

package/src/utils/workspaces.test.ts

@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import { launchMsaView } from './launchMsaView'
+import {
+  DEFAULT_LAUNCH_PLACEMENT,
+  LAUNCH_PLACEMENT_KEY,
+  placeMsaView,
+  readLaunchPlacement,
+  resetWorkspacesWarning,
+  sessionSupportsPlacement,
+  writeLaunchPlacement,
+} from './workspaces'
+
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+interface Recorded {
+  moves: unknown[]
+  workspaces: boolean[]
+  added: { type: string; snapshot: Record<string, unknown> }[]
+}
+
+function makeSession({
+  canPlace = true,
+  canEnable = true,
+}: { canPlace?: boolean; canEnable?: boolean } = {}) {
+  const recorded: Recorded = { moves: [], workspaces: [], added: [] }
+  const session: Record<string, unknown> = {
+    addView(type: string, snapshot: Record<string, unknown>) {
+      recorded.added.push({ type, snapshot })
+      return { id: `view-${recorded.added.length}` }
+    },
+  }
+  if (canPlace) {
+    session.setPendingMove = (move: unknown) => recorded.moves.push(move)
+  }
+  if (canEnable) {
+    session.setUseWorkspaces = (on: boolean) => recorded.workspaces.push(on)
+  }
+  return { session: session as unknown as AbstractSessionModel, recorded }
+}
+
+// node has no localStorage, and the plugin runs in a browser -- a Map-backed
+// stub keeps read/write round-tripping without pulling in jsdom
+function stubStorage() {
+  const store = new Map<string, string>()
+  vi.stubGlobal('localStorage', {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem: (key: string, value: string) => store.set(key, value),
+  })
+}
+
+beforeEach(() => {
+  resetWorkspacesWarning()
+  stubStorage()
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+})
+
+test('stack places nothing, on a host that could tile', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'stack')
+  expect(recorded.moves).toEqual([])
+  expect(recorded.workspaces).toEqual([])
+})
+
+test('splitRight asks for the move, then turns workspaces on', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'splitRight')
+  expect(recorded.moves).toEqual([{ type: 'splitRight', viewId: 'view-1' }])
+  expect(recorded.workspaces).toEqual([true])
+})
+
+test('newTab is the same path with the other move type', () => {
+  const { session, recorded } = makeSession()
+  placeMsaView(session, 'view-1', 'newTab')
+  expect(recorded.moves).toEqual([{ type: 'newTab', viewId: 'view-1' }])
+})
+
+// an embedded session has no workspaces at all, so there is nothing to report
+test('a session with neither action is a silent no-op', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const { session, recorded } = makeSession({
+    canPlace: false,
+    canEnable: false,
+  })
+  placeMsaView(session, 'view-1', 'splitRight')
+  expect(recorded.moves).toEqual([])
+  expect(warn).not.toHaveBeenCalled()
+  expect(sessionSupportsPlacement(session)).toBe(false)
+})
+
+// the shape that broke jbrowse-plugin-protein3d silently: workspaces are there,
+// the action this plugin reaches for is not
+test('a half-supported host warns once and stacks', () => {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  const { session, recorded } = makeSession({ canPlace: false })
+  placeMsaView(session, 'view-1', 'splitRight')
+  placeMsaView(session, 'view-2', 'splitRight')
+  expect(recorded.moves).toEqual([])
+  expect(warn).toHaveBeenCalledTimes(1)
+  expect(warn.mock.calls[0]?.[0]).toContain('setPendingMove')
+})
+
+test('the dialog default is side-by-side, and a junk value falls back to it', () => {
+  expect(DEFAULT_LAUNCH_PLACEMENT).toBe('splitRight')
+  expect(readLaunchPlacement()).toBe('splitRight')
+  localStorage.setItem(LAUNCH_PLACEMENT_KEY, 'sideways')
+  expect(readLaunchPlacement()).toBe('splitRight')
+  writeLaunchPlacement('stack')
+  expect(readLaunchPlacement()).toBe('stack')
+})
+
+test('launchMsaView defaults to stack, so a spec written before placement existed is unchanged', () => {
+  const { session, recorded } = makeSession()
+  launchMsaView(session, { data: { msa: '>a\nAC' } })
+  expect(recorded.added).toEqual([
+    { type: 'MsaView', snapshot: { type: 'MsaView', data: { msa: '>a\nAC' } } },
+  ])
+  expect(recorded.moves).toEqual([])
+})
+
+// placement is a launch instruction, not view state: MST would drop it from the
+// snapshot without a word, and the view would land stacked with nothing said
+test('launchMsaView keeps placement out of the view snapshot', () => {
+  const { session, recorded } = makeSession()
+  launchMsaView(session, { placement: 'splitRight', colWidth: 10 })
+  expect(recorded.added[0]?.snapshot).toEqual({ type: 'MsaView', colWidth: 10 })
+  expect(recorded.moves).toEqual([{ type: 'splitRight', viewId: 'view-1' }])
+})