jbrowse-plugin-msaview 3.1.0 → 3.3.0

package/dist/utils/launchMsaView.d.ts

@@ -0,0 +1,19 @@
+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 declare function launchMsaView(session: AbstractSessionModel, { placement, ...snapshot }: MsaViewLaunchSpec): import("@jbrowse/core/util").AbstractViewModel;

package/dist/utils/launchMsaView.js

@@ -0,0 +1,13 @@
+import { placeMsaView } from './workspaces';
+/**
+ * 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, { placement = 'stack', ...snapshot }) {
+    const view = session.addView('MsaView', { type: 'MsaView', ...snapshot });
+    placeMsaView(session, view.id, placement);
+    return view;
+}

package/dist/utils/pantherOrthologs.d.ts

@@ -0,0 +1,79 @@
+import type { OrthologRow } from './ncbiOrthologs';
+export interface PantherGenome {
+    /** PANTHER's organism code, e.g. HUMAN, DROME */
+    code: string;
+    taxId: number;
+    /** short common name, e.g. fruit_fly */
+    name: string;
+    /** scientific name */
+    longName: string;
+}
+/**
+ * `supportedgenomes` -> the code<->taxon map every other parse needs. PANTHER
+ * names organisms by code only in ortholog results.
+ */
+export declare function parseGenomes(json: unknown): PantherGenome[];
+export interface PantherGene {
+    code: string;
+    /** UniProt accession */
+    accession: string;
+    /** the source database's own id, e.g. HGNC=1773, FlyBase=FBgn0016131 */
+    geneRef: string;
+}
+export interface PantherHit extends PantherGene {
+    symbol?: string;
+    /**
+     * LDO = least diverged ortholog, PANTHER's pick of the one-to-one; O = any
+     * other ortholog in a one-to-many or many-to-many family
+     */
+    type: 'LDO' | 'O';
+}
+/**
+ * `matchortho` -> the query gene (PANTHER names it in every row) and one hit
+ * per target gene. An unknown gene comes back under `unmapped_ids`; a gene with
+ * no ortholog in the target set comes back as a bare `{ id }`.
+ */
+export declare function parseMatches(json: unknown): {
+    unmapped: boolean;
+    query?: PantherGene;
+    hits: PantherHit[];
+};
+/**
+ * One hit per organism, in first-seen order: the LDO where PANTHER named one,
+ * else the first other ortholog it listed. A many-to-many family (the Hox
+ * genes) has no LDO at all, so dropping to "first O" is what keeps those
+ * species in the alignment.
+ */
+export declare function pickOnePerGenome(hits: PantherHit[]): PantherHit[];
+/** `uniprotkb/accessions` -> accession -> sequence */
+export declare function parseSequences(json: unknown): Map<string, string>;
+/** The proteome list, fetched once per page and forgotten on failure. */
+export declare function fetchGenomes(): Promise<PantherGenome[]>;
+export interface PantherOrthologs {
+    /** the candidate PANTHER recognised */
+    matched: string;
+    /** the query gene as PANTHER knows it, with its UniProt sequence */
+    query?: PantherGene & {
+        sequence: string;
+    };
+    rows: OrthologRow[];
+}
+/**
+ * The whole PANTHER half of the pipeline: gene -> ortholog rows carrying
+ * labels, accessions and sequences, plus the query gene's own protein for the
+ * query row. Two lookups (genomes, orthologs), one taxonomy batch for the
+ * labels, one UniProt batch for the sequences.
+ *
+ * `taxa`, `exclude` and `limit` mean what they mean for fetchOrthologRows:
+ * `taxa` narrows the targets (omitted, every genome PANTHER has, in its order),
+ * `exclude` drops the query taxon, `limit` caps the rows before their
+ * sequences are fetched.
+ */
+export declare function fetchPantherOrthologs({ candidates, taxId, taxa, exclude, limit, onProgress, }: {
+    candidates: string[];
+    taxId: number;
+    taxa?: Set<number>;
+    exclude?: number;
+    limit?: number;
+    onProgress: (arg: string) => void;
+}): Promise<PantherOrthologs>;

