p2s_mapper 1.0.0

package/dist/uniProtSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniProtSearch.js","sourceRoot":"","sources":["../src/uniProtSearch.ts"],"names":[],"mappings":"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"}

package/esm/alignmentQuality.d.ts

@@ -0,0 +1,58 @@
+import type { PairwiseAlignment } from './mappings.ts';
+export interface AlignmentQuality {
+    /** columns carrying a residue on both rows, i.e. mapped positions */
+    aligned: number;
+    identical: number;
+    transcriptLength: number;
+    structureLength: number;
+    /** identical over aligned; 0 when nothing aligned */
+    identity: number;
+    /** identical over the shorter of the two sequences: the statistic that
+     * separates a real match from a chance local alignment, see below */
+    identityOverShorter: number;
+    /** aligned over the structure's length */
+    structureCoverage: number;
+    /** first and last transcript residue the alignment covers, 1-based
+     * inclusive; 0 when nothing aligned. A structure is usually a fragment, and
+     * which part of the protein it holds is the reader's first question. */
+    transcriptStart: number;
+    transcriptEnd: number;
+}
+/**
+ * Below either floor the mapped positions are as likely to be chance as
+ * homology. Local alignment picks the best-scoring stretch of two sequences,
+ * so identity over the aligned columns is inflated whatever the inputs:
+ * measured 2026-09-11 on random sequences, Smith-Waterman with BLOSUM62 gave
+ * 37% identity over 27 columns at 300 × 300 and 30% over 100 columns at
+ * 500 × 150, two thirds of the shorter chain, and p53 against a ribosomal
+ * protein (7K00 RPS11) gives 31 identities at a third identity. Neither local
+ * identity nor coverage alone separates those from a real match. Identical
+ * residues over the shorter sequence does: 0.03, 0.20 and 0.24 for the chance
+ * cases against 0.9 or better for any structure of the transcript's protein
+ * and about 0.6 for an ortholog.
+ *
+ * A short alignment has to be nearly perfect instead: a 10-residue decoy with
+ * 3 identities sits at the ratio floor, while a real bound peptide (1YCR's 15
+ * p53 residues, 4ZZJ's 7) is identical or one off. So under
+ * SHORT_ALIGNMENT_RESIDUES identical residues the ratio floor rises to
+ * SHORT_ALIGNMENT_IDENTITY, and under MIN_IDENTICAL_RESIDUES nothing passes,
+ * since a tetrapeptide is never the gene's product.
+ */
+export declare const LOW_IDENTITY_OVER_SHORTER = 0.3;
+export declare const SHORT_ALIGNMENT_RESIDUES = 20;
+export declare const SHORT_ALIGNMENT_IDENTITY = 0.8;
+export declare const MIN_IDENTICAL_RESIDUES = 5;
+export declare function alignmentQuality(pa: PairwiseAlignment): AlignmentQuality;
+export declare function isLowSimilarity(q: AlignmentQuality): boolean;
+/** One line for the alignment header: "87% identity over 219 of 393
+ * structure residues". */
+export declare function describeAlignmentQuality(q: AlignmentQuality): string;
+/**
+ * The same counted from the transcript's side, for the always-visible header:
+ * how much of the gene's protein this structure speaks for is what decides
+ * whether a codon has a residue at all.
+ */
+export declare function describeTranscriptCoverage(q: AlignmentQuality): string;
+/** Which residues of the transcript a fragment holds, or undefined when it
+ * covers the whole translation. */
+export declare function describeCoveredRange(q: AlignmentQuality): string | undefined;

package/esm/alignmentQuality.js

