p2s_mapper 1.0.0

package/dist/stripStopCodon.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripStopCodon = stripStopCodon;
+exports.stripAllStopCodons = stripAllStopCodons;
+/**
+ * Drop the terminal stop codon(s) from a translated protein sequence.
+ *
+ * Only trailing `*` go: an interior stop (mis-annotated CDS, selenoprotein
+ * read-through) occupies a real codon position, and deleting it would shift
+ * every later residue out of step with g2p's codon-indexed transcript
+ * coordinates — offsetting every genome↔structure hover past that point.
+ */
+function stripStopCodon(seq) {
+    return seq.replace(/\*+$/, '');
+}
+/**
+ * Strip every stop codon, including interior ones. Only for sequences handed to
+ * an external similarity search (Foldseek, AlphaFold), where `*` is not a valid
+ * query character and no coordinate depends on the result's positions.
+ */
+function stripAllStopCodons(seq) {
+    return seq.replaceAll('*', '');
+}
+//# sourceMappingURL=stripStopCodon.js.map

package/dist/stripStopCodon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripStopCodon.js","sourceRoot":"","sources":["../src/stripStopCodon.ts"],"names":[],"mappings":";;AAQA,wCAEC;AAOD,gDAEC;AAnBD;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,GAAW;IACxC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;AAChC,CAAC;AAED;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;AAChC,CAAC"}

