jbrowse-plugin-msaview 3.0.0 → 3.1.0

package/dist/LaunchMsaView/components/BlastQuery/BlastManualPanel.d.ts

@@ -1,5 +1,16 @@
 import React from 'react';
 import type { AbstractTrackModel, Feature } from '@jbrowse/core/util';
+/**
+ * The route to NCBI's `nr`, which no plugin version can query directly: NCBI
+ * stopped sending Access-Control-Allow-Origin to third-party origins, so the
+ * browser cannot read Blast.cgi at all (see docs/blast.md).
+ *
+ * That makes the round trip through NCBI's own site the whole feature rather
+ * than a fallback, so the panel walks it end to end. It used to hand the user a
+ * link, tell them to "paste the results into JBrowse", and offer only a Close
+ * button -- leaving them to find the Manual upload tab, re-pick the transcript
+ * they had already chosen here, and hand-type the row name.
+ */
 declare const BlastManualPanel: ({ handleClose, feature, model, children, }: {
     children: React.ReactNode;
     model: AbstractTrackModel;

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

@@ -1,45 +1,102 @@
-import React from 'react';
+import React, { useState } from 'react';
 import { shorten2 } from '@jbrowse/core/util';
-import { Button, DialogActions, Typography } from '@mui/material';
+import { Alert, Typography } from '@mui/material';
 import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
 import { BASE_BLAST_URL } from './consts';
 import ExternalLink from '../../../components/ExternalLink';
-import { cleanProteinSequence, getLinearGenomeView } from '../../util';
+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 { useTranscriptSelection } from '../useTranscriptSelection';
 const useStyles = makeStyles()({
     ncbiLink: {
         wordBreak: 'break-all',
-        margin: 30,
-        maxWidth: 600,
     },
-    infoText: {
+    textAreaFont: {
+        fontFamily: 'Courier New',
+    },
+    msaInput: {
+        marginBottom: 20,
+    },
+    step: {
         marginTop: 20,
     },
+    stepBody: {
+        marginLeft: 20,
+        marginTop: 8,
+    },
 });
+/**
+ * The route to NCBI's `nr`, which no plugin version can query directly: NCBI
+ * stopped sending Access-Control-Allow-Origin to third-party origins, so the
+ * browser cannot read Blast.cgi at all (see docs/blast.md).
+ *
+ * That makes the round trip through NCBI's own site the whole feature rather
+ * than a fallback, so the panel walks it end to end. It used to hand the user a
+ * link, tell them to "paste the results into JBrowse", and offer only a Close
+ * button -- leaving them to find the Manual upload tab, re-pick the transcript
+ * they had already chosen here, and hand-type the row name.
+ */
 const BlastManualPanel = observer(function ({ handleClose, feature, model, children, }) {
     const { classes } = useStyles();
     const view = getLinearGenomeView(model);
+    const [launchViewError, setLaunchViewError] = useState();
+    const [msaText, setMsaText] = useState('');
+    const [treeText, setTreeText] = useState('');
     const transcriptSelection = useTranscriptSelection({ feature, view });
-    const { proteinSequence, error } = transcriptSelection;
+    const { proteinSequence, selectedTranscript, error } = transcriptSelection;
+    const queryRow = useQueryRowName(msaText, proteinSequence);
     const s2 = cleanProteinSequence(proteinSequence);
     // a link the user follows to NCBI's own site, not something we fetch — which
     // is exactly why this route still works when the automatic one cannot
     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: error },
+        React.createElement(LaunchPanelContent, { error: launchViewError ?? error },
             children,
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection }),
-            proteinSequence ? (React.createElement("div", { className: classes.ncbiLink },
-                "Link to NCBI BLAST: ",
-                React.createElement(ExternalLink, { href: link }, link2))) : null,
-            React.createElement(Typography, { className: classes.infoText }, "Click the link above and run your BLAST query, and once you have results, click \"Multiple Alignment\" at the top of the results page to be redirected to COBALT, NCBI's multiple sequence aligner. Once COBALT completes, you can download an MSA (.aln file) and optionally a Newick tree (.nh) and paste the results into JBrowse")),
-        React.createElement(DialogActions, null,
-            React.createElement(Button, { color: "primary", variant: "contained", onClick: () => {
-                    handleClose();
-                } }, "Close"))));
+            React.createElement("div", { className: classes.step },
+                React.createElement(Typography, { variant: "subtitle2" }, "1. Run the search at NCBI"),
+                React.createElement("div", { className: classes.stepBody }, proteinSequence ? (React.createElement("div", { className: classes.ncbiLink },
+                    React.createElement(ExternalLink, { href: link }, link2))) : (React.createElement(Alert, { severity: "info" }, "Pick a transcript above to get a link carrying its protein sequence.")))),
+            React.createElement("div", { className: classes.step },
+                React.createElement(Typography, { variant: "subtitle2" }, "2. Align the hits"),
+                React.createElement("div", { className: classes.stepBody },
+                    React.createElement(Typography, null, "On the results page click \"Multiple Alignment\" to run COBALT, NCBI's aligner. Download the alignment (.aln) and, if you want the tree drawn, the Newick tree (.nh)."))),
+            React.createElement("div", { className: classes.step },
+                React.createElement(Typography, { variant: "subtitle2" }, "3. Paste the results back here"),
+                React.createElement("div", { className: classes.stepBody },
+                    React.createElement(TextField2, { variant: "outlined", label: "Alignment", multiline: true, minRows: 5, maxRows: 10, fullWidth: true, className: classes.msaInput, slotProps: { input: { className: classes.textAreaFont } }, placeholder: "Paste the .aln contents here", value: msaText, onChange: event => {
+                            setMsaText(event.target.value);
+                        } }),
+                    React.createElement(TextField2, { variant: "outlined", label: "Tree (optional)", multiline: true, minRows: 3, maxRows: 10, fullWidth: true, slotProps: { input: { className: classes.textAreaFont } }, placeholder: "Paste the .nh Newick tree here", value: treeText, onChange: event => {
+                            setTreeText(event.target.value);
+                        } }),
+                    React.createElement(QueryRowSelector, { ...queryRow })))),
+        React.createElement(SubmitCancelActions, { submitDisabled: !selectedTranscript || !msaText.trim(), onSubmit: () => {
+                try {
+                    if (selectedTranscript) {
+                        setLaunchViewError(undefined);
+                        launchView({
+                            newViewTitle: getGeneDisplayName(selectedTranscript),
+                            view,
+                            feature: selectedTranscript,
+                            querySeqName: queryRow.querySeqName,
+                            data: { msa: msaText, tree: treeText },
+                        });
+                        handleClose();
+                    }
+                }
+                catch (e) {
+                    console.error(e);
+                    setLaunchViewError(e);
+                }
+            }, onCancel: handleClose })));
 });
 export default BlastManualPanel;