@@ -0,0 +1,100 @@
+import { alignmentLength, structureAlignedSeq, transcriptAlignedSeq, } from "./mappings.js";
+/**
+ * Below either floor the mapped positions are as likely to be chance as
+ * homology. Local alignment picks the best-scoring stretch of two sequences,
+ * so identity over the aligned columns is inflated whatever the inputs:
+ * measured 2026-09-11 on random sequences, Smith-Waterman with BLOSUM62 gave
+ * 37% identity over 27 columns at 300 × 300 and 30% over 100 columns at
+ * 500 × 150, two thirds of the shorter chain, and p53 against a ribosomal
+ * protein (7K00 RPS11) gives 31 identities at a third identity. Neither local
+ * identity nor coverage alone separates those from a real match. Identical
+ * residues over the shorter sequence does: 0.03, 0.20 and 0.24 for the chance
+ * cases against 0.9 or better for any structure of the transcript's protein
+ * and about 0.6 for an ortholog.
+ *
+ * A short alignment has to be nearly perfect instead: a 10-residue decoy with
+ * 3 identities sits at the ratio floor, while a real bound peptide (1YCR's 15
+ * p53 residues, 4ZZJ's 7) is identical or one off. So under
+ * SHORT_ALIGNMENT_RESIDUES identical residues the ratio floor rises to
+ * SHORT_ALIGNMENT_IDENTITY, and under MIN_IDENTICAL_RESIDUES nothing passes,
+ * since a tetrapeptide is never the gene's product.
+ */
+export const LOW_IDENTITY_OVER_SHORTER = 0.3;
+export const SHORT_ALIGNMENT_RESIDUES = 20;
+export const SHORT_ALIGNMENT_IDENTITY = 0.8;
+export const MIN_IDENTICAL_RESIDUES = 5;
+export function alignmentQuality(pa) {
+    const t = transcriptAlignedSeq(pa);
+    const s = structureAlignedSeq(pa);
+    let aligned = 0;
+    let identical = 0;
+    let transcriptLength = 0;
+    let structureLength = 0;
+    let transcriptStart = 0;
+    let transcriptEnd = 0;
+    for (let i = 0; i < alignmentLength(pa); i++) {
+        const a = t[i];
+        const b = s[i];
+        const ta = a !== '-';
+        const sb = b !== '-';
+        if (ta) {
+            transcriptLength++;
+        }
+        if (sb) {
+            structureLength++;
+        }
+        if (ta && sb) {
+            aligned++;
+            transcriptStart = transcriptStart || transcriptLength;
+            transcriptEnd = transcriptLength;
+            if (a.toUpperCase() === b.toUpperCase()) {
+                identical++;
+            }
+        }
+    }
+    const shorter = Math.min(transcriptLength, structureLength);
+    return {
+        aligned,
+        identical,
+        transcriptLength,
+        structureLength,
+        identity: aligned ? identical / aligned : 0,
+        identityOverShorter: shorter ? identical / shorter : 0,
+        structureCoverage: structureLength ? aligned / structureLength : 0,
+        transcriptStart,
+        transcriptEnd,
+    };
+}
+export function isLowSimilarity(q) {
+    const floor = q.identical < SHORT_ALIGNMENT_RESIDUES
+        ? SHORT_ALIGNMENT_IDENTITY
+        : LOW_IDENTITY_OVER_SHORTER;
+    return q.identical < MIN_IDENTICAL_RESIDUES || q.identityOverShorter < floor;
+}
+/** One line for the alignment header: "87% identity over 219 of 393
+ * structure residues". */
+export function describeAlignmentQuality(q) {
+    if (q.aligned === 0) {
+        return 'no residues aligned';
+    }
+    return `${Math.round(q.identity * 100)}% identity over ${q.aligned} of ${q.structureLength} structure residues`;
+}
+/**
+ * The same counted from the transcript's side, for the always-visible header:
+ * how much of the gene's protein this structure speaks for is what decides
+ * whether a codon has a residue at all.
+ */
+export function describeTranscriptCoverage(q) {
+    if (q.aligned === 0) {
+        return 'no residues aligned';
+    }
+    return `${Math.round(q.identity * 100)}% identity, ${q.aligned} of ${q.transcriptLength} transcript residues covered`;
+}
+/** Which residues of the transcript a fragment holds, or undefined when it
+ * covers the whole translation. */
+export function describeCoveredRange(q) {
+    return q.aligned === 0 || q.aligned === q.transcriptLength
+        ? undefined
+        : `covers transcript residues ${q.transcriptStart}–${q.transcriptEnd}`;
+}
+//# sourceMappingURL=alignmentQuality.js.map

