jbrowse-plugin-msaview 3.0.0 → 3.1.0

package/dist/MsaViewPanel/afterCreateAutoruns.js

@@ -212,60 +212,109 @@ export function syncGenomeHoverToMsaColumn(self) {
     };
 }
 /**
- * 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, field) {
+    const { connectedViewId, transcriptToMsaMap, querySeqName } = self;
+    if (!transcriptToMsaMap) {
+        return [];
+    }
+    const { g2p } = transcriptToMsaMap;
+    const columns = new Set();
+    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 !== undefined);
+}
+function sameColumns(a, b) {
+    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) {
-    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;
     return () => {
-        const { connectedViewId, transcriptToMsaMap, querySeqName } = self;
+        const { connectedViewId, transcriptToMsaMap } = self;
         if (!connectedViewId || !transcriptToMsaMap) {
             return;
         }
-        const columns = new Set();
-        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 visibleColumns = Array.from(columns)
-            .map(col => self.globalColToVisibleCol(col))
-            .filter((col) => col !== 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;
+        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 winner = hover.length ? hover : click.length ? click : seed;
+        const next = winner.length > 0 ? winner : undefined;
+        if (!sameColumns(written, next)) {
+            written = next;
+            self.setHighlightedColumns(next);
         }
     };
 }

package/dist/MsaViewPanel/observeProteinHighlights.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/MsaViewPanel/observeProteinHighlights.test.js

@@ -0,0 +1,209 @@
+import { getSession } from '@jbrowse/core/util';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import { observeProteinHighlights } from './afterCreateAutoruns';
+// 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()),
+    getSession: vi.fn(),
+}));
+const mockGetSession = vi.mocked(getSession);
+const CONNECTED = 'lgv-1';
+/**
+ * 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 } = {}) {
+    const calls = [];
+    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,
+        seqPosToGlobalCol: (_name, pos) => pos,
+        globalColToVisibleCol: (col) => col,
+        setHighlightedColumns: (cols) => {
+            calls.push(cols);
+            model.highlightedColumns = cols;
+        },
+    };
+    return { model, calls };
+}
+/** publish highlight channels on a ProteinView structure in the session */
+function session({ hover, click, connectedViewId = CONNECTED, }) {
+    mockGetSession.mockReturnValue({
+        views: [
+            {
+                type: 'ProteinView',
+                id: 'pv-1',
+                structures: [
+                    {
+                        connectedViewId,
+                        hoverGenomeHighlights: hover,
+                        clickGenomeHighlights: click,
+                    },
+                ],
+            },
+        ],
+    });
+}
+function noProteinView() {
+    mockGetSession.mockReturnValue({
+        views: [{ type: 'LinearGenomeView', id: CONNECTED }],
+    });
+}
+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,
+        };
+        const run = observeProteinHighlights(bare);
+        session({ hover: [{ start: 10, end: 12 }] });
+        run();
+        expect(calls).toEqual([]);
+    });
+});

package/dist/MsaViewPanel/structureConnection.d.ts

@@ -3,10 +3,16 @@ export interface ProteinViewStructure {
     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 {
     type: 'ProteinView';