package/dist/LaunchMsaView/components/BlastQuery/consts.d.ts

@@ -7,6 +7,13 @@
 export declare const BASE_BLAST_URL = "https://blast.ncbi.nlm.nih.gov/Blast.cgi";
 export declare const msaAlgorithms: readonly ["clustalo", "muscle", "kalign", "mafft"];
 export type MsaAlgorithm = (typeof msaAlgorithms)[number];
-export declare const blastDatabaseOptions: readonly ["uniprotkb_swissprot", "uniprotkb", "uniprotkb_reference_proteomes", "uniprotkb_trembl"];
+/**
+ * EBI rejects a submission naming a database outside its own list with a 400,
+ * so every value here has to appear in
+ * https://www.ebi.ac.uk/Tools/services/rest/ncbiblast/parameterdetails/database
+ * -- `uniprotkb_reference_proteomes` did not, and 3.0.0 shipped it as a dead
+ * menu entry.
+ */
+export declare const blastDatabaseOptions: readonly ["uniprotkb_swissprot", "uniprotkb", "pan_proteomes", "uniprotkb_trembl"];
 export type BlastDatabase = (typeof blastDatabaseOptions)[number];
 export declare const defaultBlastDatabase: BlastDatabase;

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

@@ -6,10 +6,17 @@
  */
 export const BASE_BLAST_URL = 'https://blast.ncbi.nlm.nih.gov/Blast.cgi';
 export const msaAlgorithms = ['clustalo', 'muscle', 'kalign', 'mafft'];