package/esm/alignmentQuality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignmentQuality.js","sourceRoot":"","sources":["../src/alignmentQuality.ts"],"names":[],"mappings":"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"}

package/esm/alphaFoldModels.d.ts

@@ -0,0 +1,29 @@
+import type { FetchOptions } from './fetchUtils.ts';
+export interface AlphaFoldModel {
+    /** UniProt accession, with an isoform suffix on an isoform model */
+    accession: string;
+    url: string;
+    confidenceUrl?: string;
+    sequence: string;
+}
+export declare function parseAlphaFoldModels(json: unknown): AlphaFoldModel[];
+/**
+ * Every model AlphaFold DB has for an accession: the canonical one and any
+ * isoform models, each with its file url and sequence. Asked rather than
+ * derived from the accession, because a derived `AF-<acc>-F1-model_v6` does
+ * not exist past the length cap (dystrophin has fourteen isoform models and no
+ * F1) and moves with every model version. An accession AlphaFold has never
+ * folded answers 400 or 404, which is no models rather than an error.
+ */
+export declare function fetchAlphaFoldModels(uniprotId: string, opts?: FetchOptions): Promise<AlphaFoldModel[]>;
+/**
+ * The model to open for a gene's transcripts: one folded from exactly a
+ * transcript's translation, canonical first, so the view maps it as an
+ * identity; else the canonical model; else the longest isoform model.
+ *
+ * Takes any record of sequences, since the structure loader knows one
+ * translation rather than a gene's isoforms.
+ */
+export declare function pickAlphaFoldModel(models: AlphaFoldModel[], isoformSequences: Record<string, {
+    seq: string;
+}> | undefined): AlphaFoldModel | undefined;

package/esm/alphaFoldModels.js

