jbrowse-plugin-protein3d 0.4.13 → 0.5.0

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.4.13";
+export declare const version = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = '0.4.13';
+export const version = '0.5.0';

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.13",
+  "version": "0.5.0",
   "name": "jbrowse-plugin-protein3d",
   "repository": {
     "type": "git",

package/src/LaunchProteinView/components/FoldseekActionMenu.tsx

@@ -1,10 +1,11 @@
 import React, { useState } from 'react'
 
 import { ErrorMessage } from '@jbrowse/core/ui'
+import { isSessionWithAddTracks } from '@jbrowse/core/util'
 import { Button, Menu, MenuItem } from '@mui/material'
 
+import { useSafeLaunch } from '../hooks/useSafeLaunch'
 import { caCoordsToPdb, hasValidCaCoords } from '../utils/caCoordsToPdb'
-import { safeLaunch } from '../utils/launchHelpers'
 import {
   getConfidenceUrlFromTarget,
   getUniprotIdFromAlphaFoldTarget,
@@ -41,7 +42,6 @@ export default function FoldseekActionMenu({
   onClose: () => void
 }) {
   const [anchorEl, setAnchorEl] = useState<null | HTMLElement>(null)
-  const [launchError, setLaunchError] = useState<unknown>()
   const open = Boolean(anchorEl)
 
   const uniprotId = getUniprotIdFromAlphaFoldTarget(hit.target)
@@ -54,12 +54,9 @@ export default function FoldseekActionMenu({
     setAnchorEl(null)
   }
 
-  const baseParams = { session, view, feature, selectedTranscript, uniprotId }
+  const { runLaunch, launchError } = useSafeLaunch(onClose, handleMenuClose)
 
-  const runLaunch = (fn: () => void | Promise<void>) => () => {
-    handleMenuClose()
-    void safeLaunch(fn, onClose, setLaunchError)
-  }
+  const baseParams = { session, view, feature, selectedTranscript, uniprotId }
 
   const handleLaunch3D = runLaunch(() => {
     // Use tCa coordinates to generate PDB data if no URL is available
@@ -75,22 +72,19 @@ export default function FoldseekActionMenu({
     })
   })
 
-  const handleLaunch1D = runLaunch(async () => {
-    await launch1DProteinView({
-      ...baseParams,
-      confidenceUrl: getConfidenceUrlFromTarget(hit.target),
-    })
-  })
-
   const handleLaunchMSA = runLaunch(() => {
     launchMsaView(baseParams)
   })
 
-  const canLoad = hit.structureUrl ?? hasValidCaCoords(hit.tCa, hit.tSeq)
+  const canLoad = !!hit.structureUrl || hasValidCaCoords(hit.tCa, hit.tSeq)
   if (!canLoad) {
     return <span>-</span>
   }
 
+  // 1D launch needs an add-tracks session and a uniprotId; narrowing both here
+  // gates the menu item and types its handler from a single condition.
+  const addTracksSession = isSessionWithAddTracks(session) ? session : undefined
+
   return (
     <>
       {launchError ? <ErrorMessage error={launchError} /> : null}
@@ -99,8 +93,19 @@ export default function FoldseekActionMenu({
       </Button>
       <Menu anchorEl={anchorEl} open={open} onClose={handleMenuClose}>
         <MenuItem onClick={handleLaunch3D}>Launch 3D protein view</MenuItem>
-        {uniprotId ? (
-          <MenuItem onClick={handleLaunch1D}>
+        {addTracksSession && uniprotId ? (
+          <MenuItem
+            onClick={runLaunch(() =>
+              launch1DProteinView({
+                session: addTracksSession,
+                view,
+                feature,
+                selectedTranscript,
+                uniprotId,
+                confidenceUrl: getConfidenceUrlFromTarget(hit.target),
+              }),
+            )}
+          >
             Launch 1D protein annotation view
           </MenuItem>
         ) : null}

package/src/LaunchProteinView/components/ProteinViewActions.tsx

@@ -1,6 +1,7 @@
 import React, { useState } from 'react'
 
 import { ErrorMessage } from '@jbrowse/core/ui'
+import { isSessionWithAddTracks } from '@jbrowse/core/util'
 import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown'
 import SettingsIcon from '@mui/icons-material/Settings'
 import { Button, ButtonGroup, IconButton, Tooltip, Typography } from '@mui/material'
@@ -8,7 +9,8 @@ import { Button, ButtonGroup, IconButton, Tooltip, Typography } from '@mui/mater
 import LaunchOptionsDialog from './LaunchOptionsDialog'
 import LaunchSettingsDialog from './LaunchSettingsDialog'
 import SequenceMismatchNotice from './SequenceMismatchNotice'
-import { getLaunchMissingReasons, safeLaunch } from '../utils/launchHelpers'
+import { useSafeLaunch } from '../hooks/useSafeLaunch'
+import { getLaunchMissingReasons } from '../utils/launchHelpers'
 import {
   hasMsaViewPlugin,
   launch1DProteinView,
@@ -61,7 +63,6 @@ export default function ProteinViewActions({
 }: ProteinViewActionsProps) {
   const [dialogOpen, setDialogOpen] = useState(false)
   const [settingsOpen, setSettingsOpen] = useState(false)
-  const [launchError, setLaunchError] = useState<unknown>()
   // Disable launch while loading — SWR's keepPreviousData would otherwise let
   // a user click Launch on stale results (wrong UniProt ID) during a refetch.
   const canLaunch =
@@ -82,6 +83,8 @@ export default function ProteinViewActions({
     setDialogOpen(false)
   }
 
+  const { runLaunch, launchError } = useSafeLaunch(handleClose, closeMenu)
+
   const baseParams = {
     session,
     view,
@@ -96,19 +99,10 @@ export default function ProteinViewActions({
     alignmentAlgorithm,
   }
 
-  const runLaunch = (fn: () => void | Promise<void>) => () => {
-    closeMenu()
-    void safeLaunch(fn, handleClose, setLaunchError)
-  }
-
   const handleLaunch3DView = runLaunch(() => {
     launch3DProteinView(launch3DParams)
   })
 
-  const handleLaunch1DView = runLaunch(async () => {
-    await launch1DProteinView({ ...baseParams, confidenceUrl })
-  })
-
   const handleLaunchMsa = runLaunch(() => {
     launchMsaView(baseParams)
   })
@@ -117,6 +111,13 @@ export default function ProteinViewActions({
     launch3DProteinViewWithMsa(launch3DParams)
   })
 
+  // The 1D annotation view needs an add-tracks session and a known uniprotId.
+  // Narrowing here is the single source of truth: the option only exists when
+  // both hold, and its handler is type-checked against those narrowed values —
+  // so a 1D launch that can't work is unrepresentable rather than a silent
+  // no-op.
+  const addTracksSession = isSessionWithAddTracks(session) ? session : undefined
+
   const launchOptions = [
     {
       key: '3d',
@@ -125,12 +126,26 @@ export default function ProteinViewActions({
         'View protein structure with genome-to-structure coordinate mapping',
       onClick: handleLaunch3DView,
     },
-    {
-      key: '1d',
-      title: 'Launch 1D protein annotation view',
-      description: 'View protein features and annotations as a linear track',
-      onClick: handleLaunch1DView,
-    },
+    ...(addTracksSession && uniprotId
+      ? [
+          {
+            key: '1d',
+            title: 'Launch 1D protein annotation view',
+            description:
+              'View protein features and annotations as a linear track',
+            onClick: runLaunch(() =>
+              launch1DProteinView({
+                session: addTracksSession,
+                view,
+                feature,
+                selectedTranscript,
+                uniprotId,
+                confidenceUrl,
+              }),
+            ),
+          },
+        ]
+      : []),
     ...(hasMsaViewPlugin()
       ? [
           {

package/src/LaunchProteinView/components/UserProvidedStructure.tsx

@@ -13,11 +13,7 @@ import ExternalLink from '../../components/ExternalLink'
 import useStructureFileSequence from '../hooks/useStructureFileSequence'
 import useTranscriptIsoformSelection from '../hooks/useTranscriptIsoformSelection'
 import { launch3DProteinView } from '../utils/launchViewUtils'
-import {
-  getGeneDisplayName,
-  getTranscriptDisplayName,
-  stripStopCodon,
-} from '../utils/util'
+import { stripStopCodon } from '../utils/util'
 
 import type { AlignmentAlgorithm } from '../../ProteinView/types'
 import type { AbstractSessionModel, Feature } from '@jbrowse/core/util'
@@ -117,7 +113,6 @@ const UserProvidedStructure = observer(function UserProvidedStructure({
         data: structureData,
         userProvidedTranscriptSequence: protein.seq,
         alignmentAlgorithm,
-        displayName: `Protein view ${getGeneDisplayName(feature)} - ${getTranscriptDisplayName(selectedTranscript)}`,
       })
       handleClose()
     } catch (e) {

package/src/LaunchProteinView/hooks/useSafeLaunch.ts

@@ -0,0 +1,17 @@
+import { useState } from 'react'
+
+import { safeLaunch } from '../utils/launchHelpers'
+
+/**
+ * Shared launch-button wiring for the action components: holds the launch
+ * error state and returns a `runLaunch` factory that closes any open menu,
+ * runs the launch via safeLaunch, and surfaces failures inline.
+ */
+export function useSafeLaunch(onSuccess: () => void, onBeforeLaunch?: () => void) {
+  const [launchError, setLaunchError] = useState<unknown>()
+  const runLaunch = (fn: () => void | Promise<void>) => () => {
+    onBeforeLaunch?.()
+    void safeLaunch(fn, onSuccess, setLaunchError)
+  }
+  return { runLaunch, launchError }
+}

package/src/LaunchProteinView/utils/launchViewUtils.ts

@@ -1,16 +1,18 @@
-import { isSessionWithAddTracks } from '@jbrowse/core/util'
-
 declare global {
   interface Window {
     JBrowsePluginMsaView?: unknown
   }
 }
 
-import { getLaunchSideBySide, launchViewSideBySide } from './sideBySide'
+import { maybeLaunchSideBySide } from './sideBySide'
 import { getGeneDisplayName, getTranscriptDisplayName } from './util'
 import { launchProteinAnnotationView } from '../components/launchProteinAnnotationView'
 
-import type { AbstractSessionModel, Feature } from '@jbrowse/core/util'
+import type {
+  AbstractSessionModel,
+  Feature,
+  SessionWithAddTracks,
+} from '@jbrowse/core/util'
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view'
 
 export const ALPHAFOLD_VERSION = 'v6'
@@ -84,6 +86,14 @@ interface LaunchViewParams {
   uniprotId?: string
 }
 
+interface Launch3DExtraParams {
+  url?: string
+  data?: string
+  userProvidedTranscriptSequence?: string
+  alignmentAlgorithm?: string
+  displayName?: string
+}
+
 export function formatViewName(
   prefix: string,
   feature: Feature,
@@ -115,17 +125,13 @@ export function launch3DProteinView({
   displayName,
   connectedMsaViewId,
   sideBySide,
-}: LaunchViewParams & {
-  url?: string
-  data?: string
-  userProvidedTranscriptSequence?: string
-  alignmentAlgorithm?: string
-  displayName?: string
-  connectedMsaViewId?: string
-  // explicit override; when undefined the launch-dialog localStorage preference
-  // decides (left genome | right protein)
-  sideBySide?: boolean
-}) {
+}: LaunchViewParams &
+  Launch3DExtraParams & {
+    connectedMsaViewId?: string
+    // explicit override; when undefined the launch-dialog localStorage
+    // preference decides (left genome | right protein)
+    sideBySide?: boolean
+  }) {
   const snap = {
     type: 'ProteinView',
     alignmentAlgorithm,
@@ -144,12 +150,14 @@ export function launch3DProteinView({
       formatViewName('Protein view', feature, selectedTranscript, uniprotId),
   }
   const proteinView = session.addView('ProteinView', snap)
-  if (sideBySide ?? getLaunchSideBySide()) {
-    launchViewSideBySide(session, proteinView.id)
-  }
+  maybeLaunchSideBySide(session, proteinView.id, sideBySide)
   return proteinView
 }
 
+// The 1D annotation view adds temporary tracks/assemblies, so it requires a
+// SessionWithAddTracks and a known uniprotId. Demanding both in the signature
+// forces callers to narrow up front — there's no silent no-op when a wide
+// session or missing id slips through.
 export async function launch1DProteinView({
   session,
   view,
@@ -157,12 +165,11 @@ export async function launch1DProteinView({
   selectedTranscript,
   uniprotId,
   confidenceUrl,
-}: LaunchViewParams & {
+}: Omit<LaunchViewParams, 'session' | 'uniprotId'> & {
+  session: SessionWithAddTracks
+  uniprotId: string
   confidenceUrl?: string
 }) {
-  if (!uniprotId || !isSessionWithAddTracks(session)) {
-    return
-  }
   await launchProteinAnnotationView({
     session,
     selectedTranscript,
@@ -209,13 +216,7 @@ export function hasMsaViewPlugin() {
 }
 
 export function launch3DProteinViewWithMsa(
-  params: LaunchViewParams & {
-    url?: string
-    data?: string
-    userProvidedTranscriptSequence?: string
-    alignmentAlgorithm?: string
-    displayName?: string
-  },
+  params: LaunchViewParams & Launch3DExtraParams,
 ) {
   const { uniprotId } = params
   if (!uniprotId) {

package/src/LaunchProteinView/utils/sideBySide.ts

@@ -53,3 +53,17 @@ export function launchViewSideBySide(
     session.setUseWorkspaces(true)
   }
 }
+
+/**
+ * Apply the side-by-side split honoring an explicit override, falling back to
+ * the launch-dialog localStorage preference when undefined.
+ */
+export function maybeLaunchSideBySide(
+  session: AbstractSessionModel,
+  viewId: string,
+  sideBySide?: boolean,
+) {
+  if (sideBySide ?? getLaunchSideBySide()) {
+    launchViewSideBySide(session, viewId)
+  }
+}

package/src/LaunchProteinViewExtensionPoint/index.ts

@@ -1,8 +1,5 @@
 import { type ConnectedViewSpec, resolveShortLaunch } from './resolveShortLaunch'
-import {
-  getLaunchSideBySide,
-  launchViewSideBySide,
-} from '../LaunchProteinView/utils/sideBySide'
+import { maybeLaunchSideBySide } from '../LaunchProteinView/utils/sideBySide'
 
 import type PluginManager from '@jbrowse/core/PluginManager'
 import type { AbstractSessionModel } from '@jbrowse/core/util'
@@ -76,9 +73,11 @@ export default function LaunchProteinViewExtensionPointF(
 
       const finalUrl = url ?? resolved?.url
       if (!finalUrl) {
-        throw new Error(
-          'No url or uniprotId provided when launching protein view',
-        )
+        const message =
+          'No url or uniprotId provided when launching protein view'
+        console.error(message)
+        session.notify(`Could not launch protein view: ${message}`, 'error')
+        return
       }
 
       // A session spec launches each view independently with an auto-generated
@@ -119,8 +118,8 @@ export default function LaunchProteinViewExtensionPointF(
         ],
       })
 
-      if (ownsConnectedView && (sideBySide ?? getLaunchSideBySide())) {
-        launchViewSideBySide(session, proteinView.id)
+      if (ownsConnectedView) {
+        maybeLaunchSideBySide(session, proteinView.id, sideBySide)
       }
     },
   )

package/src/ProteinView/applyLociInteractivity.ts

@@ -1,133 +1,81 @@
 import loadMolstar from './loadMolstar'
-import { getMolstarStructureSelection } from './util'
 
-import type {
-  Structure,
-  StructureElement,
-} from 'molstar/lib/mol-model/structure'
+import type { Structure } from 'molstar/lib/mol-model/structure'
 import type { PluginContext } from 'molstar/lib/mol-plugin/context'
+import type { MolScriptBuilder } from 'molstar/lib/mol-script/language/builder'
+import type { Expression } from 'molstar/lib/mol-script/language/expression'
 
-type InteractivityMode = 'highlight' | 'select' | 'clear'
+type ResidueTest = (Q: typeof MolScriptBuilder) => Expression
 
-function clearLoci(plugin: PluginContext) {
-  plugin.managers.interactivity.lociHighlights.clearHighlights()
-  plugin.managers.interactivity.lociSelects.deselectAll()
-}
+/**
+ * Which residues a highlight/selection should cover, in the plugin's native
+ * 0-based structure-sequence coordinates (see coordinates.ts). `range` is the
+ * half-open span [start, end); `list` is an explicit set of positions. The one
+ * conversion to molstar's 1-based inclusive label_seq_id happens in specToTest
+ * below — the single boundary where structure positions cross into molstar.
+ */
+export type ResidueSpec =
+  | { kind: 'range'; start: number; end: number }
+  | { kind: 'list'; residues: number[] }
 
-function applyLoci(
-  plugin: PluginContext,
-  loci: StructureElement.Loci,
-  mode: 'highlight' | 'select',
-) {
-  if (mode === 'highlight') {
-    plugin.managers.interactivity.lociHighlights.clearHighlights()
-    plugin.managers.interactivity.lociHighlights.highlight({ loci })
-  } else {
-    plugin.managers.interactivity.lociSelects.deselectAll()
-    plugin.managers.interactivity.lociSelects.select({ loci })
-  }
-}
+const seqId = (Q: typeof MolScriptBuilder) =>
+  Q.struct.atomProperty.macromolecular.label_seq_id()
 
-export async function applyLociInteractivityMultiple({
-  structure,
-  residues,
-  plugin,
-  mode,
-}: {
-  structure: Structure
-  residues: number[]
-  plugin: PluginContext
-  mode: InteractivityMode
-}) {
-  if (mode === 'clear' || residues.length === 0) {
-    clearLoci(plugin)
-    return
-  }
-
-  const { StructureSelection, Script } = await loadMolstar()
+const specToTest = (spec: ResidueSpec): ResidueTest =>
+  spec.kind === 'range'
+    ? Q =>
+        Q.core.logic.and([
+          Q.core.rel.gre([seqId(Q), spec.start + 1]),
+          Q.core.rel.lte([seqId(Q), spec.end]),
+        ])
+    : Q =>
+        Q.core.logic.or(
+          spec.residues.map(pos => Q.core.rel.eq([seqId(Q), pos + 1])),
+        )
 
-  const sel = Script.getStructureSelection(
-    Q =>
-      Q.struct.generator.atomGroups({
-        'residue-test': Q.core.logic.or(
-          residues.map(residue =>
-            Q.core.rel.eq([
-              Q.struct.atomProperty.macromolecular.label_seq_id(),
-              residue,
-            ]),
-          ),
-        ),
-        'group-by': Q.struct.atomProperty.macromolecular.residueKey(),
-      }),
-    structure,
-  )
+const isActive = (spec: ResidueSpec | undefined): spec is ResidueSpec =>
+  spec !== undefined &&
+  (spec.kind === 'range' ? spec.end > spec.start : spec.residues.length > 0)
 
-  const loci = StructureSelection.toLociWithSourceUnits(sel)
-  applyLoci(plugin, loci, mode)
-}
-
-export async function applyLociInteractivity({
+/**
+ * Reconcile one interactivity channel (hover-`highlight` or click-`select`) to
+ * the desired residue spec. Passing `undefined` (or an empty `list`) clears the
+ * channel, so callers describe the target state declaratively rather than
+ * juggling clear/apply calls.
+ */
+export async function setMolstarLoci({
   structure,
-  startResidue,
-  endResidue,
   plugin,
-  mode,
+  channel,
+  spec,
 }: {
   structure: Structure
-  startResidue: number
-  endResidue: number
   plugin: PluginContext
-  mode: InteractivityMode
+  channel: 'highlight' | 'select'
+  spec: ResidueSpec | undefined
 }) {
-  if (mode === 'clear') {
-    clearLoci(plugin)
-    return
+  const { lociHighlights, lociSelects } = plugin.managers.interactivity
+  if (channel === 'highlight') {
+    lociHighlights.clearHighlights()
+  } else {
+    lociSelects.deselectAll()
   }
 
-  const { StructureSelection, Script } = await loadMolstar()
-  const sel = Script.getStructureSelection(
-    Q =>
-      Q.struct.generator.atomGroups({
-        'residue-test': Q.core.logic.and([
-          Q.core.rel.gre([
-            Q.struct.atomProperty.macromolecular.label_seq_id(),
-            startResidue,
-          ]),
-          Q.core.rel.lte([
-            Q.struct.atomProperty.macromolecular.label_seq_id(),
-            endResidue,
-          ]),
-        ]),
-        'group-by': Q.struct.atomProperty.macromolecular.residueKey(),
-      }),
-    structure,
-  )
-
-  const loci = StructureSelection.toLociWithSourceUnits(sel)
-  applyLoci(plugin, loci, mode)
-}
-
-export async function applyLociInteractivitySingle({
-  structure,
-  selectedResidue,
-  plugin,
-  mode,
-}: {
-  structure: Structure
-  selectedResidue: number
-  plugin: PluginContext
-  mode: InteractivityMode
-}) {
-  if (mode === 'clear') {
-    clearLoci(plugin)
-    return
+  if (isActive(spec)) {
+    const { StructureSelection, Script } = await loadMolstar()
+    const sel = Script.getStructureSelection(
+      Q =>
+        Q.struct.generator.atomGroups({
+          'residue-test': specToTest(spec)(Q),
+          'group-by': Q.struct.atomProperty.macromolecular.residueKey(),
+        }),
+      structure,
+    )
+    const loci = StructureSelection.toLociWithSourceUnits(sel)
+    if (channel === 'highlight') {
+      lociHighlights.highlight({ loci })
+    } else {
+      lociSelects.select({ loci })
+    }
   }
-
-  const { StructureSelection } = await loadMolstar()
-  const sel = await getMolstarStructureSelection({
-    structure,
-    selectedResidue: selectedResidue + 1,
-  })
-  const loci = StructureSelection.toLociWithSourceUnits(sel)
-  applyLoci(plugin, loci, mode)
 }