+/**
+ * EBI rejects a submission naming a database outside its own list with a 400,
+ * so every value here has to appear in
+ * https://www.ebi.ac.uk/Tools/services/rest/ncbiblast/parameterdetails/database
+ * -- `uniprotkb_reference_proteomes` did not, and 3.0.0 shipped it as a dead
+ * menu entry.
+ */
 export const blastDatabaseOptions = [
     'uniprotkb_swissprot',
     'uniprotkb',
-    'uniprotkb_reference_proteomes',
+    'pan_proteomes',
     'uniprotkb_trembl',
 ];
 // curated, so it returns roughly one good sequence per species rather than the

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

@@ -1,12 +1,14 @@
 import React, { useState } from 'react';
 import { FileSelector } from '@jbrowse/core/ui';
-import { Alert, FormControl, FormControlLabel, Radio, RadioGroup, } from '@mui/material';
+import { FormControl, FormControlLabel, Radio, RadioGroup } from '@mui/material';
 import { observer } from 'mobx-react';
 import { makeStyles } from 'tss-react/mui';
 import { launchView } from './launchView';
 import TextField2 from '../../../components/TextField2';
+import { useQueryRowName } from '../../useQueryRowName';
 import { getGeneDisplayName, getLinearGenomeView } from '../../util';
 import LaunchPanelContent from '../LaunchPanelContent';
+import QueryRowSelector from '../QueryRowSelector';
 import SubmitCancelActions from '../SubmitCancelActions';
 import TranscriptSelector from '../TranscriptSelector';
 import { useTranscriptSelection } from '../useTranscriptSelection';
@@ -23,12 +25,6 @@ const useStyles = makeStyles()({
     msaInput: {
         marginBottom: 20,
     },
-    queryNameInput: {
-        marginTop: 20,
-    },
-    warningAlert: {
-        marginTop: 10,
-    },
 });
 const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handleClose, }) {
     const view = getLinearGenomeView(model);
@@ -39,9 +35,9 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
     const [treeText, setTreeText] = useState('');
     const [msaFileLocation, setMsaFileLocation] = useState();
     const [treeFileLocation, setTreeFileLocation] = useState();
-    const [querySeqName, setQuerySeqName] = useState('');
     const transcriptSelection = useTranscriptSelection({ feature, view });
-    const { selectedTranscript, error } = transcriptSelection;
+    const { selectedTranscript, proteinSequence, error } = transcriptSelection;
+    const queryRow = useQueryRowName(msaText, proteinSequence);
     const e = launchViewError ?? error;
     return (React.createElement(React.Fragment, null,
         React.createElement(LaunchPanelContent, { error: e },
@@ -61,10 +57,7 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
                         setTreeText(event.target.value);
                     } })))),
             React.createElement(TranscriptSelector, { feature: feature, ...transcriptSelection }),