@@ -0,0 +1,55 @@
+import { httpError, rawfetch } from "./fetchUtils.js";
+import { stripStopCodon } from "./stripStopCodon.js";
+function isPredictionEntry(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function parseAlphaFoldModels(json) {
+    return (Array.isArray(json) ? json : []).flatMap(e => isPredictionEntry(e) &&
+        typeof e.uniprotAccession === 'string' &&
+        typeof e.cifUrl === 'string' &&
+        typeof e.sequence === 'string'
+        ? [
+            {
+                accession: e.uniprotAccession,
+                url: e.cifUrl,
+                confidenceUrl: typeof e.plddtDocUrl === 'string' ? e.plddtDocUrl : undefined,
+                sequence: e.sequence,
+            },
+        ]
+        : []);
+}
+/**
+ * Every model AlphaFold DB has for an accession: the canonical one and any
+ * isoform models, each with its file url and sequence. Asked rather than
+ * derived from the accession, because a derived `AF-<acc>-F1-model_v6` does
+ * not exist past the length cap (dystrophin has fourteen isoform models and no
+ * F1) and moves with every model version. An accession AlphaFold has never
+ * folded answers 400 or 404, which is no models rather than an error.
+ */
+export async function fetchAlphaFoldModels(uniprotId, opts) {
+    const url = `https://alphafold.ebi.ac.uk/api/prediction/${encodeURIComponent(uniprotId)}`;
+    const res = await rawfetch(url, opts);
+    if (res.status === 400 || res.status === 404) {
+        return [];
+    }
+    if (!res.ok) {
+        throw await httpError(res, url);
+    }
+    return parseAlphaFoldModels(await res.json());
+}
+/**
+ * The model to open for a gene's transcripts: one folded from exactly a
+ * transcript's translation, canonical first, so the view maps it as an
+ * identity; else the canonical model; else the longest isoform model.
+ *
+ * Takes any record of sequences, since the structure loader knows one
+ * translation rather than a gene's isoforms.
+ */
+export function pickAlphaFoldModel(models, isoformSequences) {
+    const translations = new Set(Object.values(isoformSequences ?? {}).map(v => stripStopCodon(v.seq)));
+    const canonicalFirst = [...models].sort((a, b) => Number(a.accession.includes('-')) - Number(b.accession.includes('-')));
+    return (canonicalFirst.find(m => translations.has(m.sequence)) ??
+        canonicalFirst.find(m => !m.accession.includes('-')) ??
+        [...models].sort((a, b) => b.sequence.length - a.sequence.length)[0]);
+}
+//# sourceMappingURL=alphaFoldModels.js.map

package/esm/alphaFoldModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alphaFoldModels.js","sourceRoot":"","sources":["../src/alphaFoldModels.ts"],"names":[],"mappings":"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"}

package/esm/caCoordsToPdb.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Convert Foldseek tCa coordinates and tSeq to PDB format
+ * tCa is a comma-separated string of x,y,z triplets
+ * tSeq is the amino acid sequence
+ */
+export declare function caCoordsToPdb(tCa: string, tSeq: string, chainId?: string, title?: string): string;
+/**
+ * Whether a Foldseek hit carries tCa data that can be converted to PDB. A type
+ * predicate rather than a boolean so a guarded caller can pass `hit.tCa`/
+ * `hit.tSeq` straight to caCoordsToPdb without re-asserting they're defined.
+ */
+export declare function hasValidCaCoords<T extends {
+    tCa?: string;
+    tSeq?: string;
+}>(hit: T): hit is T & {
+    tCa: string;
+    tSeq: string;
+};

package/esm/caCoordsToPdb.js

@@ -0,0 +1,91 @@
+// 3-letter amino acid codes
+const AA_3LETTER = {
+    A: 'ALA',
+    C: 'CYS',
+    D: 'ASP',
+    E: 'GLU',
+    F: 'PHE',
+    G: 'GLY',
+    H: 'HIS',
+    I: 'ILE',
+    K: 'LYS',
+    L: 'LEU',
+    M: 'MET',
+    N: 'ASN',
+    P: 'PRO',
+    Q: 'GLN',
+    R: 'ARG',
+    S: 'SER',
+    T: 'THR',
+    V: 'VAL',
+    W: 'TRP',
+    Y: 'TYR',
+    X: 'UNK', // Unknown
+};
+function padLeft(str, len) {
+    return str.padStart(len, ' ');
+}
+function padRight(str, len) {
+    return str.padEnd(len, ' ');
+}
+function formatCoord(val) {
+    return val.toFixed(3).padStart(8, ' ');
+}
+/**
+ * Convert Foldseek tCa coordinates and tSeq to PDB format
+ * tCa is a comma-separated string of x,y,z triplets
+ * tSeq is the amino acid sequence
+ */
+export function caCoordsToPdb(tCa, tSeq, chainId = 'A', title) {
+    const coords = tCa.split(',').map(Number);
+    const lines = [];
+    // Add header
+    if (title) {
+        lines.push(`TITLE     ${title}`);
+    }
+    lines.push('REMARK   1 Generated from Foldseek Cα coordinates');
+    let atomNum = 1;
+    let resNum = 1;
+    for (let i = 0; i < coords.length - 2; i += 3) {
+        const x = coords[i];
+        const y = coords[i + 1];
+        const z = coords[i + 2];
+        const aa = tSeq[resNum - 1] ?? 'X';
+        const resName = AA_3LETTER[aa] ?? 'UNK';
+        if (x === undefined || y === undefined || z === undefined) {
+            break;
+        }
+        // PDB ATOM record format
+        // Columns: 1-6 "ATOM  ", 7-11 serial, 13-16 name, 17 altLoc, 18-20 resName,
+        // 22 chainID, 23-26 resSeq, 27 iCode, 31-38 x, 39-46 y, 47-54 z,
+        // 55-60 occupancy, 61-66 tempFactor, 77-78 element
+        const line = 'ATOM  ' +
+            padLeft(String(atomNum), 5) +
+            '  CA  ' +
+            padRight(resName, 3) +
+            ' ' +
+            chainId +
+            padLeft(String(resNum), 4) +
+            '    ' +
+            formatCoord(x) +
+            formatCoord(y) +
+            formatCoord(z) +
+            '  1.00  0.00           C';
+        lines.push(line);
+        atomNum++;
+        resNum++;
+    }
+    lines.push('END');
+    return lines.join('\n');
+}
+/**
+ * Whether a Foldseek hit carries tCa data that can be converted to PDB. A type
+ * predicate rather than a boolean so a guarded caller can pass `hit.tCa`/
+ * `hit.tSeq` straight to caCoordsToPdb without re-asserting they're defined.
+ */
+export function hasValidCaCoords(hit) {
+    const { tCa, tSeq } = hit;
+    // Need at least 3 coordinates (x,y,z for one residue) and a sequence
+    return !!tCa && !!tSeq && tCa.split(',').length >= 3;
+}
+//# sourceMappingURL=caCoordsToPdb.js.map

package/esm/caCoordsToPdb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"caCoordsToPdb.js","sourceRoot":"","sources":["../src/caCoordsToPdb.ts"],"names":[],"mappings":"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"}