package/dist/utils/pantherOrthologs.js

@@ -0,0 +1,262 @@
+// The second ortholog source, for the genes NCBI's ortholog sets leave out.
+//
+// NCBI Datasets computes orthologs for vertebrates and insects, so a yeast,
+// worm or plant gene comes back with orthologs only in its own clade, and a fly
+// gene gets insects and nothing else. PANTHER's ortholog sets span its 144
+// reference proteomes, human to yeast to Arabidopsis, and one `matchortho` call
+// answers "this gene's ortholog in every genome" with a UniProt accession per
+// target. Sequences come from one UniProt batch call. Both hosts send
+// `Access-Control-Allow-Origin: *`. The measurements that picked PANTHER over
+// OMA, OrthoDB and Ensembl are in react-msaview's
+// agent-docs/ideas/ortholog-sources-beyond-ncbi.md.
+//
+// Rows come out in the same shape as ncbiOrthologs.ts's, so the launch, the
+// labels, the aligner and the CDD overlay do not know which source ran.
+// `protein` is the UniProt accession; efetch serves UniProt accessions as
+// GenPept records with CDD Region features, so the overlay attaches as it does
+// to a RefSeq accession.
+import { jsonfetch } from './fetch';
+import { dedupeLabels, defaultMaxSpecies } from './ncbiOrthologs';
+import { fetchTaxonomyInfo } from './taxonomyNames';
+const PANTHER = 'https://pantherdb.org/services/oai/pantherdb';
+const UNIPROT = 'https://rest.uniprot.org/uniprotkb';
+/**
+ * `supportedgenomes` -> the code<->taxon map every other parse needs. PANTHER
+ * names organisms by code only in ortholog results.
+ */
+export function parseGenomes(json) {
+    const list = json.search?.output?.genomes?.genome ?? [];
+    return list.flatMap(g => g.short_name && g.taxon_id
+        ? [
+            {
+                code: g.short_name,
+                taxId: g.taxon_id,
+                name: g.name ?? g.short_name,
+                longName: g.long_name ?? g.short_name,
+            },
+        ]
+        : []);
+}
+// "HUMAN|HGNC=1773|UniProtKB=P11802" -> { code, geneRef, accession }
+function parseGeneRef(ref) {
+    const [code, ...xrefs] = (ref ?? '').split('|');
+    const accession = xrefs
+        .find(x => x.startsWith('UniProtKB='))
+        ?.slice('UniProtKB='.length);
+    const geneRef = xrefs.find(x => !x.startsWith('UniProtKB=')) ?? accession;
+    return code && accession && geneRef ? { code, accession, geneRef } : undefined;
+}
+/**
+ * `matchortho` -> the query gene (PANTHER names it in every row) and one hit
+ * per target gene. An unknown gene comes back under `unmapped_ids`; a gene with
+ * no ortholog in the target set comes back as a bare `{ id }`.
+ */
+export function parseMatches(json) {
+    const mapping = json.search?.mapping;
+    const mapped = mapping?.mapped;
+    const rows = Array.isArray(mapped) ? mapped : mapped ? [mapped] : [];
+    const hits = [];
+    let query;
+    for (const row of rows) {
+        query ??= parseGeneRef(row.gene);
+        const target = parseGeneRef(row.target_gene);
+        if (target && (row.ortholog === 'LDO' || row.ortholog === 'O')) {
+            hits.push({
+                ...target,
+                symbol: row.target_gene_symbol === undefined
+                    ? undefined
+                    : String(row.target_gene_symbol),
+                type: row.ortholog,
+            });
+        }
+    }
+    return { unmapped: !!mapping?.unmapped_ids, query, hits };
+}
+/**
+ * One hit per organism, in first-seen order: the LDO where PANTHER named one,
+ * else the first other ortholog it listed. A many-to-many family (the Hox
+ * genes) has no LDO at all, so dropping to "first O" is what keeps those
+ * species in the alignment.
+ */
+export function pickOnePerGenome(hits) {
+    const byCode = new Map();
+    for (const hit of hits) {
+        const current = byCode.get(hit.code);
+        if (!current || (current.type === 'O' && hit.type === 'LDO')) {
+            byCode.set(hit.code, hit);
+        }
+    }
+    return [...byCode.values()];
+}
+/** `uniprotkb/accessions` -> accession -> sequence */
+export function parseSequences(json) {
+    const map = new Map();
+    for (const r of json.results ?? []) {
+        if (r.primaryAccession && r.sequence?.value) {
+            map.set(r.primaryAccession, r.sequence.value);
+        }
+    }
+    return map;
+}
+let genomes;
+/** The proteome list, fetched once per page and forgotten on failure. */
+export function fetchGenomes() {
+    genomes ??= jsonfetch(`${PANTHER}/supportedgenomes`)
+        .then(parseGenomes)
+        .catch((e) => {
+        genomes = undefined;
+        throw e;
+    });
+    return genomes;
+}
+// UniProt caps one `accessions` call at 100 ids
+const UNIPROT_CHUNK = 100;
+async function fetchSequences(accessions) {
+    const map = new Map();
+    for (let i = 0; i < accessions.length; i += UNIPROT_CHUNK) {
+        const chunk = accessions.slice(i, i + UNIPROT_CHUNK);
+        const json = await jsonfetch(`${UNIPROT}/accessions?accessions=${chunk.join(',')}&fields=accession,sequence&format=json`);
+        for (const [acc, seq] of parseSequences(json)) {
+            map.set(acc, seq);
+        }
+    }
+    return map;
+}
+// strip a version suffix (NM_000546.6) and any GFF ID prefix (gene:TP53), as
+// resolveGeneId does for NCBI
+function cleanCandidate(raw) {
+    return raw
+        .trim()
+        .replace(/^\w+:/, '')
+        .replace(/\.\d+$/, '');
+}
+/**
+ * One `matchortho` per candidate until PANTHER maps one. A JBrowse feature
+ * carries whatever its GFF/BigBed had — `id()`, `name`, `gene_name` — and only
+ * some of those are names PANTHER knows. `targets` omitted asks for every
+ * genome PANTHER has, which is one call rather than one per genome.
+ */
+async function matchOrthologs(candidates, taxId, targets) {
+    let matched;
+    for (const raw of candidates) {
+        const query = cleanCandidate(raw);
+        if (!query) {
+            continue;
+        }
+        const params = new URLSearchParams({
+            geneInputList: query,
+            organism: String(taxId),
+            orthologType: 'all',
+        });
+        if (targets) {
+            params.set('targetOrganism', targets.map(t => t.taxId).join(','));
+        }
+        const parsed = parseMatches(await jsonfetch(`${PANTHER}/ortholog/matchortho?${params.toString()}`));
+        if (!parsed.unmapped) {
+            matched ??= query;
+            if (parsed.query) {
+                return { ...parsed, matched: query };
+            }
+        }
+    }
+    return matched === undefined
+        ? undefined
+        : { matched, hits: [], query: undefined };
+}
+/**
+ * The whole PANTHER half of the pipeline: gene -> ortholog rows carrying
+ * labels, accessions and sequences, plus the query gene's own protein for the
+ * query row. Two lookups (genomes, orthologs), one taxonomy batch for the
+ * labels, one UniProt batch for the sequences.
+ *
+ * `taxa`, `exclude` and `limit` mean what they mean for fetchOrthologRows:
+ * `taxa` narrows the targets (omitted, every genome PANTHER has, in its order),
+ * `exclude` drops the query taxon, `limit` caps the rows before their
+ * sequences are fetched.
+ */
+export async function fetchPantherOrthologs({ candidates, taxId, taxa, exclude, limit = defaultMaxSpecies, onProgress, }) {
+    const all = await fetchGenomes();
+    const byTaxId = new Map(all.map(g => [g.taxId, g]));
+    const byCode = new Map(all.map(g => [g.code, g]));
+    const queryGenome = byTaxId.get(taxId);
+    if (!queryGenome) {
+        throw new Error(`PANTHER has no reference proteome for taxon ${taxId}. NCBI orthologs cover vertebrates and insects; try that source.`);
+    }
+    const targets = taxa
+        ? [...taxa].flatMap(t => {
+            const g = byTaxId.get(t);
+            return g && t !== exclude ? [g] : [];
+        })
+        : undefined;
+    onProgress('Matching orthologs at PANTHER...');
+    const match = await matchOrthologs(candidates, taxId, targets);
+    if (!match) {
+        throw new Error(`PANTHER has no entry for ${candidates.join(', ')} in ${queryGenome.longName}. Try the NCBI BLAST tab, which needs no gene identifier.`);
+    }
+    const rank = new Map(targets?.map((t, i) => [t.taxId, i]));
+    const picks = pickOnePerGenome(match.hits)
+        .map(hit => ({ hit, genome: byCode.get(hit.code) }))
+        .filter((p) => !!p.genome &&
+        p.genome.taxId !== exclude &&
+        (targets ? rank.has(p.genome.taxId) : true))
+        .sort((a, b) => targets ? rank.get(a.genome.taxId) - rank.get(b.genome.taxId) : 0)
+        .slice(0, limit);
+    if (picks.length < 2) {
+        throw new Error(`Only ${picks.length} PANTHER ortholog(s) found for ${match.matched} — not enough to align`);
+    }
+    onProgress(`Fetching ${picks.length} protein sequences from UniProt...`);
+    const [names, sequences] = await Promise.all([
+        taxonomyNames(picks.map(p => p.genome.taxId)),
+        fetchSequences([
+            ...(match.query ? [match.query.accession] : []),
+            ...picks.map(p => p.hit.accession),
+        ]),
+    ]);
+    const described = picks.map(({ hit, genome }) => {
+        const info = names.get(genome.taxId);
+        return {
+            hit,
+            genome,
+            name: info ? (info.commonName ?? info.sciname) : genome.name,
+            scientificName: info?.sciname || genome.longName,
+            commonName: info?.commonName,
+        };
+    });
+    const labels = dedupeLabels(described.map(d => d.name));
+    const rows = described
+        .map(({ hit, genome, scientificName, commonName }, i) => ({
+        taxId: genome.taxId,
+        label: labels[i],
+        scientificName,
+        commonName,
+        geneId: hit.geneRef,
+        protein: hit.accession,
+        sequence: sequences.get(hit.accession) ?? '',
+    }))
+        .filter(r => r.sequence);
+    if (rows.length < 2) {
+        throw new Error('Could not fetch protein sequences for the orthologs');
+    }
+    const querySequence = match.query && sequences.get(match.query.accession);
+    return {
+        matched: match.matched,
+        query: match.query && querySequence
+            ? { ...match.query, sequence: querySequence }
+            : undefined,
+        rows,
+    };
+}
+/**
+ * NCBI's names for the taxa, so PANTHER rows are labelled exactly as NCBI rows
+ * are. A failed lookup only costs the labels, which fall back to PANTHER's own
+ * short names, so it is logged rather than thrown.
+ */
+async function taxonomyNames(taxIds) {
+    try {
+        return await fetchTaxonomyInfo(taxIds);
+    }
+    catch (e) {
+        console.warn('[msaview-orthologs] taxonomy name lookup failed:', e);
+        return new Map();
+    }
+}

