jbrowse-plugin-msaview 3.6.0 → 3.7.1

package/README.md

@@ -1,19 +1,28 @@
 # jbrowse-plugin-msaview
 
-This plugin packages https://github.com/gmod/react-msaview for usage inside of
-JBrowse 2
-
-See the docs for the react-msaview for more info
-https://github.com/GMOD/react-msaview/blob/main/docs/user_guide.md
+A multiple sequence alignment and phylogenetic tree viewer for JBrowse 2, linked
+column by column to the genome. It packages
+[react-msaview](https://github.com/GMOD/react-msaview), whose
+[user guide](https://github.com/GMOD/react-msaview/blob/main/docs/user_guide.md)
+covers the viewer itself.
 
 ## Gallery
 
 ![](img/1.png)
 
-MSAView plugin running in JBrowse 2
+The [demo](#demo) below: TP53 in the genome view beside a vertebrate p53
+alignment carrying per-residue variant tracks. Each release recaptures it with
+`pnpm readme-figure`.
 
 ## Demo
 
+[p53 across vertebrates, linked to the genome and the structure](https://jbrowse.org/code/jb2/main/?config=https://jbrowse.org/ucsc/hg38/config.json&session=spec-{%22views%22:[{%22type%22:%22LinearGenomeView%22,%22id%22:%22lgv1%22,%22assembly%22:%22hg38%22,%22loc%22:%22chr17:7,661,779-7,687,538%22,%22tracks%22:[%22hg38-ncbiRefSeqSelect%22]},{%22type%22:%22MsaView%22,%22displayName%22:%22p53%20across%20vertebrates%22,%22msa%22:%22https://gmod.org/JBrowseMSA/demo/data/p53/p53-vertebrates.afa%22,%22tree%22:%22https://gmod.org/JBrowseMSA/demo/data/p53/p53-vertebrates.nh%22,%22query%22:%22Human%22,%22connectedViewId%22:%22lgv1%22,%22connectedTranscript%22:%22NM_000546.6%22,%22placement%22:%22splitRight%22,%22colorSchemeName%22:%22clustalx_protein_dynamic%22,%22highlights%22:[{%22start%22:102,%22end%22:292,%22label%22:%22DNA-binding%22,%22color%22:%22rgba%28255,140,0,0.15%29%22},175,245,248,249,273,282],%22region%22:%22170-290%22,%22columnTracks%22:[{%22name%22:%22ClinVar%20pathogenic%20missense%22,%22color%22:%22%23c0392b%22,%22max%22:8,%22start%22:105,%22values%22:[2,1,0,0,2,4,3,0,6,0,0,0,0,0,0,0,0,0,0,1,2,1,5,0,0,2,2,3,1,1,4,0,0,2,0,0,2,0,3,0,0,0,1,0,0,0,6,2,0,0,1,1,3,6,2,0,1,0,2,1,1,0,0,2,0,0,2,1,3,0,3,3,1,3,5,1,3,0,0,0,0,0,0,0,0,1,0,0,4,3,1,1,1,0,1,0,0,0,0,0,3,0,0,0,0,0,0,0,3,2,1,1,0,1,0,3,0,0,0,0,0,0,0,0,0,0,0,3,0,4,0,2,4,6,2,3,5,2,0,4,5,4,1,6,2,1,2,0,1,3,0,0,0,2,1,0,0,0,0,0,2,3,3,0,1,4,1,3,6,0,2,1,1,3,0,3,8,3,1,0,2,2,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,1,0,1,0,0,5,0,0,0,1,1,0,2,0,0,1]},{%22name%22:%22AlphaMissense%20mean%20%28x100%29%22,%22color%22:%22%231565c0%22,%22max%22:100,%22values%22:[49,27,19,11,12,14,18,10,12,14,28,17,40,57,73,65,65,68,95,29,30,72,95,21,24,60,39,21,18,17,18,16,17,12,11,13,14,13,14,21,22,20,17,20,16,16,15,14,17,17,15,13,37,29,11,19,16,11,11,12,14,20,14,12,11,20,13,19,15,14,12,13,15,17,14,17,15,19,20,17,15,15,22,22,19,22,20,24,17,23,67,41,46,66,63,37,90,98,63,35,36,20,76,15,99,13,58,48,98,26,81,57,97,43,17,64,87,68,90,98,96,92,73,81,98,91,95,23,13,81,56,97,84,97,98,87,86,81,91,84,94,93,89,66,81,57,77,26,20,13,90,69,17,52,70,49,91,98,87,88,94,87,95,89,48,54,52,76,76,68,92,87,98,78,99,100,98,97,100,96,85,50,38,52,32,74,52,32,83,87,71,47,99,95,89,95,91,96,95,81,20,25,69,48,98,24,64,93,17,23,84,56,99,92,91,93,70,89,76,91,77,27,92,87,57,92,58,35,54,68,75,87,85,87,74,93,96,100,95,98,99,100,94,100,100,98,97,100,99,93,93,59,91,91,87,92,93,99,87,22,21,94,24,76,83,99,98,36,61,97,93,93,99,95,100,97,100,100,99,100,100,97,84,60,98,96,47,62,13,18,56,34,17,17,11,9,9,16,11,15,13,18,20,17,81,75,26,26,23,13,12,14,16,18,18,14,15,15,47,54,46,19,13,34,24,50,56,88,36,87,48,93,63,98,73,40,89,90,45,60,88,51,36,81,77,55,79,75,87,31,54,67,23,18,17,16,25,22,13,15,15,16,20,18,15,20,25,13,15,56,21,47,45,21,16,16,15,21,16,20,66,47,13,26,19,66,13,28,18,16,47,54,66]},{%22name%22:%22MaveDB%20nutlin-3,%20p53WT%22,%22color%22:%22%232e7d32%22,%22max%22:2,%22start%22:27,%22values%22:[0.6,0,0.1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0.1,0,0,0.2,0.4,0,0,0,0,0.1,0,0.8,0,0.7,0.3,1.6,0.1,1.4,0.1,1.3,0,0,0,0.1,0,0.1,0.5,0.2,0.4,0.4,0.8,0.8,1.4,1.5,0.1,0.1,1.2,1,1.7,1.1,1.4,1.3,0.8,0.5,0.5,0.8,0.4,1.2,0.4,1.4,0.7,1.2,0.6,1.1,0.5,0.4,0.6,1.5,1.3,0,0.7,1.3,0.3,1.4,1,1.4,0.8,1.4,0.8,1.8,0.8,0.3,0,0.2,0.8,0.4,0,0.6,0.7,1.7,1,1.2,2,1.1,0.6,2,0.8,0.7,0.3,0.1,0.4,0.2,0.3,0.1,0.1,0.5,0.8,0.1,0.1,1.4,1.6,1.4,0.7,1.3,0.1,0.1,0,0,0,0.9,0.3,1.8,0,0,1,0,0.1,0.9,0.7,1.2,1.1,1.5,1.4,0.6,1.3,0.5,1.5,0.4,0.3,0.6,0.3,0.1,0.4,0.3,0.2,0.7,0.5,0.6,1.4,0.5,1.4,0.6,1.7,1.1,1.9,0.8,1.3,1.3,1.7,0.9,1.7,2.2,2,0.9,1.5,2.1,1,1.4,0.3,1.3,1.2,1.4,0.8,1.4,1.4,0.9,0.5,0.5,0.7,0.5,0.5,0.8,1.6,1,0.9,0.8,1.5,1.3,1.5,1.5,1.7,1.8,0.5,0.4,2,0,0.9,0.6,1,0,0,1,1.8,0,0.1,0.2,0.1,0.2,0,0.1,0.4,0.4,0.3,0.4,0.6,0.4,0.6,0.5]}]},{%22type%22:%22ProteinView%22,%22uniprotId%22:%22P04637%22,%22transcriptId%22:%22NM_000546.6%22,%22connectedViewId%22:%22lgv1%22,%22connectedView%22:{%22assembly%22:%22hg38%22,%22loc%22:%22chr17:7,661,779-7,687,538%22,%22tracks%22:[%22hg38-ncbiRefSeqSelect%22]}}]}):
+TP53 in hg38, a vertebrate p53 alignment carrying ClinVar, AlphaMissense and
+MaveDB per-residue tracks, and the AlphaFold model of P04637. Hovering a codon,
+a column or a residue lights the other two views.
+[Launching](docs/launching.md#the-readme-demo-taken-apart) takes the link apart.
+
+An older shared session:
 https://jbrowse.org/code/jb2/main/index.html?config=https://unpkg.com/jbrowse-plugin-msaview/dist/config.json&session=share-BVmmEYAoAv&password=SuQaN
 
 ## Features
@@ -35,7 +44,7 @@ https://jbrowse.org/code/jb2/main/index.html?config=https://unpkg.com/jbrowse-pl
 - Aligns and builds trees in the browser, so a UniRef launch needs no job at any
   external service; EBI's aligners remain an option
 - Every launch is also a session-spec URL (`orthologParams`, `searchParams`,
-  `connectedTranscript`), see [DEVELOPERS.md](DEVELOPERS.md)
+  `connectedTranscript`), see [launching](docs/launching.md)
 
 ## File format supports
 
@@ -46,30 +55,43 @@ https://jbrowse.org/code/jb2/main/index.html?config=https://unpkg.com/jbrowse-pl
 - Clustal files (e.g. .aln file, uses clustal-js parser)
 - Newick (tree can be loaded separately as a .nh file)
 
-## Publication
+## Availability
 
-If you find this tool useful please cite our work
+This plugin is installed by default on https://genomes.jbrowse.org so you can
+use it on any species there
 
-Diesh, C., Stevens, G., Bridge, C., Hogue, G., Buels, R., Cain, S., Stein, L., &
-Holmes, I. (2026). Proteins in the Genome Browser: Integration of Phylogenies,
-Alignments, and Structures With Nucleotide-level Evidence in JBrowse 2. Journal
-of Molecular Biology, 169645. https://doi.org/10.1016/j.jmb.2026.169645
+## Documentation
 
-See also https://github.com/GMOD/proteinbrowser for overview
+Using the plugin:
 
-## Availability
+- [Alignments from a gene](docs/alignments-from-a-gene.md): the launch dialog's
+  sources — NCBI, PANTHER and UniRef orthologs, EBI searches — and aligning in
+  the browser.
+- [Your own alignments](docs/your-own-alignments.md): opening an alignment you
+  made, from a file, a link, or a per-gene dataset a site configures.
+- [BLAST](docs/blast.md): why searches run at EBI rather than NCBI, and the
+  manual route to NCBI's `nr`.
 
-This plugin is installed by default on https://genomes.jbrowse.org so you can
-use it on any species there
+Linking and embedding:
 
-## Programmatic usage
+- [Launching from a URL or code](docs/launching.md): worked session-spec links,
+  the genome connection, highlights, opening on a residue, and placement.
+- [Launch parameters](docs/launch-parameters.md): every argument and field.
+- [Linked views](docs/linked-views.md): how a column reaches its codon and a
+  protein3d structure.
 
-See [DEVELOPERS.md](DEVELOPERS.md)
+Working on the plugin:
+
+- [DEVELOPERS.md](DEVELOPERS.md): running it locally, the checks, the README
+  figure and publishing.
+
+## Publication
 
-## Publishing
+If you find this tool useful please cite our work
 
-just push a new tag using e.g.
+Diesh, C., Stevens, G., Bridge, C., Hogue, G., Buels, R., Cain, S., Stein, L., &
+Holmes, I. (2026). Proteins in the Genome Browser: Integration of Phylogenies,
+Alignments, and Structures With Nucleotide-level Evidence in JBrowse 2. Journal
+of Molecular Biology, 169645. https://doi.org/10.1016/j.jmb.2026.169645
 
-```
-pnpm version minor
-```
+See also https://github.com/GMOD/proteinbrowser for overview

package/dist/LaunchMsaView/cleanProteinSequence.test.d.ts

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

package/dist/LaunchMsaView/cleanProteinSequence.test.js

@@ -0,0 +1,77 @@
+import { SimpleFeature } from '@jbrowse/core/util';
+import { genomeToTranscriptSeqMapping } from 'g2p_mapper';
+import { describe, expect, test } from 'vitest';
+import { transcriptPosToVisibleCol } from '../MsaViewPanel/util';
+import { getProteinSequenceFromFeature } from './components/calculateProteinSequence';
+import { findQueryRow } from './detectQueryRow';
+import { cleanProteinSequence } from './util';
+describe('cleanProteinSequence', () => {
+    test('drops the stop and a trailing partial codon', () => {
+        expect(cleanProteinSequence('MAWK*')).toBe('MAWK');
+        expect(cleanProteinSequence('MAWK&')).toBe('MAWK');
+    });
+    test('keeps a residue for every other codon', () => {
+        expect(cleanProteinSequence('&MAWK*')).toBe('XMAWK');
+        expect(cleanProteinSequence('MA*WK*')).toBe('MAXWK');
+        expect(cleanProteinSequence('MA&WK')).toBe('MAXWK');
+    });
+});
+// what the genome view hovers is a codon, and what lights is the query row's
+// residue at g2p's number for that codon, so the two have to count alike
+describe('a launched query row read through g2p', () => {
+    function rowResidueUnder(genomePos, json) {
+        const seq = json.seq;
+        const feature = new SimpleFeature(json);
+        const row = cleanProteinSequence(getProteinSequenceFromFeature({ seq, feature }));
+        const { g2p } = genomeToTranscriptSeqMapping(feature.toJSON());
+        const col = transcriptPosToVisibleCol({
+            querySeqName: 'QUERY',
+            querySeqOffset: 0,
+            seqPosToVisibleCol: (_, p) => (p < row.length ? p : row.length),
+            visibleColToSeqPos: (_, c) => (c < row.length ? c : undefined),
+        }, g2p[genomePos]);
+        return row[col];
+    }
+    function transcript(seq, cds) {
+        return {
+            uniqueId: 't1',
+            refName: 'chr1',
+            start: 0,
+            end: seq.length,
+            strand: 1,
+            type: 'mRNA',
+            seq,
+            subfeatures: [
+                { uniqueId: 'c1', refName: 'chr1', start: 0, end: seq.length, ...cds },
+            ],
+        };
+    }
+    test('after a partial first codon', () => {
+        // G | ATG GCC TGG AAA TAA: base 4 opens GCC, alanine
+        const json = transcript('GATGGCCTGGAAATAA', { type: 'CDS', phase: 1 });
+        expect(rowResidueUnder(4, json)).toBe('A');
+        expect(rowResidueUnder(10, json)).toBe('K');
+    });
+    test('after an internal stop', () => {
+        // ATG TGA GCC TGG TAA: a selenocysteine GENCODE does not annotate
+        const json = transcript('ATGTGAGCCTGGTAA', { type: 'CDS' });
+        expect(rowResidueUnder(6, json)).toBe('A');
+    });
+});
+describe('query row detection', () => {
+    test('matches a row a search launch built from a partial transcript', () => {
+        const msa = '>QUERY\nXMAWK\n>other\nMAWR-';
+        expect(findQueryRow(msa, '&MAWK*').match).toMatchObject({
+            name: 'QUERY',
+            quality: 'exact',
+            offset: 0,
+        });
+    });
+    test('still places a row that starts at the first whole codon', () => {
+        const msa = '>Query_1\nMAWK\n>other\nMAWR';
+        expect(findQueryRow(msa, '&MAWK*').match).toMatchObject({
+            name: 'Query_1',
+            offset: 1,
+        });
+    });
+});

package/dist/LaunchMsaView/components/BlastQuery/BlastAutomaticPanel.js

@@ -9,10 +9,10 @@ import LaunchPanelContent from '../LaunchPanelContent';
 import SequenceStatusMessage from '../SequenceStatus';
 import SubmitCancelActions from '../SubmitCancelActions';
 import TranscriptSelector from '../TranscriptSelector';
+import { builtAlignmentLook, launchConnectedView, useLaunchSubmit, } from '../launchConnectedView';
 import { useTranscriptSelection } from '../useTranscriptSelection';
 import CachedBlastResults from './CachedBlastResults';
 import MsaAlgorithmSelect from './MsaAlgorithmSelect';
-import { blastLaunchView } from './blastLaunchView';
 import { databaseLabel, databaseOptionsFor, defaultMaxHits, defaultSearchFor, searchProgramLabels, searchPrograms, } from './consts';
 import { useStoredMsaAlgorithm, useStoredSearchChoice, } from './searchChoiceStorage';
 import { useCachedBlastResults } from './useCachedBlastResults';
@@ -35,7 +35,7 @@ const useStyles = makeStyles()({
 const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, children, preferredTranscriptId, }) {
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
-    const [launchViewError, setLaunchViewError] = useState();
+    const { launchError, submit } = useLaunchSubmit(handleClose);
     // one piece of state, not two: a program and a database that program does not
     // have is a 400 from EBI minutes after Submit, and holding them apart is what
     // would let them drift into that
@@ -53,7 +53,7 @@ const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, ch
         preferredTranscriptId,
     });
     const { selectedTranscript, proteinSequence, sequenceStatus } = transcriptSelection;
-    const e = transcriptSelection.error ?? launchViewError ?? cachedResultsError;
+    const e = transcriptSelection.error ?? launchError ?? cachedResultsError;
     return (React.createElement(React.Fragment, null,
         React.createElement(LaunchPanelContent, { error: e },
             children,
@@ -85,37 +85,34 @@ const BlastAutomaticPanel = observer(function ({ handleClose, feature, model, ch
                     React.createElement(Typography, null, "Previous BLAST Results")),
                 React.createElement(AccordionDetails, null,
                     React.createElement(CachedBlastResults, { model: model, handleClose: handleClose, feature: feature })))) : null),
-        React.createElement(SubmitCancelActions, { model: model, hint: React.createElement(SequenceStatusMessage, { status: sequenceStatus }), submitDisabled: !proteinSequence || !hitCountValid, onSubmit: () => {
-                try {
-                    if (selectedTranscript) {
-                        setLaunchViewError(undefined);
-                        blastLaunchView({
-                            feature: selectedTranscript,
+        React.createElement(SubmitCancelActions, { model: model, hint: React.createElement(SequenceStatusMessage, { status: sequenceStatus }), submitDisabled: !proteinSequence || !hitCountValid, onSubmit: placement => {
+                if (selectedTranscript) {
+                    const blastParams = search.program === 'phmmer'
+                        ? {
+                            searchProgram: 'phmmer',
+                            blastDatabase: search.database,
+                            maxHits: hitCount,
+                            selectedTranscript: selectedTranscript.toJSON(),
+                            proteinSequence,
+                        }
+                        : {
+                            searchProgram: 'blastp',
+                            blastDatabase: search.database,
+                            msaAlgorithm: selectedMsaAlgorithm,
+                            maxHits: hitCount,
+                            selectedTranscript: selectedTranscript.toJSON(),
+                            proteinSequence,
+                        };
+                    submit(() => {
+                        launchConnectedView({
                             view,
-                            newViewTitle: getBlastViewTitle(feature, selectedTranscript),
-                            blastParams: search.program === 'phmmer'
-                                ? {
-                                    searchProgram: 'phmmer',
-                                    blastDatabase: search.database,
-                                    maxHits: hitCount,
-                                    selectedTranscript: selectedTranscript.toJSON(),
-                                    proteinSequence,
-                                }
-                                : {
-                                    searchProgram: 'blastp',
-                                    blastDatabase: search.database,
-                                    msaAlgorithm: selectedMsaAlgorithm,
-                                    maxHits: hitCount,
-                                    selectedTranscript: selectedTranscript.toJSON(),
-                                    proteinSequence,
-                                },
+                            feature: selectedTranscript,
+                            placement,
+                            displayName: getBlastViewTitle(feature, selectedTranscript),
+                            ...builtAlignmentLook,
+                            blastParams,
                         });
-                        handleClose();
-                    }
-                }
-                catch (e) {
-                    console.error(e);
-                    setLaunchViewError(e);
+                    });
                 }
             }, onCancel: handleClose })));
 });

package/dist/LaunchMsaView/components/BlastQuery/BlastManualPanel.js

@@ -8,10 +8,10 @@ import TextField2 from '../../../components/TextField2';
 import { useQueryRowName } from '../../useQueryRowName';
 import { cleanProteinSequence, getGeneDisplayName, getLinearGenomeView, } from '../../util';
 import LaunchPanelContent from '../LaunchPanelContent';
-import { launchView } from '../ManualMSALoader/launchView';
 import QueryRowSelector from '../QueryRowSelector';
 import SubmitCancelActions from '../SubmitCancelActions';
 import TranscriptSelector from '../TranscriptSelector';
+import { launchConnectedView, useLaunchSubmit } from '../launchConnectedView';
 import { useTranscriptSelection } from '../useTranscriptSelection';
 import { BASE_BLAST_URL } from './consts';
 const useStyles = makeStyles()({
@@ -46,7 +46,7 @@ const useStyles = makeStyles()({
 const BlastManualPanel = observer(function ({ handleClose, feature, model, children, preferredTranscriptId, }) {
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
-    const [launchViewError, setLaunchViewError] = useState();
+    const { launchError, submit } = useLaunchSubmit(handleClose);
     const [msaText, setMsaText] = useState('');
     const [treeText, setTreeText] = useState('');
     const transcriptSelection = useTranscriptSelection({
@@ -62,7 +62,7 @@ const BlastManualPanel = observer(function ({ handleClose, feature, model, child
     const link = `${BASE_BLAST_URL}?PAGE_TYPE=BlastSearch&PAGE=Proteins&PROGRAM=blastp&QUERY=${s2}`;
     const link2 = `${BASE_BLAST_URL}?PAGE_TYPE=BlastSearch&PAGE=Proteins&PROGRAM=blastp&QUERY=${shorten2(s2, 10)}`;
     return (React.createElement(React.Fragment, null,
-        React.createElement(LaunchPanelContent, { error: launchViewError ?? error },
+        React.createElement(LaunchPanelContent, { error: launchError ?? error },
             children,
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection }),
             React.createElement("div", { className: classes.step },
@@ -83,24 +83,19 @@ const BlastManualPanel = observer(function ({ handleClose, feature, model, child
                             setTreeText(event.target.value);
                         } }),
                     React.createElement(QueryRowSelector, { ...queryRow })))),
-        React.createElement(SubmitCancelActions, { model: model, submitDisabled: !selectedTranscript || !msaText.trim(), onSubmit: () => {
-                try {
-                    if (selectedTranscript) {
-                        setLaunchViewError(undefined);
-                        launchView({
-                            newViewTitle: getGeneDisplayName(selectedTranscript),
+        React.createElement(SubmitCancelActions, { model: model, submitDisabled: !selectedTranscript || !msaText.trim(), onSubmit: placement => {
+                if (selectedTranscript) {
+                    submit(() => {
+                        launchConnectedView({
                             view,
                             feature: selectedTranscript,
+                            placement,
+                            displayName: getGeneDisplayName(selectedTranscript),
                             querySeqName: queryRow.querySeqName,
                             querySeqOffset: queryRow.querySeqOffset,
                             data: { msa: msaText, tree: treeText },
                         });
-                        handleClose();
-                    }
-                }
-                catch (e) {
-                    console.error(e);
-                    setLaunchViewError(e);
+                    });
                 }
             }, onCancel: handleClose })));
 });

package/dist/LaunchMsaView/components/BlastQuery/CachedBlastResults.js

@@ -5,7 +5,8 @@ import { Button, IconButton, List, ListItem, ListItemButton, ListItemText, Typog
 import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
 import { featureMatchesId, getGeneIdentifiers, getLinearGenomeView, getSortedTranscriptFeatures, } from '../../util';
-import { blastLaunchViewFromCache } from './blastLaunchView';
+import { builtAlignmentLook, launchConnectedView } from '../launchConnectedView';
+import { useLaunchPlacement } from '../launchPlacement';
 import { useCachedBlastResults } from './useCachedBlastResults';
 const useStyles = makeStyles()({
     header: {
@@ -53,22 +54,22 @@ const CachedBlastResults = observer(function ({ model, handleClose, feature, })
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
     const [operationError, setOperationError] = useState();
+    const [sideBySide] = useLaunchPlacement();
     const geneIds = useMemo(() => getGeneIdentifiers(feature), [feature]);
     const { results, error, isLoading, handleDelete, handleClearAll } = useCachedBlastResults(geneIds);
     const handleUseCached = (cached) => {
-        // reconnect the cached MSA to the genome: the cached query row is named
-        // 'QUERY' (react-msaview's default querySeqName) and corresponds to the
-        // transcript stored as transcriptId. Resolving it here restores the
-        // MSA<->genome navigation and hover-sync a fresh BLAST gets.
-        const { transcriptId } = cached;
-        const transcript = transcriptId
-            ? getSortedTranscriptFeatures(feature).find(t => featureMatchesId(t, transcriptId))
-            : undefined;
-        blastLaunchViewFromCache({
+        // the cached query row is the plugin's default `QUERY`, translated from
+        // the transcript stored as transcriptId, so that transcript relinks it
+        const { transcriptId, msa, tree, treeMetadata } = cached;
+        launchConnectedView({
             view,
-            cached,
-            newViewTitle: `BLAST - ${getResultDisplayName(cached)}`,
-            connectedFeature: transcript?.toJSON(),
+            feature: transcriptId
+                ? getSortedTranscriptFeatures(feature).find(t => featureMatchesId(t, transcriptId))
+                : undefined,
+            placement: sideBySide ? 'splitRight' : 'stack',
+            displayName: `BLAST - ${getResultDisplayName(cached)}`,
+            ...builtAlignmentLook,
+            data: { msa, tree, treeMetadata },
         });
         handleClose();
     };

package/dist/LaunchMsaView/components/ManualMSALoader/ManualMSALoader.js

@@ -1,9 +1,11 @@
 import React, { useState } from 'react';
 import { FileSelector } from '@jbrowse/core/ui';
+import { openLocation } from '@jbrowse/core/util/io';
 import { FormControl, FormControlLabel, Radio, RadioGroup } from '@mui/material';
 import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
 import TextField2 from '../../../components/TextField2';
+import { useDebounced, useFetch } from '../../../utils/useFetch';
 import { useQueryRowName } from '../../useQueryRowName';
 import { getGeneDisplayName, getLinearGenomeView } from '../../util';
 import LaunchPanelContent from '../LaunchPanelContent';
@@ -11,8 +13,18 @@ import QueryRowSelector from '../QueryRowSelector';
 import SequenceStatusMessage from '../SequenceStatus';
 import SubmitCancelActions from '../SubmitCancelActions';
 import TranscriptSelector from '../TranscriptSelector';
+import { launchConnectedView, useLaunchSubmit } from '../launchConnectedView';
 import { useTranscriptSelection } from '../useTranscriptSelection';
-import { launchView } from './launchView';
+/**
+ * The chosen file's text, so its query row is found by sequence the way a
+ * pasted alignment's is; without it a file launch named no row and never
+ * linked to the genome. Debounced because a URL arrives a keystroke at a time.
+ */
+function useMsaFileText(location) {
+    const debounced = useDebounced(location, 500);
+    const { data } = useFetch(debounced ? [JSON.stringify(debounced), 'msa-file-text'] : null, () => openLocation(debounced).readFile('utf8'));
+    return data ?? '';
+}
 const useStyles = makeStyles()({
     textAreaFont: {
         fontFamily: 'Courier New',
@@ -30,7 +42,7 @@ const useStyles = makeStyles()({
 const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handleClose, preferredTranscriptId, }) {
     const view = getLinearGenomeView(model);
     const { classes } = useStyles();
-    const [launchViewError, setLaunchViewError] = useState();
+    const { launchError, submit } = useLaunchSubmit(handleClose);
     const [inputMethod, setInputMethod] = useState('file');
     const [msaText, setMsaText] = useState('');
     const [treeText, setTreeText] = useState('');
@@ -42,8 +54,9 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
         preferredTranscriptId,
     });
     const { selectedTranscript, proteinSequence, error, sequenceStatus } = transcriptSelection;
-    const queryRow = useQueryRowName(msaText, proteinSequence);
-    const e = launchViewError ?? error;
+    const msaFileText = useMsaFileText(inputMethod === 'file' ? msaFileLocation : undefined);
+    const queryRow = useQueryRowName(inputMethod === 'file' ? msaFileText : msaText, proteinSequence);
+    const e = launchError ?? error;
     return (React.createElement(React.Fragment, null,
         React.createElement(LaunchPanelContent, { error: e },
             React.createElement(FormControl, { component: "fieldset" },
@@ -65,14 +78,14 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
             React.createElement(QueryRowSelector, { ...queryRow })),
         React.createElement(SubmitCancelActions, { model: model, hint: React.createElement(SequenceStatusMessage, { status: sequenceStatus }), submitDisabled: !selectedTranscript ||
                 (inputMethod === 'file' && !msaFileLocation) ||
-                (inputMethod === 'text' && !msaText.trim()), onSubmit: () => {
-                try {
-                    if (selectedTranscript) {
-                        setLaunchViewError(undefined);
-                        launchView({
-                            newViewTitle: getGeneDisplayName(selectedTranscript),
+                (inputMethod === 'text' && !msaText.trim()), onSubmit: placement => {
+                if (selectedTranscript) {
+                    submit(() => {
+                        launchConnectedView({
                             view,
                             feature: selectedTranscript,
+                            placement,
+                            displayName: getGeneDisplayName(selectedTranscript),
                             querySeqName: queryRow.querySeqName,
                             querySeqOffset: queryRow.querySeqOffset,
                             ...(inputMethod === 'file'
@@ -80,19 +93,9 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
                                     msaFilehandle: msaFileLocation,
                                     treeFilehandle: treeFileLocation,
                                 }
-                                : {
-                                    data: {
-                                        msa: msaText,
-                                        tree: treeText,
-                                    },
-                                }),
+                                : { data: { msa: msaText, tree: treeText } }),
                         });
-                        handleClose();
-                    }
-                }
-                catch (err) {
-                    console.error(err);
-                    setLaunchViewError(err);
+                    });
                 }
             }, onCancel: handleClose })));
 });

package/dist/LaunchMsaView/components/OrthologQuery/OrthologPanel.js

@@ -4,7 +4,6 @@ import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
 import TextField2 from '../../../components/TextField2';
 import { defaultMaxSpecies } from '../../../utils/ncbiOrthologs';
-import { useLocalStorage } from '../../../utils/useLocalStorage';
 import { getGeneDisplayName, getGeneIdentifiers, getLinearGenomeView, getTranscriptDisplayName, } from '../../util';
 import MsaAlgorithmSelect from '../BlastQuery/MsaAlgorithmSelect';
 import { useStoredMsaAlgorithm } from '../BlastQuery/searchChoiceStorage';
@@ -12,10 +11,10 @@ import LaunchPanelContent from '../LaunchPanelContent';
 import SequenceStatusMessage from '../SequenceStatus';
 import SubmitCancelActions from '../SubmitCancelActions';
 import TranscriptSelector from '../TranscriptSelector';
+import { builtAlignmentLook, launchConnectedView, useLaunchSubmit, } from '../launchConnectedView';
 import { useTranscriptSelection } from '../useTranscriptSelection';
-import OrthologSourceSelect, { ORTHOLOG_SOURCE_STORAGE_KEY, } from './OrthologSourceSelect';
+import OrthologSourceSelect, { useStoredOrthologSource, } from './OrthologSourceSelect';
 import QuerySpeciesSelect from './QuerySpeciesSelect';
-import { orthologLaunchView } from './orthologLaunchView';
 const useStyles = makeStyles()({
     selectField: {
         width: 180,
@@ -31,9 +30,9 @@ const rowsHint = {
 const OrthologPanel = observer(function ({ handleClose, feature, model, preferredTranscriptId, }) {
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
-    const [launchViewError, setLaunchViewError] = useState();
+    const { launchError, submit } = useLaunchSubmit(handleClose);
     const [taxId, setTaxId] = useState(9606);
-    const [source, setSource] = useLocalStorage(ORTHOLOG_SOURCE_STORAGE_KEY, 'ncbi');
+    const [source, setSource] = useStoredOrthologSource();
     const [msaAlgorithm, setMsaAlgorithm] = useStoredMsaAlgorithm();
     const [maxSpecies, setMaxSpecies] = useState(String(defaultMaxSpecies));
     const geneCandidates = useMemo(() => getGeneIdentifiers(feature), [feature]);
@@ -43,7 +42,7 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, preferre
         preferredTranscriptId,
     });
     const { selectedTranscript, proteinSequence, sequenceStatus } = transcriptSelection;
-    const e = transcriptSelection.error ?? launchViewError;
+    const e = transcriptSelection.error ?? launchError;
     const rowCount = Number(maxSpecies);
     const rowCountValid = Number.isInteger(rowCount) && rowCount >= 2;
     return (React.createElement(React.Fragment, null,
@@ -59,14 +58,15 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, preferre
                         ? rowsHint[source](rowCount)
                         : 'a whole number, 2 or more' })),
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection })),
-        React.createElement(SubmitCancelActions, { model: model, hint: React.createElement(SequenceStatusMessage, { status: sequenceStatus }), submitDisabled: !proteinSequence || !rowCountValid, onSubmit: () => {
-                try {
-                    if (selectedTranscript) {
-                        setLaunchViewError(undefined);
-                        orthologLaunchView({
-                            feature: selectedTranscript,
+        React.createElement(SubmitCancelActions, { model: model, hint: React.createElement(SequenceStatusMessage, { status: sequenceStatus }), submitDisabled: !proteinSequence || !rowCountValid, onSubmit: placement => {
+                if (selectedTranscript) {
+                    submit(() => {
+                        launchConnectedView({
                             view,
-                            newViewTitle: `Orthologs - ${getGeneDisplayName(feature)} - ${getTranscriptDisplayName(selectedTranscript)}`,
+                            feature: selectedTranscript,
+                            placement,
+                            displayName: `Orthologs - ${getGeneDisplayName(feature)} - ${getTranscriptDisplayName(selectedTranscript)}`,
+                            ...builtAlignmentLook,
                             orthologParams: {
                                 taxId,
                                 source,
@@ -77,12 +77,7 @@ const OrthologPanel = observer(function ({ handleClose, feature, model, preferre
                                 proteinSequence,
                             },
                         });
-                        handleClose();
-                    }
-                }
-                catch (e) {
-                    console.error(e);
-                    setLaunchViewError(e);
+                    });
                 }
             }, onCancel: handleClose })));
 });

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.d.ts

@@ -1,7 +1,8 @@
 import React from 'react';
 import type { OrthologSource } from '../../../MsaViewPanel/model';
-export declare const ORTHOLOG_SOURCE_STORAGE_KEY = "msaview-ortholog-source";
 export declare const orthologSourceLabels: Record<OrthologSource, string>;
+export declare function validOrthologSource(stored: unknown): OrthologSource;
+export declare function useStoredOrthologSource(): readonly ["ncbi" | "panther" | "uniref", (source: OrthologSource) => void];
 export default function OrthologSourceSelect({ value, onChange, className, }: {
     value: OrthologSource;
     onChange: (val: OrthologSource) => void;

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.js

@@ -1,12 +1,28 @@
 import React from 'react';
 import { MenuItem } from '@mui/material';
 import TextField2 from '../../../components/TextField2';
-export const ORTHOLOG_SOURCE_STORAGE_KEY = 'msaview-ortholog-source';
+import { useLocalStorage } from '../../../utils/useLocalStorage';
+const ORTHOLOG_SOURCE_STORAGE_KEY = 'msaview-ortholog-source';
 export const orthologSourceLabels = {
     ncbi: 'NCBI orthologs',
     panther: 'PANTHER',
     uniref: 'UniRef cluster',
 };
+const orthologSources = Object.keys(orthologSourceLabels);
+// another plugin version on the same origin may have stored a source this one
+// lacks, and the tab indexes its hints by it
+export function validOrthologSource(stored) {
+    return orthologSources.find(s => s === stored) ?? 'ncbi';
+}
+export function useStoredOrthologSource() {
+    const [stored, setStored] = useLocalStorage(ORTHOLOG_SOURCE_STORAGE_KEY, 'ncbi');
+    return [
+        validOrthologSource(stored),
+        (source) => {
+            setStored(source);
+        },
+    ];
+}
 // Which species a source can answer for, in the words a reader picking one
 // needs: NCBI's ortholog sets stop at vertebrates and insects, PANTHER's run
 // from human to yeast and Arabidopsis, and a UniRef cluster is every UniProtKB
@@ -19,5 +35,5 @@ const hints = {
 export default function OrthologSourceSelect({ value, onChange, className, }) {
     return (React.createElement(TextField2, { variant: "outlined", label: "Source", className: className, select: true, value: value, helperText: hints[value], onChange: event => {
             onChange(event.target.value);
-        } }, Object.keys(orthologSourceLabels).map(val => (React.createElement(MenuItem, { value: val, key: val }, orthologSourceLabels[val])))));
+        } }, orthologSources.map(val => (React.createElement(MenuItem, { value: val, key: val }, orthologSourceLabels[val])))));
 }

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.test.d.ts

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

package/dist/LaunchMsaView/components/OrthologQuery/OrthologSourceSelect.test.js

@@ -0,0 +1,13 @@
+import { expect, test } from 'vitest';
+import { validOrthologSource } from './OrthologSourceSelect';
+test('a stored source this version knows comes back as it went in', () => {
+    expect(validOrthologSource('panther')).toBe('panther');
+    expect(validOrthologSource('uniref')).toBe('uniref');
+});
+// the Orthologs tab is the dialog's default, and it looked its helper text up
+// by whatever was stored, so an unknown value threw on open
+test('anything else falls back to NCBI', () => {
+    expect(validOrthologSource('ensembl')).toBe('ncbi');
+    expect(validOrthologSource(undefined)).toBe('ncbi');
+    expect(validOrthologSource({ source: 'panther' })).toBe('ncbi');
+});