package/esm/chooseMappedEntity.d.ts

@@ -0,0 +1,55 @@
+import type { PairwiseAlignment } from './mappings.ts';
+import type { AlignmentAlgorithm } from './types.ts';
+/**
+ * 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 extends ScoredAlignment {
+    /** index into the candidate array of the entity that is the transcript's */
+    index: number;
+}
+export interface ScoredAlignment {
+    /** alignment of the transcript against the entity (stop codons stripped on
+     * both sides, matching the rest of the mapping pipeline) */
+    alignment: PairwiseAlignment;
+    /** identical aligned residues */
+    matches: number;
+    /** identical residues over the shorter sequence, the score that picks the
+     * entity; see `explainedFraction` */
+    explained: number;
+    /** the alignment's BLOSUM62 score, gap penalties included */
+    score: number;
+}
+/** A candidate entity: its sequence, and whether it is DNA/RNA, which is never
+ * the transcript's product however its letters happen to align. */
+export interface EntityCandidate {
+    seq: string;
+    nucleicAcid?: boolean;
+}
+export declare function explainedFraction(matches: number, transcriptLength: number, entityLength: number): number;
+/**
+ * Align one transcript to one entity, stop codons stripped on both sides. An
+ * exact match skips the DP entirely; an oversized pair returns undefined rather
+ * than locking up the tab. Used both to score every entity of a structure and
+ * to honour a user's explicit chain choice.
+ */
+export declare function alignTranscriptToEntity(transcript: string, entitySeq: string, algorithm: AlignmentAlgorithm): ScoredAlignment | undefined;
+/**
+ * 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 highest identity over the shorter
+ * sequence (see `explainedFraction`). Nucleic-acid entities are never
+ * candidates.
+ *
+ * Returns `undefined` only when there is nothing to map (no transcript or no
+ * protein entities) — never a silent fallback to the wrong entity.
+ */
+export declare function chooseMappedEntity(transcript: string, entities: readonly (string | EntityCandidate)[], algorithm: AlignmentAlgorithm): EntitySelection | undefined;

package/esm/chooseMappedEntity.js

