jbrowse-plugin-protein3d 0.5.2 → 0.5.4

package/dist/Protein1DViewRegistry/index.js

@@ -1,7 +1,6 @@
 import { SimpleFeature } from '@jbrowse/core/util';
-import { getCodonRange } from 'g2p_mapper';
 import { action, computed, makeObservable, observable } from 'mobx';
-import { genomeToTranscriptSeqMapping } from '../mappings';
+import { codonGenomeSpan, genomeToTranscriptSeqMapping } from '../mappings';
 class Protein1DViewRegistry {
     views = observable.map();
     constructor() {
@@ -53,13 +52,9 @@ class Protein1DViewRegistry {
         if (!mapping) {
             return undefined;
         }
-        const { p2g, strand, refName } = mapping;
-        const result = getCodonRange(p2g, proteinPos, strand);
-        if (!result) {
-            return undefined;
-        }
-        const [start, end] = result;
-        return { refName, start, end };
+        const { p2gCodon, refName } = mapping;
+        const span = codonGenomeSpan(p2gCodon, proteinPos);
+        return span ? { refName, start: span[0], end: span[1] } : undefined;
     }
 }
 export const protein1DViewRegistry = new Protein1DViewRegistry();

package/dist/ProteinView/__fixtures__/structureFixtures.d.ts

@@ -0,0 +1,7 @@
+export declare const HBA_ALPHA_4HHB_ENTITY0 = "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR";
+export declare const HBB_BETA_4HHB_ENTITY1 = "VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH";
+export declare const HBA_TRANSCRIPT_P69905 = "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR";
+export declare const HBB_TRANSCRIPT_P68871 = "MVHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH";
+export declare const DNA_1TUP_ENTITY0 = "TTTCCTAGACTTGCCCAATTA";
+export declare const P53_1TUP_ENTITY2 = "SSSVPSQKTYQGSYGFRLGFLHSGTAKSVTCTYSPALNKMFCQLAKTCPVQLWVDSTPPPGTRVRAMAIYKQSQHMTEVVRRCPHHERCSDSDGLAPPQHLIRVEGNLRVEYLDDRNTFRHSVVVPYEPPEVGSDCTTIHYNYMCNSSCMGGMNRRPILTIITLEDSSGNLLGRNSFEVRVCACPGRDRRTEEENLRKKGEPHHELPPGSTKRALPNNT";
+export declare const P53_TRANSCRIPT_P04637 = "MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGPDEAPRMPEAAPPVAPAPAAPTPAAPAPAPSWPLSSSVPSQKTYQGSYGFRLGFLHSGTAKSVTCTYSPALNKMFCQLAKTCPVQLWVDSTPPPGTRVRAMAIYKQSQHMTEVVRRCPHHERCSDSDGLAPPQHLIRVEGNLRVEYLDDRNTFRHSVVVPYEPPEVGSDCTTIHYNYMCNSSCMGGMNRRPILTIITLEDSSGNLLGRNSFEVRVCACPGRDRRTEEENLRKKGEPHHELPPGSTKRALPNNTSSSPQPKKKPLDGEYFTLQIRGRERFEMFRELNEALELKDAQAGKEPGGSRAHSSHLKSKKGQSTSRHKKLMFKTEGPDSD";

package/dist/ProteinView/__fixtures__/structureFixtures.js

@@ -0,0 +1,16 @@
+// Real entity sequences (RCSB entity_poly one-letter, canonical) and transcript
+// sequences (UniProt canonical) for structures the entity-[0] assumption maps
+// wrong. Frozen here so the tests are deterministic and offline.
+//
+// 4HHB: hemoglobin α/β tetramer — entity[0] is the α chain, so a β (HBB)
+//   transcript must NOT map to [0]. (PDB strips the initiator Met, hence the
+//   leading-M difference vs UniProt.)
+// 1TUP: p53 core bound to DNA — entity[0] and [1] are DNA strands; the protein
+//   is entity[2].
+export const HBA_ALPHA_4HHB_ENTITY0 = 'VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR';
+export const HBB_BETA_4HHB_ENTITY1 = 'VHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH';
+export const HBA_TRANSCRIPT_P69905 = 'MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR';
+export const HBB_TRANSCRIPT_P68871 = 'MVHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPWTQRFFESFGDLSTPDAVMGNPKVKAHGKKVLGAFSDGLAHLDNLKGTFATLSELHCDKLHVDPENFRLLGNVLVCVLAHHFGKEFTPPVQAAYQKVVAGVANALAHKYH';
+export const DNA_1TUP_ENTITY0 = 'TTTCCTAGACTTGCCCAATTA';
+export const P53_1TUP_ENTITY2 = 'SSSVPSQKTYQGSYGFRLGFLHSGTAKSVTCTYSPALNKMFCQLAKTCPVQLWVDSTPPPGTRVRAMAIYKQSQHMTEVVRRCPHHERCSDSDGLAPPQHLIRVEGNLRVEYLDDRNTFRHSVVVPYEPPEVGSDCTTIHYNYMCNSSCMGGMNRRPILTIITLEDSSGNLLGRNSFEVRVCACPGRDRRTEEENLRKKGEPHHELPPGSTKRALPNNT';
+export const P53_TRANSCRIPT_P04637 = 'MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGPDEAPRMPEAAPPVAPAPAAPTPAAPAPAPSWPLSSSVPSQKTYQGSYGFRLGFLHSGTAKSVTCTYSPALNKMFCQLAKTCPVQLWVDSTPPPGTRVRAMAIYKQSQHMTEVVRRCPHHERCSDSDGLAPPQHLIRVEGNLRVEYLDDRNTFRHSVVVPYEPPEVGSDCTTIHYNYMCNSSCMGGMNRRPILTIITLEDSSGNLLGRNSFEVRVCACPGRDRRTEEENLRKKGEPHHELPPGSTKRALPNNTSSSPQPKKKPLDGEYFTLQIRGRERFEMFRELNEALELKDAQAGKEPGGSRAHSSHLKSKKGQSTSRHKKLMFKTEGPDSD';

package/dist/ProteinView/applyLociInteractivity.d.ts

@@ -21,9 +21,12 @@ export type ResidueSpec = {
  * channel, so callers describe the target state declaratively rather than
  * juggling clear/apply calls.
  */
-export declare function setMolstarLoci({ structure, plugin, channel, spec, }: {
+export declare function setMolstarLoci({ structure, plugin, channel, spec, entityId, }: {
     structure: Structure;
     plugin: PluginContext;
     channel: 'highlight' | 'select';
     spec: ResidueSpec | undefined;
+    /** Confine the loci to this mmCIF entity so a residue number doesn't light up
+     * on unrelated chains (binding partners, the other half of a homodimer). */
+    entityId?: string;
 }): Promise<void>;

package/dist/ProteinView/applyLociInteractivity.js

@@ -14,7 +14,7 @@ const isActive = (spec) => spec !== undefined &&
  * channel, so callers describe the target state declaratively rather than
  * juggling clear/apply calls.
  */
-export async function setMolstarLoci({ structure, plugin, channel, spec, }) {
+export async function setMolstarLoci({ structure, plugin, channel, spec, entityId, }) {
     const { lociHighlights, lociSelects } = plugin.managers.interactivity;
     if (channel === 'highlight') {
         lociHighlights.clearHighlights();
@@ -25,6 +25,14 @@ export async function setMolstarLoci({ structure, plugin, channel, spec, }) {
     if (isActive(spec)) {
         const { StructureSelection, Script } = await loadMolstar();
         const sel = Script.getStructureSelection(Q => Q.struct.generator.atomGroups({
+            ...(entityId
+                ? {
+                    'chain-test': Q.core.rel.eq([
+                        Q.struct.atomProperty.macromolecular.label_entity_id(),
+                        entityId,
+                    ]),
+                }
+                : {}),
             'residue-test': specToTest(spec)(Q),
             'group-by': Q.struct.atomProperty.macromolecular.residueKey(),
         }), structure);

package/dist/ProteinView/chooseMappedEntity.d.ts

@@ -0,0 +1,32 @@
+import type { PairwiseAlignment } from '../mappings';
+import type { AlignmentAlgorithm } from './types';
+/**
+ * Whether a structure interaction (hover/click) should drive genome navigation.
+ * Only the transcript's mapped entity may — a hover on any other chain carries
+ * that chain's own label_seq_id and would mis-map through the wrong alignment.
+ * A structure with no resolved mapping (`mappedEntityId` undefined, e.g. a
+ * standalone viewer with no transcript) stays fully interactive.
+ */
+export declare function interactionMatchesMappedEntity(entityId: string, mappedEntityId: string | undefined): boolean;
+export interface EntitySelection {
+    /** index into the entity-sequence array that best matches the transcript */
+    index: number;
+    /** alignment of the transcript against the chosen entity (stop codons
+     * stripped on both sides, matching the rest of the mapping pipeline) */
+    alignment: PairwiseAlignment;
+    /** identical aligned residues, the score used to pick the entity */
+    matches: number;
+}
+/**
+ * Pick which polymer entity of a structure corresponds to the transcript.
+ *
+ * The plugin historically hardcoded entity `[0]`, which silently mis-maps every
+ * heteromeric / protein-DNA / processed-peptide structure where the protein of
+ * interest is some other chain. Selecting by alignment makes the structure self-
+ * describe which entity is the gene's protein: an exact sequence match wins
+ * outright, otherwise the entity with the most identical aligned residues.
+ *
+ * Returns `undefined` only when there is nothing to map (no transcript or no
+ * entities) — never a silent fallback to the wrong entity.
+ */
+export declare function chooseMappedEntity(transcript: string, entitySeqs: string[], algorithm: AlignmentAlgorithm): EntitySelection | undefined;

package/dist/ProteinView/chooseMappedEntity.js

@@ -0,0 +1,71 @@
+import { runLocalAlignment } from './pairwiseAlignment';
+import { stripStopCodon } from '../LaunchProteinView/utils/util';
+/**
+ * Whether a structure interaction (hover/click) should drive genome navigation.
+ * Only the transcript's mapped entity may — a hover on any other chain carries
+ * that chain's own label_seq_id and would mis-map through the wrong alignment.
+ * A structure with no resolved mapping (`mappedEntityId` undefined, e.g. a
+ * standalone viewer with no transcript) stays fully interactive.
+ */
+export function interactionMatchesMappedEntity(entityId, mappedEntityId) {
+    return mappedEntityId === undefined || entityId === mappedEntityId;
+}
+function countMatches(pa) {
+    const a = pa.alns[0].seq;
+    const b = pa.alns[1].seq;
+    let matches = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ca = a[i];
+        const cb = b[i];
+        if (ca !== '-' && cb !== '-' && ca?.toUpperCase() === cb?.toUpperCase()) {
+            matches++;
+        }
+    }
+    return matches;
+}
+/**
+ * Pick which polymer entity of a structure corresponds to the transcript.
+ *
+ * The plugin historically hardcoded entity `[0]`, which silently mis-maps every
+ * heteromeric / protein-DNA / processed-peptide structure where the protein of
+ * interest is some other chain. Selecting by alignment makes the structure self-
+ * describe which entity is the gene's protein: an exact sequence match wins
+ * outright, otherwise the entity with the most identical aligned residues.
+ *
+ * Returns `undefined` only when there is nothing to map (no transcript or no
+ * entities) — never a silent fallback to the wrong entity.
+ */
+export function chooseMappedEntity(transcript, entitySeqs, algorithm) {
+    const t = stripStopCodon(transcript);
+    if (!t || entitySeqs.length === 0) {
+        return undefined;
+    }
+    const stripped = entitySeqs.map(stripStopCodon);
+    const exactIndex = stripped.findIndex(s => s.length > 0 && s === t);
+    if (exactIndex !== -1) {
+        return {
+            index: exactIndex,
+            alignment: {
+                consensus: '|'.repeat(t.length),
+                alns: [
+                    { id: 'seq1', seq: t },
+                    { id: 'seq2', seq: stripped[exactIndex] },
+                ],
+            },
+            matches: t.length,
+        };
+    }
+    let best;
+    for (let index = 0; index < stripped.length; index++) {
+        const s = stripped[index];
+        if (s.length === 0) {
+            continue;
+        }
+        const alignment = runLocalAlignment(t, s, algorithm);
+        const matches = countMatches(alignment);
+        if (!best || matches > best.matches) {
+            best = { index, alignment, matches };
+        }
+    }
+    return best;
+}

package/dist/ProteinView/components/FeatureBar.js

@@ -56,6 +56,7 @@ const FeatureBar = observer(function FeatureBar({ feature, model, }) {
                 structure,
                 plugin: molstarPluginContext,
                 channel: 'select',
+                entityId: model.mappedEntityId,
                 spec: newSelected
                     ? { kind: 'range', start: feature.start - 1, end: feature.end }
                     : undefined,

package/dist/ProteinView/extractStructureSequences.d.ts

@@ -1,8 +1,17 @@
+/** A polymer entity of a loaded structure: its mmCIF entity id and its full
+ * (label_seq_id-indexed) one-letter sequence. The entity id is what lets every
+ * downstream step talk about "the gene's protein" by identity instead of by the
+ * fragile entity-[0] position. */
+export interface Entity {
+    entityId: string;
+    seq: string;
+}
 interface StructureModel {
     obj?: {
         data: {
             sequence: {
                 sequences: readonly {
+                    entityId: string;
                     sequence: {
                         label: {
                             toArray(): ArrayLike<string>;
@@ -13,5 +22,8 @@ interface StructureModel {
         };
     };
 }
+export declare function extractEntities(model: StructureModel): Entity[] | undefined;
+/** Back-compat helper for callers that only need the sequence strings (e.g. the
+ * launch dialog's isoform matching). */
 export declare function extractStructureSequences(model: StructureModel): string[] | undefined;
 export {};

package/dist/ProteinView/extractStructureSequences.js

@@ -1,3 +1,11 @@
+export function extractEntities(model) {
+    return model.obj?.data.sequence.sequences.map(s => ({
+        entityId: s.entityId,
+        seq: Array.from(s.sequence.label.toArray()).join(''),
+    }));
+}
+/** Back-compat helper for callers that only need the sequence strings (e.g. the
+ * launch dialog's isoform matching). */
 export function extractStructureSequences(model) {
-    return model.obj?.data.sequence.sequences.map(s => Array.from(s.sequence.label.toArray()).join(''));
+    return extractEntities(model)?.map(e => e.seq);
 }

package/dist/ProteinView/loadStructureData.d.ts

@@ -1,6 +1,7 @@
+import type { Entity } from './extractStructureSequences';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context';
 export interface StructureData {
-    sequences?: string[];
+    entities?: Entity[];
     confidence?: number[];
 }
 /**

package/dist/ProteinView/loadStructureData.js

@@ -1,7 +1,7 @@
 import { addStructureFromData } from './addStructureFromData';
 import { addStructureFromURL } from './addStructureFromURL';
 import { extractPerResidueConfidence } from './extractPerResidueConfidence';
-import { extractStructureSequences } from './extractStructureSequences';
+import { extractEntities } from './extractStructureSequences';
 /**
  * Loads a structure (from inline data or a URL) into the given Molstar plugin
  * and pulls out its per-chain sequences and per-residue confidence. Pure with
@@ -14,9 +14,9 @@ export async function loadStructureData({ structure, plugin, }) {
         : structure.url
             ? await addStructureFromURL({ url: structure.url, plugin })
             : { model: undefined };
-    const sequences = model ? extractStructureSequences(model) : undefined;
+    const entities = model ? extractEntities(model) : undefined;
     const confidence = model
-        ? extractPerResidueConfidence(model, sequences?.[0]?.length)
+        ? extractPerResidueConfidence(model, entities?.[0]?.seq.length)
         : undefined;
-    return { sequences, confidence };
+    return { entities, confidence };
 }

package/dist/ProteinView/model.d.ts

@@ -47,10 +47,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hoverPosition: {
             structureSeqPos?: number;
             code?: string;
-            chain?: string;
+            chain? /**
+             * #action
+             */: string;
             source: "structure" | "genome";
         } | undefined;
-        structureSequences: string[] | undefined;
+        entities: import("./extractStructureSequences").Entity[] | undefined;
+        mappedEntityIndex: number;
         structureConfidence: number[] | undefined;
         isMouseInAlignment: boolean;
         loadedToMolstar: boolean;
@@ -62,7 +65,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hiddenFeatureTypes: Set<string>;
     } & {
         setStructureData(data: {
-            sequences?: string[];
+            entities?: import("./extractStructureSequences").Entity[];
             confidence?: number[];
         }): void;
         hideFeatureType(type: string): void;
@@ -581,8 +584,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         }): void;
         setGenomeHoveredPosition(structureSeqPos?: number): void;
         setAlignment(r?: import("../mappings").PairwiseAlignment): void;
+        setMappedEntityIndex(n: number): void;
         setIsMouseInAlignment(val: boolean): void;
     } & {
+        readonly structureSequences: string[] | undefined;
+        readonly mappedEntity: import("./extractStructureSequences").Entity | undefined;
+        readonly mappedStructureSeq: string | undefined;
+        readonly mappedEntityId: string | undefined;
         readonly uniprotId: string | undefined;
         readonly coordinateMapper: import("./coordinates").CoordinateMapper | undefined;
         readonly structureSeqToTranscriptSeqPosition: Record<number, number> | undefined;
@@ -795,10 +803,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hoverPosition: {
             structureSeqPos?: number;
             code?: string;
-            chain?: string;
+            chain? /**
+             * #action
+             */: string;
             source: "structure" | "genome";
         } | undefined;
-        structureSequences: string[] | undefined;
+        entities: import("./extractStructureSequences").Entity[] | undefined;
+        mappedEntityIndex: number;
         structureConfidence: number[] | undefined;
         isMouseInAlignment: boolean;
         loadedToMolstar: boolean;
@@ -810,7 +821,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hiddenFeatureTypes: Set<string>;
     } & {
         setStructureData(data: {
-            sequences?: string[];
+            entities?: import("./extractStructureSequences").Entity[];
             confidence?: number[];
         }): void;
         hideFeatureType(type: string): void;
@@ -1329,8 +1340,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         }): void;
         setGenomeHoveredPosition(structureSeqPos?: number): void;
         setAlignment(r?: import("../mappings").PairwiseAlignment): void;
+        setMappedEntityIndex(n: number): void;
         setIsMouseInAlignment(val: boolean): void;
     } & {
+        readonly structureSequences: string[] | undefined;
+        readonly mappedEntity: import("./extractStructureSequences").Entity | undefined;
+        readonly mappedStructureSeq: string | undefined;
+        readonly mappedEntityId: string | undefined;
         readonly uniprotId: string | undefined;
         readonly coordinateMapper: import("./coordinates").CoordinateMapper | undefined;
         readonly structureSeqToTranscriptSeqPosition: Record<number, number> | undefined;
@@ -1422,10 +1438,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hoverPosition: {
             structureSeqPos?: number;
             code?: string;
-            chain?: string;
+            chain? /**
+             * #action
+             */: string;
             source: "structure" | "genome";
         } | undefined;
-        structureSequences: string[] | undefined;
+        entities: import("./extractStructureSequences").Entity[] | undefined;
+        mappedEntityIndex: number;
         structureConfidence: number[] | undefined;
         isMouseInAlignment: boolean;
         loadedToMolstar: boolean;
@@ -1437,7 +1456,7 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         hiddenFeatureTypes: Set<string>;
     } & {
         setStructureData(data: {
-            sequences?: string[];
+            entities?: import("./extractStructureSequences").Entity[];
             confidence?: number[];
         }): void;
         hideFeatureType(type: string): void;
@@ -1956,8 +1975,13 @@ declare function stateModelFactory(): import("@jbrowse/mobx-state-tree").IModelT
         }): void;
         setGenomeHoveredPosition(structureSeqPos?: number): void;
         setAlignment(r?: import("../mappings").PairwiseAlignment): void;
+        setMappedEntityIndex(n: number): void;
         setIsMouseInAlignment(val: boolean): void;
     } & {
+        readonly structureSequences: string[] | undefined;
+        readonly mappedEntity: import("./extractStructureSequences").Entity | undefined;
+        readonly mappedStructureSeq: string | undefined;
+        readonly mappedEntityId: string | undefined;
         readonly uniprotId: string | undefined;
         readonly coordinateMapper: import("./coordinates").CoordinateMapper | undefined;
         readonly structureSeqToTranscriptSeqPosition: Record<number, number> | undefined;

package/dist/ProteinView/proteinToGenomeMapping.d.ts

@@ -2,7 +2,7 @@ import type { PairwiseAlignment } from '../mappings';
 import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
 import type { LinearGenomeViewModel } from '@jbrowse/plugin-linear-genome-view';
 interface GenomeToTranscriptSeqMapping {
-    p2g: Record<number, number>;
+    p2gCodon: Record<number, number[]>;
     strand: number;
     refName: string;
 }

package/dist/ProteinView/proteinToGenomeMapping.js

@@ -1,5 +1,5 @@
 import { getSession } from '@jbrowse/core/util';
-import { getCodonRange } from 'g2p_mapper';
+import { codonGenomeSpan } from '../mappings';
 /**
  * Maps a protein structure position to genome coordinates
  * @returns [start, end] tuple of genome coordinates, or undefined if mapping fails
@@ -9,12 +9,11 @@ export function proteinToGenomeMapping({ model, structureSeqPos, }) {
     if (!genomeToTranscriptSeqMapping || !pairwiseAlignment) {
         return undefined;
     }
-    const { p2g, strand } = genomeToTranscriptSeqMapping;
+    const { p2gCodon } = genomeToTranscriptSeqMapping;
     const transcriptPos = structureSeqToTranscriptSeqPosition?.[structureSeqPos];
-    if (transcriptPos === undefined) {
-        return undefined;
-    }
-    return getCodonRange(p2g, transcriptPos, strand);
+    return transcriptPos === undefined
+        ? undefined
+        : codonGenomeSpan(p2gCodon, transcriptPos);
 }
 /**
  * Maps a protein structure range to genome coordinates
@@ -63,7 +62,11 @@ export async function navigateToProteinPosition({ model, structureSeqPos, struct
     }
     const [start, end] = result;
     if (zoomToBaseLevel) {
-        await connectedView.navToLocString(`${refName}:${start}-${end}${strand === -1 ? '[rev]' : ''}`, undefined, 0.2);
+        // start/end are 0-based half-open (from getCodonRanges). navToLocString
+        // parses a 1-based locString (parseLocString does start -= 1), so the start
+        // must be shifted to 1-based; the half-open end already equals the 1-based
+        // inclusive end. Passing the raw 0-based start landed the view 1bp 5'.
+        await connectedView.navToLocString(`${refName}:${start + 1}-${end}${strand === -1 ? '[rev]' : ''}`, undefined, 0.2);
     }
     else {
         const { assemblyManager } = session;

package/dist/ProteinView/structureModel.d.ts

@@ -1,5 +1,6 @@
 import { type Instance } from '@jbrowse/mobx-state-tree';
 import { type CoordinateMapper } from './coordinates';
+import type { Entity } from './extractStructureSequences';
 import type { PairwiseAlignment } from '../mappings';
 import type { AlignmentAlgorithm } from './types';
 import type { SimpleFeatureSerialized } from '@jbrowse/core/util';
@@ -91,7 +92,15 @@ declare const Structure: import("@jbrowse/mobx-state-tree").IModelType<{
     /**
      * #volatile
      */
-    structureSequences: string[] | undefined;
+    entities: Entity[] | undefined;
+    /**
+     * #volatile
+     * Index into entities of the one that matches the transcript. Resolved by
+     * alignment (see chooseMappedEntity) instead of assuming the protein of
+     * interest is entity [0], which mis-maps heteromers / protein-DNA complexes /
+     * processed peptides.
+     */
+    mappedEntityIndex: number;
     /**
      * #volatile
      * Per-residue B-factor / pLDDT for the first chain, indexed by 0-based
@@ -127,7 +136,7 @@ declare const Structure: import("@jbrowse/mobx-state-tree").IModelType<{
     hiddenFeatureTypes: Set<string>;
 } & {
     setStructureData(data: {
-        sequences?: string[];
+        entities?: Entity[];
         confidence?: number[];
     }): void;
     /**
@@ -189,11 +198,37 @@ declare const Structure: import("@jbrowse/mobx-state-tree").IModelType<{
      * #action
      */
     setAlignment(r?: PairwiseAlignment): void;
+    /**
+     * #action
+     */
+    setMappedEntityIndex(n: number): void;
     /**
      * #action
      */
     setIsMouseInAlignment(val: boolean): void;
 } & {
+    /**
+     * #getter
+     * Sequence strings of every polymer entity (back-compat for the alignment
+     * autorun and presence checks).
+     */
+    readonly structureSequences: string[] | undefined;
+    /**
+     * #getter
+     * The entity that maps to the transcript (chosen by chooseMappedEntity), not
+     * blindly entity [0].
+     */
+    readonly mappedEntity: Entity | undefined;
+    /**
+     * #getter
+     */
+    readonly mappedStructureSeq: string | undefined;
+    /**
+     * #getter
+     * mmCIF entity id of the mapped entity. Used to reject hovers/clicks on
+     * other chains and to confine highlights to the gene's protein.
+     */
+    readonly mappedEntityId: string | undefined;
     /**
      * #getter
      * Extracts UniProt ID from AlphaFold URL if available
@@ -227,6 +262,9 @@ declare const Structure: import("@jbrowse/mobx-state-tree").IModelType<{
      * #getter
      * Per-residue pLDDT values mapped to alignment columns, shown only when the
      * structure's B-factor column actually looks like AlphaFold confidence.
+     * pLDDT is an AlphaFold concept — those models are single-entity, so the
+     * mapped entity is always [0] and structureConfidence (extracted from [0])
+     * stays coherent.
      */
     readonly confidenceCells: {
         col: number;