jbrowse-plugin-protein3d 0.4.11 → 0.4.13

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.11",
+  "version": "0.4.13",
   "name": "jbrowse-plugin-protein3d",
   "repository": {
     "type": "git",
@@ -51,6 +51,8 @@
     "jsdom": "^29.1.1",
     "mobx": "^6.15.4",
     "mobx-react": "^9.2.2",
+    "pixelmatch": "^7.2.0",
+    "pngjs": "^7.0.0",
     "prettier": "^3.8.3",
     "pretty-bytes": "^7.1.0",
     "puppeteer": "^25.1.0",
@@ -86,7 +88,7 @@
     "lint": "eslint src --report-unused-disable-directives --max-warnings 0",
     "pretest": "test -d .test-jbrowse-nightly || jbrowse create .test-jbrowse-nightly --nightly",
     "preversion": "pnpm lint",
-    "version": "node -e \"console.log('export const version = \\'' + require('./package.json').version + '\\'')\" > src/version.ts && git add src/version.ts",
+    "version": "node scripts/sync-version.mjs && git add src/version.ts",
     "postversion": "git push --follow-tags"
   }
 }

package/src/LaunchProteinView/components/LaunchSettingsDialog.tsx

@@ -0,0 +1,63 @@
+import React, { useState } from 'react'
+
+import {
+  Button,
+  Checkbox,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  FormControlLabel,
+  FormGroup,
+  Typography,
+} from '@mui/material'
+
+import { getLaunchSideBySide, setLaunchSideBySide } from '../utils/sideBySide'
+
+// Small, self-contained launch settings (NOT the global preferences dialog):
+// just the options that affect how this protein view opens.
+export default function LaunchSettingsDialog({
+  open,
+  onClose,
+}: {
+  open: boolean
+  onClose: () => void
+}) {
+  const [sideBySide, setSideBySide] = useState(() => getLaunchSideBySide())
+  return (
+    <Dialog
+      open={open}
+      onClose={() => {
+        onClose()
+      }}
+    >
+      <DialogTitle>Launch settings</DialogTitle>
+      <DialogContent>
+        <FormGroup>
+          <FormControlLabel
+            control={<Checkbox checked={sideBySide} />}
+            label="Open protein view side-by-side with the genome view"
+            onChange={(_, checked) => {
+              setSideBySide(checked)
+              setLaunchSideBySide(checked)
+            }}
+          />
+        </FormGroup>
+        <Typography variant="body2" color="text.secondary">
+          When enabled, launching a protein view places it to the right of the
+          connected genome view in a split layout instead of stacking it below.
+        </Typography>
+      </DialogContent>
+      <DialogActions>
+        <Button
+          variant="contained"
+          onClick={() => {
+            onClose()
+          }}
+        >
+          Close
+        </Button>
+      </DialogActions>
+    </Dialog>
+  )
+}

package/src/LaunchProteinView/components/ProteinViewActions.tsx

@@ -2,9 +2,11 @@ import React, { useState } from 'react'
 
 import { ErrorMessage } from '@jbrowse/core/ui'
 import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown'
-import { Button, ButtonGroup, Typography } from '@mui/material'
+import SettingsIcon from '@mui/icons-material/Settings'
+import { Button, ButtonGroup, IconButton, Tooltip, Typography } from '@mui/material'
 
 import LaunchOptionsDialog from './LaunchOptionsDialog'