package/dist/structureFormat.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Which molstar trajectory parser a structure needs.
+ *
+ * Getting this wrong is not a graceful failure in either direction: parsing a
+ * PDB file as mmCIF throws ("Unexpected token. Expected data_, loop_, or data
+ * name"), and — worse — parsing an mmCIF as PDB *succeeds* and yields a model
+ * with zero polymer entities and thousands of misread atoms, so the view loads
+ * with no sequence, no alignment and no genome mapping, and nothing reports an
+ * error.
+ *
+ * So detection lives here and is applied as the default at every entry point,
+ * rather than at one of them.
+ *
+ * The two names are the subset of molstar's `BuiltInTrajectoryFormat` a
+ * structure loaded from a file or a url can be, spelled out rather than
+ * imported so nothing here depends on molstar.
+ */
+export type StructureFormat = 'pdb' | 'mmcif';
+/** Trailing extension of a filename or URL, lowercased, ignoring any query or
+ * fragment and any `.gz` wrapper (`…/pdb1tup.ent.gz` -> `ent`). */
+export declare function structureFileExtension(nameOrUrl: string): string;
+/**
+ * Format for a filename or URL. Unknown extensions fall back to mmCIF, which is
+ * what every URL this plugin generates itself serves (AlphaFold and RCSB both
+ * hand out `.cif`).
+ */
+export declare function structureFormatFromName(nameOrUrl: string): StructureFormat;
+/** Whether a URL points at a binary-encoded structure, which molstar must be
+ * told to download as bytes rather than text. */
+export declare function isBinaryStructureUrl(url: string): boolean;
+/**
+ * Format for structure text that arrived without a filename — an inline `data`
+ * snapshot, a pasted file, or the PDB the plugin synthesizes from Foldseek Cα
+ * coordinates. Sniffs the content, which is strictly more reliable than a name
+ * and is the only signal available here.
+ *
+ * mmCIF is line-oriented and its first meaningful line is a `data_` block
+ * header (comments and blank lines may precede it); PDB has none.
+ */
+export declare function structureFormatFromContent(data: string): StructureFormat;

package/dist/structureFormat.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.structureFileExtension = structureFileExtension;
+exports.structureFormatFromName = structureFormatFromName;
+exports.isBinaryStructureUrl = isBinaryStructureUrl;
+exports.structureFormatFromContent = structureFormatFromContent;
+// Only the PDB set is enumerated: mmCIF is the fallback (see below), so listing
+// its extensions would be a second source of truth that could disagree.
+const PDB_EXTENSIONS = new Set(['pdb', 'ent', 'pdb1', 'pdb2', 'pdb3']);
+/** Trailing extension of a filename or URL, lowercased, ignoring any query or
+ * fragment and any `.gz` wrapper (`…/pdb1tup.ent.gz` -> `ent`). */
+function structureFileExtension(nameOrUrl) {
+    const path = nameOrUrl.split(/[?#]/)[0] ?? '';
+    const name = path.split('/').pop() ?? '';
+    const parts = name.toLowerCase().split('.');
+    if (parts.at(-1) === 'gz') {
+        parts.pop();
+    }
+    return parts.length > 1 ? (parts.at(-1) ?? '') : '';
+}
+/**
+ * Format for a filename or URL. Unknown extensions fall back to mmCIF, which is
+ * what every URL this plugin generates itself serves (AlphaFold and RCSB both
+ * hand out `.cif`).
+ */
+function structureFormatFromName(nameOrUrl) {
+    return PDB_EXTENSIONS.has(structureFileExtension(nameOrUrl)) ? 'pdb' : 'mmcif';
+}
+/** Whether a URL points at a binary-encoded structure, which molstar must be
+ * told to download as bytes rather than text. */
+function isBinaryStructureUrl(url) {
+    return structureFileExtension(url) === 'bcif';
+}
+/**
+ * Format for structure text that arrived without a filename — an inline `data`
+ * snapshot, a pasted file, or the PDB the plugin synthesizes from Foldseek Cα
+ * coordinates. Sniffs the content, which is strictly more reliable than a name
+ * and is the only signal available here.
+ *
+ * mmCIF is line-oriented and its first meaningful line is a `data_` block
+ * header (comments and blank lines may precede it); PDB has none.
+ */
+function structureFormatFromContent(data) {
+    // a data_ header can only appear in the first few lines; don't scan a 30MB
+    // structure to find out
+    for (const line of data.slice(0, 4096).split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed !== '' && !trimmed.startsWith('#')) {
+            return trimmed.toLowerCase().startsWith('data_') ? 'mmcif' : 'pdb';
+        }
+    }
+    return 'pdb';
+}
+//# sourceMappingURL=structureFormat.js.map

package/dist/structureFormat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structureFormat.js","sourceRoot":"","sources":["../src/structureFormat.ts"],"names":[],"mappings":";;AAyBA,wDAQC;AAOD,0DAEC;AAID,oDAEC;AAWD,gEAUC;AAlDD,gFAAgF;AAChF,wEAAwE;AACxE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEtE;mEACmE;AACnE,SAAgB,sBAAsB,CAAC,SAAiB;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAA;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC3C,IAAI,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC1B,KAAK,CAAC,GAAG,EAAE,CAAA;IACb,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACrD,CAAC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,SAAiB;IACvD,OAAO,cAAc,CAAC,GAAG,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAA;AAChF,CAAC;AAED;iDACiD;AACjD,SAAgB,oBAAoB,CAAC,GAAW;IAC9C,OAAO,sBAAsB,CAAC,GAAG,CAAC,KAAK,MAAM,CAAA;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,0BAA0B,CAAC,IAAY;IACrD,2EAA2E;IAC3E,wBAAwB;IACxB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,OAAO,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/C,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;QACpE,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/structureSources.d.ts

@@ -0,0 +1,28 @@
+import type { FetchOptions } from './fetchUtils.ts';
+export interface ExperimentalStructure {
+    pdbId: string;
+    method: string;
+    /** Å; absent for NMR and some EM entries */
+    resolution?: number;
+    /** 1-based inclusive UniProt residues the entry covers */
+    start: number;
+    end: number;
+    /** fraction of the UniProt sequence the entry covers, 0..1 */
+    coverage: number;
+}
+export declare function beaconsSummaryUrl(uniprotId: string): string;
+/**
+ * PDBe entries only, best-covering first and sharpest within a tie.
+ *
+ * Predicted entries (AlphaFold, SWISS-MODEL, AlphaFill) are left out because a
+ * prediction comes from AlphaFold's own API, which answers per model. And
+ * 3D-Beacons files SASBDB's small-angle-scattering fits under "experimentally
+ * determined" too, with numeric ids and near-full coverage — dystrophin's best
+ * "structure" by coverage was SASBDB 436 — which are not entries a residue
+ * mapping exists for. Hence the `provider === 'PDBe'` gate rather than the
+ * category alone.
+ */
+export declare function parseExperimentalStructures(json: unknown): ExperimentalStructure[];
+/** Best-effort: an unreachable API reads as "no entries", which costs a
+ * structure suggestion and nothing else. */
+export declare function fetchExperimentalStructures(uniprotId: string, opts?: FetchOptions): Promise<ExperimentalStructure[]>;

package/dist/structureSources.js

@@ -0,0 +1,76 @@
+"use strict";
+// The experimental structures 3D-Beacons knows for a UniProt entry: every PDBe
+// entry mapped to the accession, with the UniProt range it covers and its
+// resolution, in one CORS-enabled call. That is what lets a page offer a
+// crystal structure beside a prediction without a PDB search of its own; take
+// the entry id from here and ask `fetchUniProtStructureMappings` for its
+// residue mapping.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beaconsSummaryUrl = beaconsSummaryUrl;
+exports.parseExperimentalStructures = parseExperimentalStructures;
+exports.fetchExperimentalStructures = fetchExperimentalStructures;
+const fetchUtils_ts_1 = require("./fetchUtils.js");
+function beaconsSummaryUrl(uniprotId) {
+    return `https://www.ebi.ac.uk/pdbe/pdbe-kb/3dbeacons/api/uniprot/summary/${encodeURIComponent(uniprotId)}.json?provider=pdbe`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * PDBe entries only, best-covering first and sharpest within a tie.
+ *
+ * Predicted entries (AlphaFold, SWISS-MODEL, AlphaFill) are left out because a
+ * prediction comes from AlphaFold's own API, which answers per model. And
+ * 3D-Beacons files SASBDB's small-angle-scattering fits under "experimentally
+ * determined" too, with numeric ids and near-full coverage — dystrophin's best
+ * "structure" by coverage was SASBDB 436 — which are not entries a residue
+ * mapping exists for. Hence the `provider === 'PDBe'` gate rather than the
+ * category alone.
+ */
+function parseExperimentalStructures(json) {
+    const structures = isRecord(json) ? json.structures : undefined;
+    if (!Array.isArray(structures)) {
+        return [];
+    }
+    return structures
+        .flatMap(entry => {
+        const s = isRecord(entry) ? entry.summary : undefined;
+        if (!isRecord(s)) {
+            return [];
+        }
+        const start = finiteNumber(s.uniprot_start);
+        const end = finiteNumber(s.uniprot_end);
+        const coverage = finiteNumber(s.coverage);
+        return typeof s.model_identifier === 'string' &&
+            s.provider === 'PDBe' &&
+            s.model_category === 'EXPERIMENTALLY DETERMINED' &&
+            start !== undefined &&
+            end !== undefined &&
+            coverage !== undefined
+            ? [
+                {
+                    pdbId: s.model_identifier.toLowerCase(),
+                    method: typeof s.experimental_method === 'string'
+                        ? s.experimental_method
+                        : 'experimental',
+                    resolution: finiteNumber(s.resolution),
+                    start,
+                    end,
+                    coverage,
+                },
+            ]
+            : [];
+    })
+        .sort((a, b) => b.coverage - a.coverage ||
+        (a.resolution ?? Infinity) - (b.resolution ?? Infinity));
+}
+/** Best-effort: an unreachable API reads as "no entries", which costs a
+ * structure suggestion and nothing else. */
+async function fetchExperimentalStructures(uniprotId, opts) {
+    const res = await (0, fetchUtils_ts_1.rawfetch)(beaconsSummaryUrl(uniprotId), opts).catch(() => undefined);
+    return res?.ok ? parseExperimentalStructures(await res.json()) : [];
+}
+//# sourceMappingURL=structureSources.js.map

package/dist/structureSources.js.map

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

package/dist/structureUrls.d.ts

@@ -0,0 +1,54 @@
+export declare function uniprotGffUrl(uniprotId: string): string;
+export declare function uniprotFastaUrl(uniprotId: string): string;
+export declare function uniprotEntryUrl(uniprotId: string): string;
+/**
+ * The guessed filename of an accession's canonical AlphaFold model. A guess:
+ * the F1 fragment does not exist past the length cap and the version moves, so
+ * this is the last resort when the prediction API cannot be reached. Ask
+ * `fetchAlphaFoldModels` for the real files.
+ */
+export declare function getAlphaFoldStructureUrl(uniprotId: string, version?: string): string;
+export declare function getPdbStructureUrl(pdbId: string): string;
+/**
+ * Resolve the `{ pdbId }` shorthand to a concrete structure URL, so a
+ * hand-authored snapshot or a short launch URL doesn't have to know RCSB's
+ * filename format. An explicit `url` (or inline `data`) always wins.
+ * Idempotent: re-resolving an already-resolved spec returns the same url.
+ *
+ * `uniprotId` deliberately resolves to no url here, and still outranks a
+ * `pdbId`. An accession's files are whatever AlphaFold DB currently holds — an
+ * isoform model, several fragments, a new model version — so the structure
+ * keeps the accession and the structure loader asks the prediction API which
+ * file to open.
+ *
+ * Shared by the Structure model's snapshot preprocessor and the
+ * LaunchView-ProteinView extension point, which would otherwise each carry
+ * their own copy of the same precedence rule.
+ */
+export declare function resolveStructureUrl({ url, data, uniprotId, pdbId, }: {
+    url?: string;
+    data?: string;
+    uniprotId?: string;
+    pdbId?: string;
+}): string | undefined;
+/**
+ * The PDB id of a structure URL from the PDB archive, lowercased, or undefined
+ * for any other URL. Accepts the filename forms those hosts serve, e.g.
+ * `1TUP.cif`, `pdb1tup.ent.gz`, `1tup_updated.cif`.
+ */
+export declare function getPdbIdFromUrl(url: string): string | undefined;
+/** The accession of an AlphaFold model id or url, with its isoform suffix:
+ * `AF-P16442-F1-model_v6` gives P16442, `AF-P04637-2-F1-model_v6` P04637-2. */
+export declare function getUniprotIdFromAlphaFoldTarget(target: string): string | undefined;
+export declare function getStructureUrlFromTarget(target: string, db: string): string | undefined;
+export declare function getConfidenceUrlFromTarget(target: string): string | undefined;
+/**
+ * What a structure is called in the UI: its PDB id, its AlphaFold accession,
+ * else the file's name. Shared by the view title, the alignment panel heading
+ * and the hover readout, so one structure reads the same everywhere.
+ */
+export declare function structureDisplayLabel({ url, data, uniprotId, }: {
+    url?: string;
+    data?: string;
+    uniprotId?: string;
+}): string;

package/dist/structureUrls.js

@@ -0,0 +1,147 @@
+"use strict";
+// Pure structure-URL builders and target parsers. Kept dependency-free so both
+// the launch flow and the ProteinView model (e.g. resolving a `uniprotId`/`pdbId`
+// shorthand at hydration) can import them without pulling in heavy launch code.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uniprotGffUrl = uniprotGffUrl;
+exports.uniprotFastaUrl = uniprotFastaUrl;
+exports.uniprotEntryUrl = uniprotEntryUrl;
+exports.getAlphaFoldStructureUrl = getAlphaFoldStructureUrl;
+exports.getPdbStructureUrl = getPdbStructureUrl;
+exports.resolveStructureUrl = resolveStructureUrl;
+exports.getPdbIdFromUrl = getPdbIdFromUrl;
+exports.getUniprotIdFromAlphaFoldTarget = getUniprotIdFromAlphaFoldTarget;
+exports.getStructureUrlFromTarget = getStructureUrlFromTarget;
+exports.getConfidenceUrlFromTarget = getConfidenceUrlFromTarget;
+exports.structureDisplayLabel = structureDisplayLabel;
+const ALPHAFOLD_VERSION = 'v6';
+// UniProt endpoints. rest.* is the machine API (the GFF the feature tracks and
+// the alignment's annotation rows both read, the FASTA the temporary protein
+// assembly is built from); www.*/entry is the human-facing entry page the UI
+// links to. Centralized so a path change is one edit rather than a grep.
+function uniprotGffUrl(uniprotId) {
+    return `https://rest.uniprot.org/uniprotkb/${uniprotId}.gff`;
+}
+function uniprotFastaUrl(uniprotId) {
+    return `https://rest.uniprot.org/uniprotkb/${uniprotId}.fasta`;
+}
+function uniprotEntryUrl(uniprotId) {
+    return `https://www.uniprot.org/uniprotkb/${uniprotId}/entry`;
+}
+/**
+ * The guessed filename of an accession's canonical AlphaFold model. A guess:
+ * the F1 fragment does not exist past the length cap and the version moves, so
+ * this is the last resort when the prediction API cannot be reached. Ask
+ * `fetchAlphaFoldModels` for the real files.
+ */
+function getAlphaFoldStructureUrl(uniprotId, version = ALPHAFOLD_VERSION) {
+    return `https://alphafold.ebi.ac.uk/files/AF-${uniprotId}-F1-model_${version}.cif`;
+}
+function getPdbStructureUrl(pdbId) {
+    return `https://files.rcsb.org/download/${pdbId}.cif`;
+}
+/**
+ * Resolve the `{ pdbId }` shorthand to a concrete structure URL, so a
+ * hand-authored snapshot or a short launch URL doesn't have to know RCSB's
+ * filename format. An explicit `url` (or inline `data`) always wins.
+ * Idempotent: re-resolving an already-resolved spec returns the same url.
+ *
+ * `uniprotId` deliberately resolves to no url here, and still outranks a
+ * `pdbId`. An accession's files are whatever AlphaFold DB currently holds — an
+ * isoform model, several fragments, a new model version — so the structure
+ * keeps the accession and the structure loader asks the prediction API which
+ * file to open.
+ *
+ * Shared by the Structure model's snapshot preprocessor and the
+ * LaunchView-ProteinView extension point, which would otherwise each carry
+ * their own copy of the same precedence rule.
+ */
+function resolveStructureUrl({ url, data, uniprotId, pdbId, }) {
+    if (url !== undefined || data !== undefined) {
+        return url;
+    }
+    return uniprotId !== undefined || pdbId === undefined
+        ? undefined
+        : getPdbStructureUrl(pdbId);
+}
+// Hosts that serve the PDB archive, so a 4-character filename there really is
+// that PDB entry. Restricted deliberately: a user-uploaded model happening to be
+// named 1abc.cif must not pick up 1ABC's UniProt annotations.
+const PDB_ARCHIVE_HOSTS = ['files.rcsb.org', 'www.ebi.ac.uk', 'ftp.ebi.ac.uk'];
+/**
+ * The PDB id of a structure URL from the PDB archive, lowercased, or undefined
+ * for any other URL. Accepts the filename forms those hosts serve, e.g.
+ * `1TUP.cif`, `pdb1tup.ent.gz`, `1tup_updated.cif`.
+ */
+function getPdbIdFromUrl(url) {
+    const { host, file } = (() => {
+        try {
+            const parsed = new URL(url);
+            return { host: parsed.hostname, file: parsed.pathname.split('/').pop() };
+        }
+        catch {
+            return { host: undefined, file: undefined };
+        }
+    })();
+    if (host === undefined || !PDB_ARCHIVE_HOSTS.includes(host)) {
+        return undefined;
+    }
+    const match = /^(?:pdb)?([1-9][a-z0-9]{3})(?:_updated)?\.(?:cif|bcif|pdb|ent)(?:\.gz)?$/i.exec(file ?? '');
+    return match?.[1]?.toLowerCase();
+}
+// Foldseek targets may contain a description after the ID separated by a
+// space, e.g. "AF-P16442-F1-model_v6 Histo-blood group ABO transferase".
+function extractTargetId(target) {
+    return target.split(' ')[0];
+}
+/** The accession of an AlphaFold model id or url, with its isoform suffix:
+ * `AF-P16442-F1-model_v6` gives P16442, `AF-P04637-2-F1-model_v6` P04637-2. */
+function getUniprotIdFromAlphaFoldTarget(target) {
+    const match = /AF-([A-Z0-9]+(?:-\d+)?)-F\d+/.exec(extractTargetId(target));
+    return match?.[1];
+}
+// Foldseek names a pdb100 hit by the assembly file and chain it searched,
+// `8f2h-assembly1.cif.gz_A`; the entry id is the first four characters.
+function getStructureUrlFromTarget(target, db) {
+    const targetId = extractTargetId(target);
+    if (targetId.startsWith('AF-')) {
+        return `https://alphafold.ebi.ac.uk/files/${targetId}.cif`;
+    }
+    const pdbId = db === 'pdb100'
+        ? /^([1-9][a-z0-9]{3})(?:[-_.]|$)/i.exec(targetId)?.[1]
+        : undefined;
+    return pdbId ? getPdbStructureUrl(pdbId) : undefined;
+}
+function getConfidenceUrlFromTarget(target) {
+    const targetId = extractTargetId(target);
+    if (targetId.startsWith('AF-')) {
+        const confidenceId = targetId.replace('-model_', '-confidence_');
+        return `https://alphafold.ebi.ac.uk/files/${confidenceId}.json`;
+    }
+    return undefined;
+}
+/**
+ * What a structure is called in the UI: its PDB id, its AlphaFold accession,
+ * else the file's name. Shared by the view title, the alignment panel heading
+ * and the hover readout, so one structure reads the same everywhere.
+ */
+function structureDisplayLabel({ url, data, uniprotId, }) {
+    if (url === undefined) {
+        return data !== undefined
+            ? 'Uploaded structure'
+            : uniprotId
+                ? `AlphaFold ${uniprotId}`
+                : '';
+    }
+    const pdbId = getPdbIdFromUrl(url);
+    if (pdbId) {
+        return pdbId.toUpperCase();
+    }
+    const urlAccession = getUniprotIdFromAlphaFoldTarget(url);
+    if (urlAccession) {
+        return `AlphaFold ${urlAccession}`;
+    }
+    const name = url.split('/').pop()?.split('?')[0];
+    return name === undefined || name === '' ? url : name;
+}
+//# sourceMappingURL=structureUrls.js.map

package/dist/structureUrls.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export type AlignmentAlgorithm = 'needleman_wunsch' | 'smith_waterman';
+export declare const ALIGNMENT_ALGORITHMS: {
+    readonly NEEDLEMAN_WUNSCH: "needleman_wunsch";
+    readonly SMITH_WATERMAN: "smith_waterman";
+};
+export declare const DEFAULT_ALIGNMENT_ALGORITHM: AlignmentAlgorithm;
+export declare const ALIGNMENT_ALGORITHM_VALUES: AlignmentAlgorithm[];
+/**
+ * Parses an untrusted algorithm name (a URL session-spec param) into the union.
+ * The only place a coercion is needed: the model property is an enumeration, so
+ * everything downstream of hydration is already typed.
+ */
+export declare function coerceAlignmentAlgorithm(value: string): AlignmentAlgorithm;
+export declare const ALIGNMENT_ALGORITHM_LABELS: Record<AlignmentAlgorithm, string>;

package/dist/types.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALIGNMENT_ALGORITHM_LABELS = exports.ALIGNMENT_ALGORITHM_VALUES = exports.DEFAULT_ALIGNMENT_ALGORITHM = exports.ALIGNMENT_ALGORITHMS = void 0;
+exports.coerceAlignmentAlgorithm = coerceAlignmentAlgorithm;
+exports.ALIGNMENT_ALGORITHMS = {
+    NEEDLEMAN_WUNSCH: 'needleman_wunsch',
+    SMITH_WATERMAN: 'smith_waterman',
+};
+exports.DEFAULT_ALIGNMENT_ALGORITHM = 'smith_waterman';
+exports.ALIGNMENT_ALGORITHM_VALUES = [
+    'needleman_wunsch',
+    'smith_waterman',
+];
+/**
+ * Parses an untrusted algorithm name (a URL session-spec param) into the union.
+ * The only place a coercion is needed: the model property is an enumeration, so
+ * everything downstream of hydration is already typed.
+ */
+function coerceAlignmentAlgorithm(value) {
+    return (exports.ALIGNMENT_ALGORITHM_VALUES.find(v => v === value) ??
+        exports.DEFAULT_ALIGNMENT_ALGORITHM);
+}
+exports.ALIGNMENT_ALGORITHM_LABELS = {
+    needleman_wunsch: 'Needleman-Wunsch',
+    smith_waterman: 'Smith-Waterman',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAmBA,4DAKC;AAtBY,QAAA,oBAAoB,GAAG;IAClC,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACxB,CAAA;AAEG,QAAA,2BAA2B,GAAuB,gBAAgB,CAAA;AAElE,QAAA,0BAA0B,GAAyB;IAC9D,kBAAkB;IAClB,gBAAgB;CACjB,CAAA;AAED;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,KAAa;IACpD,OAAO,CACL,kCAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC;QACjD,mCAA2B,CAC5B,CAAA;AACH,CAAC;AAEY,QAAA,0BAA0B,GAAuC;IAC5E,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;CACjC,CAAA"}

package/dist/uniProtSearch.d.ts

@@ -0,0 +1,32 @@
+import type { FetchOptions } from './fetchUtils.ts';
+export interface UniProtEntry {
+    accession: string;
+    id?: string;
+    geneName?: string;
+    organismName?: string;
+    proteinName?: string;
+    isReviewed: boolean;
+}
+/**
+ * `gene_exact` rather than `gene`, which also matches synonyms and returns
+ * paralogs. Without a taxon the query runs across every species, so a mouse
+ * assembly whose tracks carry no taxId lists mouse beside human instead of
+ * silently answering with the human entry.
+ *
+ * The symbol is quoted because a bare one containing `:` — an HLA allele, a
+ * name straight out of an annotation file — reads as another field to
+ * UniProt's parser, which answers 400.
+ */
+export declare function buildGeneNameQuery(geneName: string, organismId?: number): string;
+export interface UniProtSearchResult {
+    entries: UniProtEntry[];
+    attemptedCount: number;
+    failedCount: number;
+}
+export declare function searchUniProtEntries({ recognizedIds, geneId, geneName, organismId, }: {
+    recognizedIds?: string[];
+    geneId?: string;
+    geneName?: string;
+    /** NCBI taxon id; undefined searches every species */
+    organismId?: number;
+}, opts?: FetchOptions): Promise<UniProtSearchResult>;

package/dist/uniProtSearch.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildGeneNameQuery = buildGeneNameQuery;
+exports.searchUniProtEntries = searchUniProtEntries;
+const fetchUtils_ts_1 = require("./fetchUtils.js");
+const dbIds_ts_1 = require("./dbIds.js");
+const UNIPROT_FIELDS = 'accession,id,gene_names,organism_name,protein_name,reviewed';
+function mapApiResultToEntry(result) {
+    return {
+        accession: result.primaryAccession,
+        id: result.uniProtkbId,
+        geneName: result.genes?.[0]?.geneName?.value,
+        organismName: result.organism?.commonName ?? result.organism?.scientificName,
+        proteinName: result.proteinDescription?.recommendedName?.fullName?.value,
+        isReviewed: result.entryType === 'UniProtKB reviewed (Swiss-Prot)',
+    };
+}
+async function searchUniProt(query, size, opts) {
+    const url = `https://rest.uniprot.org/uniprotkb/search?query=${encodeURIComponent(query)}&fields=${UNIPROT_FIELDS}&size=${size}`;
+    const data = await (0, fetchUtils_ts_1.jsonfetch)(url, opts);
+    return data.results.map(mapApiResultToEntry);
+}
+/**
+ * `gene_exact` rather than `gene`, which also matches synonyms and returns
+ * paralogs. Without a taxon the query runs across every species, so a mouse
+ * assembly whose tracks carry no taxId lists mouse beside human instead of
+ * silently answering with the human entry.
+ *
+ * The symbol is quoted because a bare one containing `:` — an HLA allele, a
+ * name straight out of an annotation file — reads as another field to
+ * UniProt's parser, which answers 400.
+ */
+function buildGeneNameQuery(geneName, organismId) {
+    return [
+        `gene_exact:"${geneName.replaceAll('"', '\\"')}"`,
+        organismId ? `organism_id:${organismId}` : undefined,
+        'reviewed:true',
+    ]
+        .filter(s => s !== undefined)
+        .join(' AND ');
+}
+async function searchByXref(id, opts) {
+    const query = (0, dbIds_ts_1.buildUniProtXrefQuery)(id);
+    if (!query) {
+        return { entries: [], error: undefined };
+    }
+    try {
+        return { entries: await searchUniProt(query, 10, opts), error: undefined };
+    }
+    catch (e) {
+        console.error(`xref search failed for ${id}:`, e);
+        return { entries: [], error: e };
+    }
+}
+async function searchByGeneName(geneName, organismId, opts) {
+    try {
+        const entries = await searchUniProt(buildGeneNameQuery(geneName, organismId), organismId ? 5 : 10, opts);
+        return { entries, error: undefined };
+    }
+    catch (e) {
+        console.error(`gene name search failed for ${geneName}:`, e);
+        return { entries: [], error: e };
+    }
+}
+function deduplicateEntries(entries) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of entries) {
+        if (!seen.has(entry.accession)) {
+            seen.add(entry.accession);
+            result.push(entry);
+        }
+    }
+    return result;
+}
+async function searchUniProtEntries({ recognizedIds = [], geneId, geneName, organismId, }, opts) {
+    const idsToSearch = new Set(recognizedIds);
+    const strippedGeneId = geneId ? (0, dbIds_ts_1.stripTrailingVersion)(geneId) : undefined;
+    if (strippedGeneId && (0, dbIds_ts_1.isRecognizedDatabaseId)(strippedGeneId)) {
+        idsToSearch.add(strippedGeneId);
+    }
+    // The gene-name query runs alongside the xrefs rather than after them: it is
+    // only consulted when no xref found a reviewed entry, but waiting for that
+    // answer before starting it doubled the latency of the commonest case.
+    const [xrefResults, geneResult] = await Promise.all([
+        Promise.all([...idsToSearch].map(id => searchByXref(id, opts))),
+        geneName ? searchByGeneName(geneName, organismId, opts) : undefined,
+    ]);
+    let entries = deduplicateEntries(xrefResults.flatMap(r => r.entries));
+    // The gene-name answer is consulted only where no xref found a reviewed
+    // entry. Counting it otherwise reported "failed for 1 of 2 identifiers" over
+    // a gene that had in fact resolved, off a query nothing was waiting for.
+    const consultedGeneResult = geneResult && !entries.some(e => e.isReviewed) ? geneResult : undefined;
+    if (consultedGeneResult) {
+        entries = deduplicateEntries([...entries, ...consultedGeneResult.entries]);
+    }
+    const attemptedCount = idsToSearch.size + (consultedGeneResult ? 1 : 0);
+    const failedCount = xrefResults.filter(r => r.error !== undefined).length +
+        (consultedGeneResult?.error === undefined ? 0 : 1);
+    // Every attempt failing is a network problem, not an empty result. Throwing
+    // it stops consumers reporting "No UniProt ID found" over a dead connection.
+    if (entries.length === 0 &&
+        attemptedCount > 0 &&
+        attemptedCount === failedCount) {
+        throw (consultedGeneResult?.error ??
+            xrefResults.find(r => r.error !== undefined)?.error);
+    }
+    return {
+        entries: entries.toSorted((a, b) => Number(b.isReviewed) - Number(a.isReviewed)),
+        attemptedCount,
+        failedCount,
+    };
+}
+//# sourceMappingURL=uniProtSearch.js.map