package/dist/utils/workspaces.d.ts

@@ -0,0 +1,34 @@
+import type { AbstractSessionModel } from '@jbrowse/core/util';
+/**
+ * Where a launched MSA view lands. Every launch names one of these and stops
+ * there, so a host that arranges views differently is one function to teach.
+ *
+ *   stack       append below whatever is on screen
+ *   splitRight  its own cell to the right, beside the view it is connected to
+ *   newTab      its own tab in the current cell
+ */
+export type MsaViewPlacement = 'stack' | 'splitRight' | 'newTab';
+/**
+ * What the dialog does unasked. Side-by-side, because a launch from a gene
+ * feature sets `connectedViewId`: the pair shares a hover and a highlight, and
+ * reads as a split. A session spec defaults to `stack` instead.
+ */
+export declare const DEFAULT_LAUNCH_PLACEMENT: MsaViewPlacement;
+export declare const LAUNCH_PLACEMENT_KEY = "msaView-launchPlacement";
+export declare function resetWorkspacesWarning(): void;
+/**
+ * Whether this host can honor anything other than `stack`. Silent: the dialog
+ * asks on every render, and only a launch is worth warning about.
+ */
+export declare function sessionSupportsPlacement(session: AbstractSessionModel): boolean;
+/**
+ * Put a freshly added view where the launch said to. `stack` is a placement
+ * rather than the absence of one, so no caller has to ask what host it is on.
+ */
+export declare function placeMsaView(session: AbstractSessionModel, viewId: string, placement: MsaViewPlacement): void;
+/**
+ * The dialog's own remembered choice — not the host's preferences system, which
+ * records whether the user likes workspaces and does not exist everywhere.
+ */
+export declare function readLaunchPlacement(): MsaViewPlacement;
+export declare function writeLaunchPlacement(placement: MsaViewPlacement): void;