+import LaunchSettingsDialog from './LaunchSettingsDialog'
 import SequenceMismatchNotice from './SequenceMismatchNotice'
 import { getLaunchMissingReasons, safeLaunch } from '../utils/launchHelpers'
 import {
@@ -58,6 +60,7 @@ export default function ProteinViewActions({
   error,
 }: 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.
@@ -155,6 +158,17 @@ export default function ProteinViewActions({
           onAlignmentAlgorithmChange={onAlignmentAlgorithmChange}
         />
       ) : null}
+      <Tooltip title="Launch settings">
+        <IconButton
+          size="small"
+          aria-label="Launch settings"
+          onClick={() => {
+            setSettingsOpen(true)
+          }}
+        >
+          <SettingsIcon fontSize="small" />
+        </IconButton>
+      </Tooltip>
       <Button
         variant="contained"
         color="secondary"
@@ -189,6 +203,12 @@ export default function ProteinViewActions({
         onClose={closeMenu}
         options={launchOptions}
       />
+      <LaunchSettingsDialog
+        open={settingsOpen}
+        onClose={() => {
+          setSettingsOpen(false)
+        }}
+      />
     </>
   )
 }

package/src/LaunchProteinView/hooks/useAlphaFoldDBSearch.ts

@@ -63,6 +63,7 @@ export default function useAlphaFoldDBSearch({
 
   const {
     isLoading: isAlphaFoldLoading,
+    isValidating: isAlphaFoldValidating,
     error: alphaFoldError,
     url: alphaFoldUrl,
     confidenceUrl: alphaFoldConfidenceUrl,
@@ -93,6 +94,7 @@ export default function useAlphaFoldDBSearch({
     plddtDocUrl: seqSearchConfidenceUrl,
     structureSequence: seqSearchStructureSequence,
     isLoading: isSequenceSearchLoading,
+    isValidating: isSequenceSearchValidating,
     error: sequenceSearchError,
   } = useAlphaFoldSequenceSearch({
     sequence: userSelectedProteinSequence?.seq,
@@ -110,6 +112,14 @@ export default function useAlphaFoldDBSearch({
     : alphaFoldStructureSequence
   const finalUniprotId = isSequenceMode ? seqSearchUniprotId : uniprotId
 
+  // While a structure fetch is in flight, finalStructureSequence may still be
+  // the previous selection's sequence (keepPreviousData). Comparing that stale
+  // sequence to the freshly-selected transcript would give a wrong match, so
+  // the match is treated as unknown until the fetch settles.
+  const isStructureValidating = isSequenceMode
+    ? isSequenceSearchValidating
+    : isAlphaFoldValidating
+
   const loadingStatuses = [
     isLookupLoading && 'Looking up UniProt ID',
     isIsoformLoading && 'Loading protein sequences from transcript isoforms',
@@ -167,7 +177,9 @@ export default function useAlphaFoldDBSearch({
       !!selectedTranscript &&
       (isSequenceMode || !!(finalStructureSequence && finalUniprotId)),
     sequencesMatch:
-      userSelectedProteinSequence?.seq && finalStructureSequence
+      !isStructureValidating &&
+      userSelectedProteinSequence?.seq &&
+      finalStructureSequence
         ? stripStopCodon(userSelectedProteinSequence.seq) ===
           finalStructureSequence
         : undefined,

package/src/LaunchProteinView/hooks/useAlphaFoldData.ts

@@ -14,10 +14,12 @@ export default function useAlphaFoldData({
     ? getAlphaFoldConfidenceUrl(uniprotId)
     : undefined
 
-  const { sequences, isLoading, error } = useStructureFileSequence({ url })
+  const { sequences, isLoading, isValidating, error } =
+    useStructureFileSequence({ url })
 
   return {
     isLoading,
+    isValidating,
     error,
     url,
     confidenceUrl,

package/src/LaunchProteinView/hooks/useAlphaFoldSequenceSearch.ts

@@ -41,19 +41,21 @@ export default function useAlphaFoldSequenceSearch({
     return searchType === 'md5' ? md5(cleanSeq) : cleanSeq
   }, [sequence, searchType])
 
-  const { data, error, isLoading } = useSWR<SequenceSummaryResponse>(
-    enabled && searchValue
-      ? `https://alphafold.ebi.ac.uk/api/sequence/summary?id=${encodeURIComponent(searchValue)}&type=${searchType}`
-      : null,
-    jsonfetch,
-    {
-      ...STATIC_SWR_OPTIONS,
-      keepPreviousData: true,
-    },
-  )
+  const { data, error, isLoading, isValidating } =
+    useSWR<SequenceSummaryResponse>(
+      enabled && searchValue
+        ? `https://alphafold.ebi.ac.uk/api/sequence/summary?id=${encodeURIComponent(searchValue)}&type=${searchType}`
+        : null,
+      jsonfetch,
+      {
+        ...STATIC_SWR_OPTIONS,
+        keepPreviousData: true,
+      },
+    )
 
   return {
     isLoading,
+    isValidating,
     result: data,
     uniprotId: data?.uniprotAccession,
     cifUrl: data?.cifUrl,

package/src/LaunchProteinView/hooks/useFoldseekSearch.ts

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 
 import {
   DEFAULT_DATABASES,
@@ -23,21 +23,43 @@ export default function useFoldseekSearch() {
   const [error, setError] = useState<unknown>()
   const [statusMessage, setStatusMessage] = useState('')
 
+  // Aborts the in-flight request (3Di prediction or the up-to-3-minute Foldseek
+  // poll) when the dialog closes/unmounts, so it stops hitting the external API
+  // and stops updating dead state.
+  const abortRef = useRef<AbortController | null>(null)
+  useEffect(() => {
+    return () => {
+      abortRef.current?.abort()
+    }
+  }, [])
+
+  const startOperation = () => {
+    abortRef.current?.abort()
+    const controller = new AbortController()
+    abortRef.current = controller
+    return controller.signal
+  }
+
   const predictStructure = async (aaSequence: string) => {
+    const signal = startOperation()
     setIsPredicting(true)
     setError(undefined)
     setStatusMessage('Predicting 3Di structure...')
     try {
-      const result = await predict3Di(aaSequence)
+      const result = await predict3Di({ aaSequence, signal })
       setPredictData(result)
       return result
     } catch (e) {
-      console.error(e)
-      setError(e)
+      if (!signal.aborted) {
+        console.error(e)
+        setError(e)
+      }
       return undefined
     } finally {
-      setIsPredicting(false)
-      setStatusMessage('')
+      if (!signal.aborted) {
+        setIsPredicting(false)
+        setStatusMessage('')
+      }
     }
   }
 
@@ -46,25 +68,40 @@ export default function useFoldseekSearch() {
     di3Seq: string,
     databases: FoldseekDatabaseId[] = DEFAULT_DATABASES,
   ) => {
+    const signal = startOperation()
     setIsLoading(true)
     setError(undefined)
     setStatusMessage('Submitting search...')
     try {
-      const ticket = await submitFoldseekSearch(aaSeq, di3Seq, databases)
-      const result = await waitForFoldseekResults(ticket.id, setStatusMessage)
+      const ticket = await submitFoldseekSearch({
+        aaSequence: aaSeq,
+        di3Sequence: di3Seq,
+        databases,
+        signal,
+      })
+      const result = await waitForFoldseekResults({
+        ticketId: ticket.id,
+        onStatusChange: setStatusMessage,
+        signal,
+      })
       setResults(result)
       return result
     } catch (e) {
-      console.error(e)
-      setError(e)
+      if (!signal.aborted) {
+        console.error(e)
+        setError(e)
+      }
       return undefined
     } finally {
-      setIsLoading(false)
-      setStatusMessage('')
+      if (!signal.aborted) {
+        setIsLoading(false)
+        setStatusMessage('')
+      }
     }
   }
 
   const reset = () => {
+    abortRef.current?.abort()
     setResults(undefined)
     setPredictData(undefined)
     setError(undefined)

package/src/LaunchProteinView/hooks/useStructureFileSequence.ts

@@ -45,7 +45,7 @@ export default function useStructureFileSequence({
     : url
       ? (['structure-url', url] as const)
       : null
-  const { data, error, isLoading } = useSWR<string[] | undefined>(
+  const { data, error, isLoading, isValidating } = useSWR<string[] | undefined>(
     key,
     async () => {
       const seq = await fetchSequences({ file, url })
@@ -60,5 +60,8 @@ export default function useStructureFileSequence({
     },
   )
 
-  return { error, isLoading, sequences: data }
+  // isValidating distinguishes "fetching for the current key" from the stale
+  // data keepPreviousData keeps around during a key change. Consumers comparing
+  // this sequence against another need it to avoid matching against stale data.
+  return { error, isLoading, isValidating, sequences: data }
 }

package/src/LaunchProteinView/services/foldseekApi.ts

@@ -61,7 +61,13 @@ export interface FoldseekResult {
   results: FoldseekDatabaseResult[]
 }
 
-export async function predict3Di(aaSequence: string) {
+export async function predict3Di({
+  aaSequence,
+  signal,
+}: {
+  aaSequence: string
+  signal?: AbortSignal
+}) {
   // Clean the sequence - remove FASTA header, whitespace, stop codons, and non-AA chars
   const cleanSequence = aaSequence
     .split('\n')
@@ -74,6 +80,7 @@ export async function predict3Di(aaSequence: string) {
 
   const response = await fetch(
     `https://3di.foldseek.com/predict/${encodeURIComponent(cleanSequence)}`,
+    { signal },
   )
   if (!response.ok) {
     throw new Error(
@@ -89,11 +96,17 @@ export async function predict3Di(aaSequence: string) {
   return { aaSequence: cleanSequence, di3Sequence: cleanDi3 }
 }
 
-export async function submitFoldseekSearch(
-  aaSequence: string,
-  di3Sequence: string,
-  databases: FoldseekDatabaseId[],
-) {
+export async function submitFoldseekSearch({
+  aaSequence,
+  di3Sequence,
+  databases,
+  signal,
+}: {
+  aaSequence: string
+  di3Sequence: string
+  databases: FoldseekDatabaseId[]
+  signal?: AbortSignal
+}) {
   // Submit both AA and 3Di sequences (with trailing newline like working example)
   const fastaContent = `>query\n${aaSequence}\n>3DI\n${di3Sequence}\n`
   const params = new URLSearchParams()
@@ -110,20 +123,27 @@ export async function submitFoldseekSearch(
       'Content-Type': 'application/x-www-form-urlencoded',
     },
     body: params,
+    signal,
   })
 
-  const responseData = await response.json()
-
+  // Read the body as text first so a non-JSON error page (e.g. a gateway/500
+  // HTML response) surfaces the real status instead of an opaque JSON
+  // SyntaxError that hides it.
+  const text = await response.text()
   if (!response.ok) {
-    throw new Error(
-      `Foldseek submission failed: ${response.status} ${JSON.stringify(responseData)}`,
-    )
+    throw new Error(`Foldseek submission failed: ${response.status} ${text}`)
   }
 
-  return responseData as FoldseekTicketResponse
+  return JSON.parse(text) as FoldseekTicketResponse
 }
 
-export async function pollFoldseekStatus(ticketId: string) {
+export async function pollFoldseekStatus({
+  ticketId,
+  signal,
+}: {
+  ticketId: string
+  signal?: AbortSignal
+}) {
   // Use the /tickets endpoint (plural) with POST
   const params = new URLSearchParams()
   params.append('tickets[]', ticketId)
@@ -134,6 +154,7 @@ export async function pollFoldseekStatus(ticketId: string) {
       'Content-Type': 'application/x-www-form-urlencoded',
     },
     body: params,
+    signal,
   })
 
   if (!response.ok) {
@@ -160,23 +181,36 @@ interface FoldseekApiResponse {
   }[]
 }
 
-export async function getFoldseekResults(
-  ticketId: string,
-): Promise<FoldseekApiResponse> {
+export async function getFoldseekResults({
+  ticketId,
+  signal,
+}: {
+  ticketId: string
+  signal?: AbortSignal
+}): Promise<FoldseekApiResponse> {
   return jsonfetch<FoldseekApiResponse>(
     `https://search.foldseek.com/api/result/${ticketId}/0`,
+    { signal },
   )
 }
 
-export async function waitForFoldseekResults(
-  ticketId: string,
-  onStatusChange?: (status: string) => void,
-) {
+export async function waitForFoldseekResults({
+  ticketId,
+  onStatusChange,
+  signal,
+}: {
+  ticketId: string
+  onStatusChange?: (status: string) => void
+  signal?: AbortSignal
+}) {
   const maxAttempts = 180
   let attempts = 0
 
   while (attempts < maxAttempts) {
-    const status = await pollFoldseekStatus(ticketId)
+    if (signal?.aborted) {
+      throw signal.reason
+    }
+    const status = await pollFoldseekStatus({ ticketId, signal })
 
     if (status.status === 'ERROR') {
       console.error('[Foldseek] Search error:', status)
@@ -187,7 +221,7 @@ export async function waitForFoldseekResults(
 
     if (status.status === 'COMPLETE') {
       onStatusChange?.('Fetching results...')
-      const apiResponse = await getFoldseekResults(ticketId)
+      const apiResponse = await getFoldseekResults({ ticketId, signal })
 
       // Transform API response to our format
       const results: FoldseekResult = {
@@ -204,7 +238,7 @@ export async function waitForFoldseekResults(
     onStatusChange?.(
       `Search ${status.status.toLowerCase()}... (${attempts + 1}s)`,
     )
-    await timeout(1000)
+    await timeout(1000, signal)
     attempts++
   }
 

package/src/LaunchProteinView/utils/launchViewUtils.ts

@@ -6,6 +6,7 @@ declare global {
   }
 }
 
+import { getLaunchSideBySide, launchViewSideBySide } from './sideBySide'
 import { getGeneDisplayName, getTranscriptDisplayName } from './util'
 import { launchProteinAnnotationView } from '../components/launchProteinAnnotationView'
 
@@ -113,6 +114,7 @@ export function launch3DProteinView({
   alignmentAlgorithm,
   displayName,
   connectedMsaViewId,
+  sideBySide,
 }: LaunchViewParams & {
   url?: string
   data?: string
@@ -120,6 +122,9 @@ export function launch3DProteinView({
   alignmentAlgorithm?: string
   displayName?: string
   connectedMsaViewId?: string
+  // explicit override; when undefined the launch-dialog localStorage preference
+  // decides (left genome | right protein)
+  sideBySide?: boolean
 }) {
   const snap = {
     type: 'ProteinView',
@@ -138,7 +143,11 @@ export function launch3DProteinView({
       displayName ??
       formatViewName('Protein view', feature, selectedTranscript, uniprotId),
   }
-  return session.addView('ProteinView', snap)
+  const proteinView = session.addView('ProteinView', snap)
+  if (sideBySide ?? getLaunchSideBySide()) {
+    launchViewSideBySide(session, proteinView.id)
+  }
+  return proteinView
 }
 
 export async function launch1DProteinView({

package/src/LaunchProteinView/utils/sideBySide.ts

@@ -0,0 +1,55 @@
+import type { AbstractSessionModel } from '@jbrowse/core/util'
+
+// Self-contained launch preference (NOT the global/core preferences system):
+// whether a protein view launched from a genome feature opens side-by-side with
+// its connected genome view (left genome | right protein) instead of stacked.
+const SIDE_BY_SIDE_KEY = 'proteinView-launchSideBySide'
+
+// Default to side-by-side: a connected genome+protein pair reads best as a
+// left/right split. Users can turn it off in the launch dialog's settings.
+const DEFAULT_SIDE_BY_SIDE = true
+
+export function getLaunchSideBySide() {
+  const stored = localStorage.getItem(SIDE_BY_SIDE_KEY)
+  return stored === null ? DEFAULT_SIDE_BY_SIDE : stored === 'true'
+}
+
+export function setLaunchSideBySide(value: boolean) {
+  localStorage.setItem(SIDE_BY_SIDE_KEY, value ? 'true' : 'false')
+}
+
+// The workspaces split is driven by two session actions that only exist on the
+// web/desktop session (MultipleViews + DockviewLayout mixins). Embedded sessions
+// lack them, so feature-detect before using.
+interface SessionWithWorkspaces {
+  setUseWorkspaces: (useWorkspaces: boolean) => void
+  setPendingMove: (move: { type: 'splitRight'; viewId: string }) => void
+}
+
+function isSessionWithWorkspaces(
+  session: AbstractSessionModel,
+): session is AbstractSessionModel & SessionWithWorkspaces {
+  return (
+    'setUseWorkspaces' in session &&
+    typeof session.setUseWorkspaces === 'function' &&
+    'setPendingMove' in session &&
+    typeof session.setPendingMove === 'function'
+  )
+}
+
+/**
+ * Place a freshly-added view to the right of the others in a workspaces (tiled)
+ * layout. Mirrors the "Move to split view" view-menu action: queue a splitRight
+ * pending move for this view, then enable workspaces so TiledViewsContainer
+ * consumes the move on mount (other views land in the left panel, this one in a
+ * new right panel). No-op on sessions without workspaces support.
+ */
+export function launchViewSideBySide(
+  session: AbstractSessionModel,
+  viewId: string,
+) {
+  if (isSessionWithWorkspaces(session)) {
+    session.setPendingMove({ type: 'splitRight', viewId })
+    session.setUseWorkspaces(true)
+  }
+}

package/src/LaunchProteinViewExtensionPoint/index.ts

@@ -1,4 +1,8 @@
 import { type ConnectedViewSpec, resolveShortLaunch } from './resolveShortLaunch'
+import {
+  getLaunchSideBySide,
+  launchViewSideBySide,
+} from '../LaunchProteinView/utils/sideBySide'
 
 import type PluginManager from '@jbrowse/core/PluginManager'
 import type { AbstractSessionModel } from '@jbrowse/core/util'
@@ -28,6 +32,7 @@ export default function LaunchProteinViewExtensionPointF(
       showControls,
       showHighlight,
       zoomToBaseLevel,
+      sideBySide,
     }: {
       session: AbstractSessionModel
       url?: string
@@ -43,6 +48,10 @@ export default function LaunchProteinViewExtensionPointF(
       showControls?: boolean
       showHighlight?: boolean
       zoomToBaseLevel?: boolean
+      // when this launch creates its own connected genome view, place the
+      // protein view side-by-side (left genome | right protein). Explicit
+      // override; falls back to the launch-dialog localStorage preference.
+      sideBySide?: boolean
     }) => {
       // Short-URL form: `uniprotId` + `transcriptId` + `connectedView` (no
       // explicit `url`/`feature`/sequence). Derive the structure URL, the
@@ -77,6 +86,9 @@ export default function LaunchProteinViewExtensionPointF(
       // `connectedView` is supplied we create the LinearGenomeView here and wire
       // its id, letting a single spec entry produce a connected genome+protein
       // pair (e.g. hover a variant to highlight the residue).
+      // a connected view this launch created itself can be split beside the
+      // protein view; a pre-existing connectedViewId is left in place
+      const ownsConnectedView = !connectedViewId && !!connectedView
       const resolvedConnectedViewId =
         connectedViewId ??
         (connectedView
@@ -86,7 +98,7 @@ export default function LaunchProteinViewExtensionPointF(
             }).id
           : undefined)
 
-      session.addView('ProteinView', {
+      const proteinView = session.addView('ProteinView', {
         type: 'ProteinView',
         alignmentAlgorithm,
         displayName,
@@ -106,6 +118,10 @@ export default function LaunchProteinViewExtensionPointF(
           },
         ],
       })
+
+      if (ownsConnectedView && (sideBySide ?? getLaunchSideBySide())) {
+        launchViewSideBySide(session, proteinView.id)
+      }
     },
   )
 }