-            React.createElement(TextField2, { variant: "outlined", name: "MSA row name", fullWidth: true, required: true, className: classes.queryNameInput, placeholder: "Row name in MSA that corresponds to the selected transcript", helperText: "Required: Specify the name of the row in your MSA that should be aligned with the selected transcript", value: querySeqName, onChange: event => {
-                    setQuerySeqName(event.target.value);
-                } }),
-            !querySeqName.trim() ? (React.createElement(Alert, { severity: "warning", className: classes.warningAlert }, "Without specifying the MSA row name, clicking on the MSA will not navigate to the corresponding genome position, and hovering highlights will not work.")) : null),
+            React.createElement(QueryRowSelector, { ...queryRow })),
         React.createElement(SubmitCancelActions, { submitDisabled: !selectedTranscript ||
                 (inputMethod === 'file' && !msaFileLocation) ||
                 (inputMethod === 'text' && !msaText.trim()), onSubmit: () => {
@@ -75,7 +68,7 @@ const ManualMSALoader = observer(function PreLoadedMSA2({ model, feature, handle
                             newViewTitle: getGeneDisplayName(selectedTranscript),
                             view,
                             feature: selectedTranscript,
-                            querySeqName: querySeqName.trim(),
+                            querySeqName: queryRow.querySeqName,
                             ...(inputMethod === 'file'
                                 ? {
                                     msaFilehandle: msaFileLocation,

package/dist/LaunchMsaView/components/QueryRowSelector.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import type { QueryRowMatch } from '../detectQueryRow';
+/**
+ * Which MSA row corresponds to the selected transcript. Clicking and hovering in
+ * the alignment reach the genome only through this name, and a wrong one fails
+ * silently -- the view opens, renders, and never navigates -- so the field fills
+ * itself in from the pasted alignment and offers that alignment's own row names
+ * rather than a free text box the user can typo.
+ */
+export default function QueryRowSelector({ names, detected, querySeqName, setQuerySeqName, isAutoDetected, }: {
+    names: string[];
+    detected?: QueryRowMatch;
+    querySeqName: string;
+    setQuerySeqName: (arg: string) => void;
+    isAutoDetected: boolean;
+}): React.JSX.Element;

package/dist/LaunchMsaView/components/QueryRowSelector.js

@@ -0,0 +1,38 @@
+import React from 'react';
+import { Alert, MenuItem } from '@mui/material';
+import { makeStyles } from 'tss-react/mui';
+import TextField2 from '../../components/TextField2';
+const useStyles = makeStyles()({
+    field: {
+        marginTop: 20,
+    },
+    alert: {
+        marginTop: 10,
+    },
+});
+/**
+ * Which MSA row corresponds to the selected transcript. Clicking and hovering in
+ * the alignment reach the genome only through this name, and a wrong one fails
+ * silently -- the view opens, renders, and never navigates -- so the field fills
+ * itself in from the pasted alignment and offers that alignment's own row names
+ * rather than a free text box the user can typo.
+ */
+export default function QueryRowSelector({ names, detected, querySeqName, setQuerySeqName, isAutoDetected, }) {
+    const { classes } = useStyles();
+    return (React.createElement(React.Fragment, null,
+        names.length > 0 ? (React.createElement(TextField2, { variant: "outlined", label: "MSA row matching the selected transcript", select: true, fullWidth: true, className: classes.field, value: names.includes(querySeqName) ? querySeqName : '', onChange: event => {
+                setQuerySeqName(event.target.value);
+            } }, names.map(name => (React.createElement(MenuItem, { value: name, key: name },
+            name,
+            detected?.name === name ? ' — matches your protein' : ''))))) : (React.createElement(TextField2, { variant: "outlined", label: "MSA row matching the selected transcript", fullWidth: true, className: classes.field, helperText: "Paste an alignment above and this fills in on its own", value: querySeqName, onChange: event => {
+                setQuerySeqName(event.target.value);
+            } })),
+        isAutoDetected && detected ? (React.createElement(Alert, { severity: "success", className: classes.alert },
+            "Matched ",
+            React.createElement("strong", null, detected.name),
+            " to your protein sequence",
+            detected.quality === 'exact'
+                ? ''
+                : `, covering ${Math.round(detected.identity * 100)}% of it`,
+            ". Clicking the alignment will navigate the genome view.")) : names.length > 0 && !querySeqName ? (React.createElement(Alert, { severity: "warning", className: classes.alert }, "No row matched your protein sequence \u2014 pick the one for your gene above. Without it the alignment still renders, but clicking it will not navigate the genome view.")) : null));
+}

package/dist/LaunchMsaView/detectQueryRow.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which row of a pasted alignment is the gene the user launched from.
+ *
+ * The MsaView needs that row name to tie alignment columns back to genome
+ * coordinates, and until now the user typed it. Nothing validates a typo: the
+ * view opens, renders, and simply never navigates or highlights, which reads as
+ * a broken feature rather than a wrong field. Meanwhile the plugin already
+ * knows the protein sequence it sent to BLAST, so it can find the row by
+ * sequence instead of asking.
+ *
+ * NCBI and EBI both rename the query on the way through -- COBALT emits
+ * `Query_1`, EBI's aligners carry the accession -- so the name is no help. The
+ * residues are, and they survive every rename.
+ */
+export type MatchQuality = 'exact' | 'partial' | 'similar';
+export interface QueryRowMatch {
+    name: string;
+    quality: MatchQuality;
+    /** identity over the compared region, 0-1 */
+    identity: number;
+}
+export declare function detectQueryRow(msaText: string, proteinSequence: string): QueryRowMatch | undefined;
+export declare function getMsaRowNames(msaText: string): string[];

package/dist/LaunchMsaView/detectQueryRow.js

@@ -0,0 +1,94 @@
+import { getUngappedSequence, parseMSA } from 'msa-parsers';
+/**
+ * A stop codon is present in the transcript's translation and absent from
+ * anything an aligner returns, and case is not meaningful in either.
+ */
+function normalize(seq) {
+    return seq
+        .replaceAll('*', '')
+        .replaceAll('-', '')
+        .replaceAll('.', '')
+        .toUpperCase();
+}
+function identityOverOverlap(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0) {
+        return 0;
+    }
+    let same = 0;
+    for (let i = 0; i < len; i++) {
+        if (a[i] === b[i]) {
+            same++;
+        }
+    }
+    return same / len;
+}
+/**
+ * Below this, a "best" row is not a match at all -- an alignment of homologs is
+ * full of rows in the 40-70% range, and picking the top one would silently wire
+ * the view to a paralog from another species.
+ */
+const SIMILARITY_FLOOR = 0.9;
+/**
+ * How much of the query a contained row has to cover. A short fragment is a
+ * substring of almost any protein, so without a floor the first few residues of
+ * a half-pasted alignment match the query and the field fills in with a row the
+ * user is still typing.
+ */
+const PARTIAL_COVERAGE_FLOOR = 0.5;
+export function detectQueryRow(msaText, proteinSequence) {
+    const query = normalize(proteinSequence);
+    if (!query || !msaText.trim()) {
+        return undefined;
+    }
+    let names;
+    let parsed;
+    try {
+        const msa = parseMSA(msaText);
+        names = msa.getNames();
+        parsed = msa;
+    }
+    catch {
+        // a half-pasted alignment throws here on every keystroke; the caller shows
+        // the field rather than an error
+        return undefined;
+    }
+    const candidates = [];
+    for (const name of names) {
+        const row = normalize(getUngappedSequence(parsed.getRow(name)));
+        if (!row) {
+            continue;
+        }
+        if (row === query) {
+            // nothing beats an exact match, and a second one would be a duplicate row
+            return { name, quality: 'exact', identity: 1 };
+        }
+        // BLAST reports the aligned region, so the row is often the query trimmed
+        // at one or both ends rather than the whole protein
+        if (query.includes(row) || row.includes(query)) {
+            const coverage = Math.min(row.length, query.length) / Math.max(row.length, query.length);
+            if (coverage >= PARTIAL_COVERAGE_FLOOR) {
+                candidates.push({ name, quality: 'partial', identity: coverage });
+            }
+            continue;
+        }
+        const identity = identityOverOverlap(row, query);
+        if (identity >= SIMILARITY_FLOOR) {
+            candidates.push({ name, quality: 'similar', identity });
+        }
+    }
+    const order = ['exact', 'partial', 'similar'];
+    return candidates.sort((a, b) => order.indexOf(a.quality) - order.indexOf(b.quality) ||
+        b.identity - a.identity)[0];
+}
+export function getMsaRowNames(msaText) {
+    if (!msaText.trim()) {
+        return [];
+    }
+    try {
+        return parseMSA(msaText).getNames();
+    }
+    catch {
+        return [];
+    }
+}

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

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

package/dist/LaunchMsaView/detectQueryRow.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'vitest';
+import { detectQueryRow, getMsaRowNames } from './detectQueryRow';
+const protein = 'MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD';
+// COBALT renames the query `Query_1`, so only the residues identify it
+const clustal = `CLUSTAL W (1.81) multiple sequence alignment
+
+Query_1         MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+sp|P02769|ALBU  MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPYD
+sp|Q5XLE4|OTHE  MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLWWCPFD
+`;
+const fasta = `>Query_1
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+>sp|P02769|ALBU_BOVIN
+MKWVTFISLLLLFSSAYSRG--RRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPYD
+`;
+describe('detectQueryRow', () => {
+    test('finds the query by sequence when the aligner renamed it', () => {
+        expect(detectQueryRow(clustal, protein)).toMatchObject({
+            name: 'Query_1',
+            quality: 'exact',
+        });
+    });
+    test('ignores gaps in the aligned row', () => {
+        expect(detectQueryRow(fasta, protein)?.name).toBe('Query_1');
+    });
+    test('tolerates the trailing stop codon the translation carries', () => {
+        expect(detectQueryRow(clustal, `${protein}*`)?.name).toBe('Query_1');
+    });
+    test('matches a row that is the query trimmed to the aligned region', () => {
+        const trimmed = `>hit_one\nWRONGWRONGWRONGWRONG\n>aligned_query\n${protein.slice(5, 40)}\n`;
+        expect(detectQueryRow(trimmed, protein)).toMatchObject({
+            name: 'aligned_query',
+            quality: 'partial',
+        });
+    });
+    // the failure that matters: silently wiring the view to a homolog would look
+    // like it worked, and every navigation afterwards would land in the wrong place
+    test('returns nothing when only diverged homologs are present', () => {
+        const homologsOnly = `>hit_one
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+>hit_two
+MKWVTFISLLLLFSSAYSRGVFRRDTHKSEIAHRFKDLGEEHFKGLVLIAFSQYLQQCPFD
+`;
+        expect(detectQueryRow(homologsOnly, 'WWWWWWWWWWWWWWWWWWWWWWWWWWWWWW')).toBeUndefined();
+    });
+    test('returns nothing rather than throwing on a half-pasted alignment', () => {
+        expect(detectQueryRow('>partial\nMKWV', protein)).toBeUndefined();
+        expect(detectQueryRow('not an alignment at all', protein)).toBeUndefined();
+        expect(detectQueryRow('', protein)).toBeUndefined();
+        expect(detectQueryRow(clustal, '')).toBeUndefined();
+    });
+});
+describe('getMsaRowNames', () => {
+    test('lists the rows for the override dropdown', () => {
+        expect(getMsaRowNames(clustal)).toEqual([
+            'Query_1',
+            'sp|P02769|ALBU',
+            'sp|Q5XLE4|OTHE',
+        ]);
+    });
+    test('is empty rather than throwing while the user is still pasting', () => {
+        expect(getMsaRowNames('CLUSTAL W')).toEqual([]);
+        expect(getMsaRowNames('')).toEqual([]);
+    });
+});

package/dist/LaunchMsaView/useQueryRowName.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The MSA row name to launch with, found by sequence rather than typed.
+ *
+ * Only the user's override is state. The detected name is derived from the
+ * pasted text during render, so pasting a new alignment re-detects without an
+ * effect writing back into state, and an override survives later edits to the
+ * alignment because it is the one thing actually stored.
+ */
+export declare function useQueryRowName(msaText: string, proteinSequence: string): {
+    detected: import("./detectQueryRow").QueryRowMatch | undefined;
+    names: string[];
+    querySeqName: string;
+    setQuerySeqName: import("react").Dispatch<import("react").SetStateAction<string | undefined>>;
+    isAutoDetected: boolean;
+};

package/dist/LaunchMsaView/useQueryRowName.js

@@ -0,0 +1,26 @@
+import { useMemo, useState } from 'react';
+import { detectQueryRow, getMsaRowNames } from './detectQueryRow';
+/**
+ * The MSA row name to launch with, found by sequence rather than typed.
+ *
+ * Only the user's override is state. The detected name is derived from the
+ * pasted text during render, so pasting a new alignment re-detects without an
+ * effect writing back into state, and an override survives later edits to the
+ * alignment because it is the one thing actually stored.
+ */
+export function useQueryRowName(msaText, proteinSequence) {
+    const [override, setOverride] = useState();
+    // parsing runs on every keystroke in the paste box otherwise, and an
+    // alignment of a few hundred rows is not free
+    const { detected, names } = useMemo(() => ({
+        detected: detectQueryRow(msaText, proteinSequence),
+        names: getMsaRowNames(msaText),
+    }), [msaText, proteinSequence]);
+    return {
+        detected,
+        names,
+        querySeqName: override ?? detected?.name ?? '',
+        setQuerySeqName: setOverride,
+        isAutoDetected: override === undefined && !!detected,
+    };
+}

package/dist/MsaViewPanel/afterCreateAutoruns.d.ts

@@ -27,18 +27,34 @@ export declare function processInit(self: JBrowsePluginMsaViewModel): void;
  */
 export declare function syncGenomeHoverToMsaColumn(self: JBrowsePluginMsaViewModel): () => void;
 /**
- * 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.
+ * Mirror a connected 3D protein view's highlights onto the MSA's highlighted
+ * columns, from either of the two channels protein3d publishes:
  *
- * 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).
+ * - `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.
+ *
+ * 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 declare function observeProteinHighlights(self: JBrowsePluginMsaViewModel): () => void;
 export declare function runCleanup(): void;