package/dist/utils/workspaces.js

@@ -0,0 +1,100 @@
+const PLACEMENTS = ['stack', 'splitRight', 'newTab'];
+/**
+ * What the dialog does unasked. Side-by-side, because a launch from a gene
+ * feature sets `connectedViewId`: the pair shares a hover and a highlight, and
+ * reads as a split. A session spec defaults to `stack` instead.
+ */
+export const DEFAULT_LAUNCH_PLACEMENT = 'splitRight';
+export const LAUNCH_PLACEMENT_KEY = 'msaView-launchPlacement';
+function hasAction(session, name) {
+    return (name in session &&
+        typeof session[name] === 'function');
+}
+// Warned at most once. This is a property of the host, so the answer is the
+// same on every launch and a dialog the user reopens should not stack up noise.
+let warnedPartial = false;
+export function resetWorkspacesWarning() {
+    warnedPartial = false;
+}
+/**
+ * Whether this host can honor anything other than `stack`. Silent: the dialog
+ * asks on every render, and only a launch is worth warning about.
+ */
+export function sessionSupportsPlacement(session) {
+    return (hasAction(session, 'setUseWorkspaces') &&
+        hasAction(session, 'setPendingMove'));
+}
+function isSessionWithWorkspaces(session) {
+    const canEnable = hasAction(session, 'setUseWorkspaces');
+    const canPlace = hasAction(session, 'setPendingMove');
+    // Missing BOTH is an embedded session: it has no workspaces, there is nothing
+    // to ask for, and silence is the right answer.
+    //
+    // Missing ONE is a host that has workspaces but places views some other way,
+    // and silence there is how the same feature broke in jbrowse-plugin-protein3d
+    // — jbrowse-web folded `setPendingMove` into its layout `init`, the guard went
+    // false, and the plugin simply stopped asking: no error, no missing feature,
+    // two views quietly stacking, nobody noticed for weeks. Feature detection
+    // cannot ask a host to announce a change, but it can tell "not supported here"
+    // from "supported, and gone".
+    //
+    // Two very different hosts produce this one shape and nothing on the session
+    // tells them apart, so the message carries both rather than a guess:
+    //
+    // - releases through v4.3.0, where placement is `setPendingMoveToSplitRight`,
+    //   a module function in @jbrowse/app-core rather than a session action.
+    //   Nothing is wrong and nothing needs fixing
+    // - a newer host that moved the action out from under us, which is the
+    //   regression this warning exists to catch
+    //
+    // Do not quiet the first case by sniffing the version. The alarm is only worth
+    // having if it fires on a shape it cannot explain, and these two are identical.
+    if (canEnable !== canPlace && !warnedPartial) {
+        warnedPartial = true;
+        console.warn(`jbrowse-plugin-msaview: this session supports workspaces but not ` +
+            `${canPlace ? 'setUseWorkspaces' : 'setPendingMove'}, so the MSA view ` +
+            `was stacked instead of tiled. Expected on releases through v4.3.0, ` +
+            `which place views through @jbrowse/app-core instead; on a newer host ` +
+            `it means the session API moved and the plugin needs updating to match.`);
+    }
+    return canEnable && canPlace;
+}
+/**
+ * Put a freshly added view where the launch said to. `stack` is a placement
+ * rather than the absence of one, so no caller has to ask what host it is on.
+ */
+export function placeMsaView(session, viewId, placement) {
+    if (placement === 'stack' || !isSessionWithWorkspaces(session)) {
+        return;
+    }
+    session.setPendingMove({ type: placement, viewId });
+    // Session-scoped: turning workspaces on for this session leaves the user's
+    // own default alone, which is what `setUseWorkspaces` (as against
+    // `setUseWorkspacesPreference`) is for.
+    session.setUseWorkspaces(true);
+}
+function isPlacement(value) {
+    return PLACEMENTS.includes(value);
+}
+/**
+ * The dialog's own remembered choice — not the host's preferences system, which
+ * records whether the user likes workspaces and does not exist everywhere.
+ */
+export function readLaunchPlacement() {
+    try {
+        const stored = globalThis.localStorage.getItem(LAUNCH_PLACEMENT_KEY);
+        return isPlacement(stored) ? stored : DEFAULT_LAUNCH_PLACEMENT;
+    }
+    catch (error) {
+        console.error(error);
+        return DEFAULT_LAUNCH_PLACEMENT;
+    }
+}
+export function writeLaunchPlacement(placement) {
+    try {
+        globalThis.localStorage.setItem(LAUNCH_PLACEMENT_KEY, placement);
+    }
+    catch (error) {
+        console.error(error);
+    }
+}