@@ -0,0 +1,134 @@
+import { alignmentTooLarge, scoredAlignment, selfScore, } from "./pairwiseAlignment.js";
+import { stripStopCodon } from "./stripStopCodon.js";
+import { structureAlignedSeq, transcriptAlignedSeq } from "./mappings.js";
+/**
+ * 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;
+}
+/**
+ * Identical residues over the shorter of the two sequences: how much of
+ * whichever is smaller, transcript or entity, the other reproduces.
+ *
+ * A raw match count favours whatever chain is longest, and a complex's partner
+ * usually is: on 1H26 the 11-residue p53 peptide matches 11 while CDK2 accrues
+ * 58 scattered identities, and on 4ZZJ SIRT1 beats the 7-residue p53 peptide
+ * 63 to 6. The Smith-Waterman score is no better there (56 vs 58). Dividing
+ * by length asks the question the picker actually has, which chain *is* this
+ * gene's product: the peptide scores 0.69 and 0.50, the partners 0.19 and
+ * 0.17, and across a ribosome's 55 chains no decoy passes 0.29.
+ *
+ * Dividing by the *entity's* length alone penalised a fusion construct: a
+ * 60-residue target fused to a 370-residue carrier scored 0.14, and a random
+ * 10-mer decoy chain with 3 identities beat it a third of the time (measured
+ * 2026-09-11). Dividing by the shorter sequence leaves every chain shorter
+ * than the transcript scored as before and lets a chain that contains the
+ * whole transcript score near 1 however long its tag is. The pseudocount
+ * keeps a two-residue fragment that happens to match (a tRNA end in 7K00)
+ * from scoring 1.0.
+ */
+const EXPLAINED_PSEUDOCOUNT = 5;
+export function explainedFraction(matches, transcriptLength, entityLength) {
+    return (matches / (Math.min(transcriptLength, entityLength) + EXPLAINED_PSEUDOCOUNT));
+}
+function countMatches(pa) {
+    const a = transcriptAlignedSeq(pa);
+    const b = structureAlignedSeq(pa);
+    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;
+}
+/**
+ * Align one transcript to one entity, stop codons stripped on both sides. An
+ * exact match skips the DP entirely; an oversized pair returns undefined rather
+ * than locking up the tab. Used both to score every entity of a structure and
+ * to honour a user's explicit chain choice.
+ */
+export function alignTranscriptToEntity(transcript, entitySeq, algorithm) {
+    const t = stripStopCodon(transcript);
+    const s = stripStopCodon(entitySeq);
+    if (!t || !s || alignmentTooLarge(t.length, s.length)) {
+        return undefined;
+    }
+    if (s === t) {
+        return {
+            alignment: {
+                consensus: '|'.repeat(t.length),
+                alns: [
+                    { id: 'seq1', seq: t },
+                    { id: 'seq2', seq: s },
+                ],
+            },
+            matches: t.length,
+            explained: explainedFraction(t.length, t.length, s.length),
+            score: selfScore(t),
+        };
+    }
+    const { alignment, score } = scoredAlignment(t, s, algorithm);
+    const matches = countMatches(alignment);
+    return {
+        alignment,
+        matches,
+        explained: explainedFraction(matches, t.length, s.length),
+        score,
+    };
+}
+/**
+ * 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 highest identity over the shorter
+ * sequence (see `explainedFraction`). Nucleic-acid entities are never
+ * candidates.
+ *
+ * Returns `undefined` only when there is nothing to map (no transcript or no
+ * protein entities) — never a silent fallback to the wrong entity.
+ */
+export function chooseMappedEntity(transcript, entities, algorithm) {
+    const t = stripStopCodon(transcript);
+    if (!t) {
+        return undefined;
+    }
+    const candidates = entities.map(e => typeof e === 'string'
+        ? { seq: stripStopCodon(e) }
+        : { ...e, seq: stripStopCodon(e.seq) });
+    const exactIndex = candidates.findIndex(c => !c.nucleicAcid && c.seq.length > 0 && c.seq === t);
+    if (exactIndex !== -1) {
+        const exact = alignTranscriptToEntity(t, candidates[exactIndex].seq, algorithm);
+        return { index: exactIndex, ...exact };
+    }
+    // Each alignment is an O(len(t) * len(s)) main-thread DP, so a complex with
+    // many chains pays it once per chain. Homomers and repeated chains share a
+    // sequence, so align each distinct one once and reuse the result.
+    const bySeq = new Map();
+    let best;
+    for (let index = 0; index < candidates.length; index++) {
+        const { seq, nucleicAcid } = candidates[index];
+        if (nucleicAcid) {
+            continue;
+        }
+        if (!bySeq.has(seq)) {
+            bySeq.set(seq, alignTranscriptToEntity(t, seq, algorithm));
+        }
+        const scored = bySeq.get(seq);
+        if (scored && (!best || scored.explained > best.explained)) {
+            best = { index, ...scored };
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=chooseMappedEntity.js.map

package/esm/chooseMappedEntity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chooseMappedEntity.js","sourceRoot":"","sources":["../src/chooseMappedEntity.ts"],"names":[],"mappings":"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"}

package/esm/coordinates.d.ts

@@ -0,0 +1,66 @@
+import type { PairwiseAlignment } from './mappings.ts';
+/**
+ * Branded coordinate spaces. Every position in this plugin is a bare `number`,
+ * but the *meaning* differs: a structure residue index is not interchangeable
+ * with a transcript residue index or an alignment column, and mixing them is
+ * the root cause of the off-by-one class of bugs. Branding makes the compiler
+ * reject cross-space mixing; construct values with the helpers below at the
+ * boundaries where raw numbers enter (molstar picks, hover events, features).
+ *
+ * Conventions: all are 0-based. StructurePos indexes the ungapped structure
+ * sequence; TranscriptPos the ungapped transcript sequence; AlignmentCol a
+ * column of the pairwise alignment (gaps included).
+ */
+type Branded<B extends string> = number & {
+    readonly __brand: B;
+};
+export type StructurePos = Branded<'StructurePos'>;
+export type TranscriptPos = Branded<'TranscriptPos'>;
+export type AlignmentCol = Branded<'AlignmentCol'>;
+export declare const structurePos: (n: number) => StructurePos;
+export declare const transcriptPos: (n: number) => TranscriptPos;
+export declare const alignmentCol: (n: number) => AlignmentCol;
+export interface CoordinateMaps {
+    structureSeqToTranscriptSeqPosition: Record<number, number>;
+    transcriptSeqToStructureSeqPosition: Record<number, number>;
+    structurePositionToAlignmentMap: Record<number, number>;
+    transcriptPositionToAlignmentMap: Record<number, number>;
+    alignmentToStructurePosition: Record<number, number>;
+    alignmentToTranscriptPosition: Record<number, number>;
+}
+export interface CoordinateMapper {
+    structureToTranscript: (p: StructurePos) => TranscriptPos | undefined;
+    transcriptToStructure: (p: TranscriptPos) => StructurePos | undefined;
+    structureToAlignment: (p: StructurePos) => AlignmentCol | undefined;
+    alignmentToStructure: (c: AlignmentCol) => StructurePos | undefined;
+    transcriptToAlignment: (p: TranscriptPos) => AlignmentCol | undefined;
+    alignmentToTranscript: (c: AlignmentCol) => TranscriptPos | undefined;
+    /**
+     * Raw lookup tables, for consumers that iterate the whole map rather than
+     * convert a single position (e.g. per-residue track rendering, selection of
+     * all aligned residues). Plain numbers — prefer the typed methods above for
+     * point conversions.
+     */
+    readonly maps: CoordinateMaps;
+}
+/**
+ * Builds every coordinate conversion once from a pairwise alignment, replacing
+ * the scatter of per-getter map builds + repeated invertMap calls. The branded
+ * methods are the preferred API; `maps` stays unbranded for whole-map consumers.
+ */
+export declare function makeCoordinateMapper(pairwiseAlignment: PairwiseAlignment): CoordinateMapper;
+/**
+ * The 0-based half-open structure-position range covering an inclusive range
+ * of 1-based transcript residues, the numbering a UniProt feature or a domain
+ * map uses. Residues the structure lacks are skipped, so a range that runs
+ * past a fragment's end clamps to the last modeled residue; undefined when none
+ * of the range aligns to the structure.
+ */
+export declare function transcriptRangeToStructureRange(mapper: CoordinateMapper, range: {
+    start: number;
+    end: number;
+}): {
+    start: number;
+    end: number;
+} | undefined;
+export {};