package/dist/utils/workspaces.test.d.ts

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

package/dist/utils/workspaces.test.js

@@ -0,0 +1,100 @@
+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';
+function makeSession({ canPlace = true, canEnable = true, } = {}) {
+    const recorded = { moves: [], workspaces: [], added: [] };
+    const session = {
+        addView(type, snapshot) {
+            recorded.added.push({ type, snapshot });
+            return { id: `view-${recorded.added.length}` };
+        },
+    };
+    if (canPlace) {
+        session.setPendingMove = (move) => recorded.moves.push(move);
+    }
+    if (canEnable) {
+        session.setUseWorkspaces = (on) => recorded.workspaces.push(on);
+    }
+    return { session: session, 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();
+    vi.stubGlobal('localStorage', {
+        getItem: (key) => store.get(key) ?? null,
+        setItem: (key, value) => 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' }]);
+});

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.1.0";
+export declare const version = "3.3.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = '3.1.0';
+export const version = '3.3.0';

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.1.0",
+  "version": "3.3.0",
   "license": "MIT",
   "name": "jbrowse-plugin-msaview",
   "repository": {
@@ -32,6 +32,8 @@
     "@mui/material": "^9.2.0",
     "@mui/system": "^9.2.0",
     "@mui/x-data-grid": "^9.10.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "esbuild": "^0.28.1",
@@ -41,6 +43,7 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-unicorn": "^72.0.0",
     "git-cliff": "^2.13.1",
+    "jsdom": "^30.0.1",
     "mobx": "^6.16.1",
     "mobx-react": "^9.2.2",
     "msa-parsers": "^6.0.0",

package/src/LaunchMsaView/components/BlastQuery/BlastAutomaticPanel.tsx

@@ -123,6 +123,7 @@ const BlastAutomaticPanel = observer(function ({
         ) : null}
       </LaunchPanelContent>
       <SubmitCancelActions
+        model={model}
         submitDisabled={!proteinSequence}
         onSubmit={() => {
           try {

package/src/LaunchMsaView/components/BlastQuery/BlastManualPanel.tsx

@@ -155,6 +155,7 @@ const BlastManualPanel = observer(function ({
       </LaunchPanelContent>
 
       <SubmitCancelActions
+        model={model}
         submitDisabled={!selectedTranscript || !msaText.trim()}
         onSubmit={() => {
           try {