p2s_mapper 1.4.0 → 2.1.0

package/src/mappings.ts

@@ -6,13 +6,11 @@ export interface AlignmentRow {
 }
 
 /**
- * A two-row alignment whose ROW ORDER IS A CONTRACT: row 0 is the transcript,
- * row 1 is the structure. Every producer honors it — runLocalAlignment is
- * always called as (transcript, structure), and the manual-import dialog tells
- * the user to paste them in that order — and every consumer depends on it, but
- * nothing in the type can enforce it, and swapping the two silently inverts
- * every coordinate map. Read the rows through the accessors below rather than
- * indexing, so a call site states which sequence it means.
+ * A two-row alignment: row 0 is the transcript and row 1 is the structure.
+ * alignSequences takes them in that order and every consumer depends on it,
+ * but the type cannot enforce it, and swapped rows invert every coordinate map
+ * without an error. Read the rows with the accessors below, so a call site
+ * names the sequence it means.
  */
 export interface PairwiseAlignment {
   consensus: string
@@ -28,11 +26,10 @@ export const alignmentLength = (pa: PairwiseAlignment) =>
   transcriptAlignedSeq(pa).length
 
 /**
- * Why a pairwise alignment can't be used, or undefined if it's usable. The two
- * rows must be the same non-zero length — every coordinate map walks them in
- * lockstep, so a ragged pair would map positions to nonsense. Callers that
- * accept alignments from outside (the manual-import dialog) check this and
- * report it; the internal map builders assert on it.
+ * Why a pairwise alignment can't be used, or undefined if it's usable. Both
+ * rows must have the same non-zero length, because every coordinate map walks
+ * them in step. Check an alignment from outside the package with this; the
+ * internal map builders throw on it.
  */
 export function pairwiseAlignmentProblem(pa: PairwiseAlignment) {
   const transcript = transcriptAlignedSeq(pa)

package/src/pairwiseAlignment.ts

@@ -68,7 +68,7 @@ function getScore(a: string, b: string) {
 const GAP_OPEN = -10
 const GAP_EXTEND = -0.5
 
-interface AlignmentResult {
+export interface AlignmentResult {
   alignedSeq1: string
   alignedSeq2: string
   score: number
@@ -393,14 +393,14 @@ export function selfScore(seq: string) {
 }
 
 export function scoredAlignment(
-  seq1: string,
-  seq2: string,
+  transcript: string,
+  structure: string,
   algorithm: AlignmentAlgorithm,
 ): { alignment: PairwiseAlignment; score: number } {
   const { alignedSeq1, alignedSeq2, score } =
     algorithm === 'smith_waterman'
-      ? smithWaterman(seq1, seq2)
-      : needlemanWunsch(seq1, seq2)
+      ? smithWaterman(transcript, structure)
+      : needlemanWunsch(transcript, structure)
 
   return {
     alignment: {
@@ -414,10 +414,13 @@ export function scoredAlignment(
   }
 }
 
-export function runLocalAlignment(
-  seq1: string,
-  seq2: string,
+export function alignSequences(
+  transcript: string,
+  structure: string,
   algorithm: AlignmentAlgorithm,
 ): PairwiseAlignment {
-  return scoredAlignment(seq1, seq2, algorithm).alignment
+  return scoredAlignment(transcript, structure, algorithm).alignment
 }
+
+/** @deprecated renamed to `alignSequences`, which runs either algorithm */
+export const runLocalAlignment = alignSequences

package/src/pdbEntry.ts

@@ -0,0 +1,240 @@
+// What RCSB knows about one PDB entry that a mapping needs, in one GraphQL
+// call: each polymer entity's sequence, its author chains, and its alignment
+// to UniProt. The alignment is what SIFTS publishes per chain, numbered the
+// same way (`entity_beg_seq_id` is label_seq_id, 1-based into the SEQRES),
+// and agreed with PDBe's SIFTS on every residue of 23 entries checked
+// (2026-10-11, 1TUP, 2RH1, 4HHB, 7K00 among them), in a tenth of the time.
+
+import {
+  HttpError,
+  isDefinitiveFailure,
+  jsonfetch,
+  timeout,
+} from './fetchUtils.ts'
+
+import type { FetchOptions } from './fetchUtils.ts'
+import type {
+  UniProtStructureMapping,
+  UniProtStructureSegment,
+} from './pdbUniProtMapping.ts'
+
+export const RCSB_DATA_GRAPHQL_URL = 'https://data.rcsb.org/graphql'
+
+export interface PdbEntry {
+  /** every UniProt accession the entry's entities align to */
+  mappings: UniProtStructureMapping[]
+  /** one sequence per protein entity, in entity order; nucleic acids left
+   * out, since A, C, G, T and U are amino-acid letters too */
+  proteinSequences: string[]
+}
+
+export function pdbEntryQuery(pdbId: string) {
+  return `{ entry(entry_id: "${pdbId.toUpperCase()}") { polymer_entities {
+  rcsb_id
+  entity_poly { type pdbx_seq_one_letter_code_can }
+  rcsb_polymer_entity_container_identifiers { auth_asym_ids }
+  rcsb_polymer_entity_align {
+    reference_database_name reference_database_accession
+    aligned_regions { entity_beg_seq_id ref_beg_seq_id length }
+  }
+  uniprots { rcsb_id rcsb_uniprot_entry_name }
+} } }`
+}
+
+const RETRY_DELAYS_MS = [1000, 3000]
+// bounded, since a view reports itself loading until the entry answers
+const TIMEOUT_MS = 20_000
+
+/**
+ * A GraphQL request. The server answers 200 whatever happened, so a failure
+ * is read from the body's `errors`, and counts as a 400: the server
+ * understood the query and declined it, so asking again gets the same answer.
+ */
+export async function graphqlFetch(
+  url: string,
+  query: string,
+  variables: Record<string, unknown> | undefined,
+  opts?: FetchOptions,
+) {
+  const json: unknown = await jsonfetch(url, {
+    ...opts,
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+  })
+  const errors = isRecord(json) ? json.errors : undefined
+  if (Array.isArray(errors) && errors.length > 0) {
+    const first: unknown = errors[0]
+    const message =
+      isRecord(first) && typeof first.message === 'string'
+        ? first.message
+        : 'unknown error'
+    throw new HttpError(`${new URL(url).host}: ${message}`, 400)
+  }
+  return isRecord(json) ? json.data : undefined
+}
+
+/**
+ * The entry, retried twice: one failed request would otherwise leave a fusion
+ * construct mapped onto its partner for the whole session. An id RCSB has no
+ * entry for is a 404, which is not retried, since that answer cannot change.
+ */
+export async function fetchPdbEntry(
+  pdbId: string,
+  opts?: FetchOptions,
+): Promise<PdbEntry> {
+  const { signal: caller, ...rest } = opts ?? {}
+  const signal = caller ?? undefined
+  const deadline = () =>
+    signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(TIMEOUT_MS)])
+      : AbortSignal.timeout(TIMEOUT_MS)
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const entry = parsePdbEntry(
+        await graphqlFetch(
+          RCSB_DATA_GRAPHQL_URL,
+          pdbEntryQuery(pdbId),
+          undefined,
+          { ...rest, signal: deadline() },
+        ),
+      )
+      if (!entry) {
+        throw new HttpError(`RCSB has no entry ${pdbId.toUpperCase()}`, 404)
+      }
+      return entry
+    } catch (e) {
+      const delay = RETRY_DELAYS_MS[attempt]
+      // the caller's own abort is not a failure to retry either
+      if (delay === undefined || isDefinitiveFailure(e) || signal?.aborted) {
+        throw e
+      }
+      await timeout(delay, signal)
+    }
+  }
+}
+
+/** The entry's UniProt alignment alone. */
+export async function fetchUniProtStructureMappings(
+  pdbId: string,
+  opts?: FetchOptions,
+) {
+  return (await fetchPdbEntry(pdbId, opts)).mappings
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function finiteNumber(value: unknown) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function strings(value: unknown) {
+  return Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === 'string')
+    : []
+}
+
+/**
+ * Parses the `data` of `pdbEntryQuery`. Undefined when RCSB has no such
+ * entry; an entry nothing aligns to UniProt (DNA alone, say) parses to no
+ * mappings. An unparseable alignment is skipped rather than failing the
+ * entry, so a chimera with one malformed region still maps its other chains.
+ */
+export function parsePdbEntry(data: unknown): PdbEntry | undefined {
+  const entry = isRecord(data) ? data.entry : undefined
+  if (!isRecord(entry)) {
+    return undefined
+  }
+  const entities = Array.isArray(entry.polymer_entities)
+    ? entry.polymer_entities.filter(isRecord)
+    : []
+  const byAccession = new Map<string, UniProtStructureMapping>()
+  const proteinSequences: string[] = []
+  for (const entity of entities.toSorted(
+    (a, b) => entityNumber(a.rcsb_id) - entityNumber(b.rcsb_id),
+  )) {
+    const entityId = String(entityNumber(entity.rcsb_id))
+    const poly = isRecord(entity.entity_poly) ? entity.entity_poly : undefined
+    const sequence = poly?.pdbx_seq_one_letter_code_can
+    if (
+      typeof poly?.type === 'string' &&
+      poly.type.startsWith('polypeptide') &&
+      typeof sequence === 'string' &&
+      sequence.length > 0
+    ) {
+      proteinSequences.push(sequence)
+    }
+    const ids = entity.rcsb_polymer_entity_container_identifiers
+    const chains = strings(isRecord(ids) ? ids.auth_asym_ids : undefined)
+    const names = new Map(
+      (Array.isArray(entity.uniprots) ? entity.uniprots : [])
+        .filter(isRecord)
+        .map(u => [u.rcsb_id, strings(u.rcsb_uniprot_entry_name)[0]] as const),
+    )
+    for (const align of Array.isArray(entity.rcsb_polymer_entity_align)
+      ? entity.rcsb_polymer_entity_align.filter(isRecord)
+      : []) {
+      const accession = align.reference_database_accession
+      if (
+        align.reference_database_name !== 'UniProt' ||
+        typeof accession !== 'string'
+      ) {
+        continue
+      }
+      const segments = (
+        Array.isArray(align.aligned_regions) ? align.aligned_regions : []
+      ).flatMap(region => parseSegments(region, entityId, chains))
+      if (segments.length === 0) {
+        continue
+      }
+      const mapping = byAccession.get(accession) ?? {
+        accession,
+        name: names.get(accession),
+        segments: [],
+      }
+      mapping.segments.push(...segments)
+      byAccession.set(accession, mapping)
+    }
+  }
+  return { mappings: [...byAccession.values()], proteinSequences }
+}
+
+function entityNumber(rcsbId: unknown) {
+  return typeof rcsbId === 'string' ? Number(rcsbId.split('_')[1]) : NaN
+}
+
+/** One segment per chain carrying the entity, so a PDB-format file, whose
+ * entities Mol* numbers per chain, still matches by chain. */
+function parseSegments(
+  region: unknown,
+  entityId: string,
+  chains: string[],
+): UniProtStructureSegment[] {
+  if (!isRecord(region)) {
+    return []
+  }
+  const entityBeg = finiteNumber(region.entity_beg_seq_id)
+  const refBeg = finiteNumber(region.ref_beg_seq_id)
+  const length = finiteNumber(region.length)
+  if (
+    entityBeg === undefined ||
+    refBeg === undefined ||
+    length === undefined ||
+    length < 1
+  ) {
+    return []
+  }
+  const segment = {
+    entityId,
+    unpStart: refBeg,
+    unpEnd: refBeg + length - 1,
+    // SEQRES/label_seq_id is 1-based, structure positions are 0-based
+    structStart: entityBeg - 1,
+    structEnd: entityBeg + length - 2,
+  }
+  return chains.length === 0
+    ? [segment]
+    : chains.map(chainId => ({ ...segment, chainId }))
+}

package/src/pdbUniProtMapping.ts

@@ -1,4 +1,4 @@
-// SIFTS UniProt <-> PDB residue mapping.
+// UniProt <-> PDB residue mapping.
 //
 // UniProt feature coordinates are positions in the UniProt canonical sequence.
 // For an AlphaFold model that *is* the structure's own sequence, so a feature at
@@ -6,33 +6,23 @@
 // entry it is not: the deposited construct is usually a fragment, often with
 // tags or engineered residues, so the two numberings differ by a per-segment
 // offset (1TUP's p53 chain starts at UniProt 94; 6VXX's spike SEQRES 33 is
-// UniProt 14). SIFTS is the authoritative alignment between the two, published
-// per entity/chain by PDBe.
+// UniProt 14). The entry's own UniProt alignment, which `fetchPdbEntry` reads
+// from RCSB, is the authority on that correspondence.
 //
-// `residue_number` in the PDBe response is the 1-based index into the entity's
-// SEQRES, i.e. label_seq_id, which is exactly this plugin's structure-sequence
-// position + 1 (see applyLociInteractivity.ts for the other place that boundary
-// is crossed).
-
-import { isDefinitiveFailure, jsonfetch, timeout } from './fetchUtils.ts'
-
-import type { FetchOptions } from './fetchUtils.ts'
+// Structure positions here index the entity's SEQRES from 0, i.e.
+// label_seq_id - 1, which is this package's structure-sequence position.
 
 /** One contiguous UniProt <-> structure correspondence for a single entity.
  * `unp*` are 1-based UniProt positions; `struct*` are 0-based inclusive
- * structure-sequence positions, this plugin's native coordinate. */
+ * structure-sequence positions, this package's native coordinate. */
 export interface UniProtStructureSegment {
   entityId: string
-  /** author chain id, when the response names it */
+  /** author chain id, when the source names it */
   chainId?: string
   unpStart: number
   unpEnd: number
   structStart: number
   structEnd: number
-  /** the endpoints' author residue numbers, the numbering a paper cites and a
-   * Mol* hover shows; absent when the response omits them */
-  authorStart?: number
-  authorEnd?: number
 }
 
 export interface UniProtStructureMapping {
@@ -49,140 +39,11 @@ export interface UniProtStructureMapping {
  */
 export type MapUniProtPosition = (uniprotPos: number) => number | undefined
 
-export function pdbeSiftsUrl(pdbId: string) {
-  return `https://www.ebi.ac.uk/pdbe/api/mappings/uniprot/${pdbId.toLowerCase()}`
-}
-
-const SIFTS_RETRY_DELAYS_MS = [1000, 3000]
-// bounded, since a view reports itself loading until SIFTS answers
-const SIFTS_TIMEOUT_MS = 20_000
-
-/**
- * SIFTS for an entry, retried twice: one failed request would otherwise leave a
- * fusion construct mapped onto its partner for the whole session.
- *
- * A 4xx is not retried. PDBe answers 404 for an entry it has no UniProt
- * mapping for at all — a DNA-only or obsolete entry — and that answer cannot
- * change, so the retries only postponed it: measured 2026-09-16, `1hhb` and
- * `1bna` each took three requests and ~4.8s to say so, which a caller shows as
- * four and a half seconds of "resolving" for a structure that will never
- * resolve.
- */
-export async function fetchUniProtStructureMappings(
-  pdbId: string,
-  opts?: FetchOptions,
-) {
-  const { signal: caller, ...rest } = opts ?? {}
-  const signal = caller ?? undefined
-  const deadline = () =>
-    signal
-      ? AbortSignal.any([signal, AbortSignal.timeout(SIFTS_TIMEOUT_MS)])
-      : AbortSignal.timeout(SIFTS_TIMEOUT_MS)
-  for (let attempt = 0; ; attempt++) {
-    try {
-      return parseUniProtStructureMappings(
-        await jsonfetch(pdbeSiftsUrl(pdbId), { ...rest, signal: deadline() }),
-      )
-    } catch (e) {
-      const delay = SIFTS_RETRY_DELAYS_MS[attempt]
-      // the caller's own abort is not a failure to retry either
-      if (delay === undefined || isDefinitiveFailure(e) || signal?.aborted) {
-        throw e
-      }
-      await timeout(delay, signal)
-    }
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function finiteNumber(value: unknown) {
-  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
-}
-
-function residueNumber(endpoint: unknown) {
-  return isRecord(endpoint) ? finiteNumber(endpoint.residue_number) : undefined
-}
-
-function authorResidueNumber(endpoint: unknown) {
-  return isRecord(endpoint)
-    ? finiteNumber(endpoint.author_residue_number)
-    : undefined
-}
-
-function parseSegment(mapping: unknown): UniProtStructureSegment | undefined {
-  if (!isRecord(mapping)) {
-    return undefined
-  }
-  const entityId = finiteNumber(mapping.entity_id)
-  const unpStart = finiteNumber(mapping.unp_start)
-  const unpEnd = finiteNumber(mapping.unp_end)
-  const structStart = residueNumber(mapping.start)
-  const structEnd = residueNumber(mapping.end)
-  const authorStart = authorResidueNumber(mapping.start)
-  const authorEnd = authorResidueNumber(mapping.end)
-  return entityId === undefined ||
-    unpStart === undefined ||
-    unpEnd === undefined ||
-    structStart === undefined ||
-    structEnd === undefined
-    ? undefined
-    : {
-        entityId: String(entityId),
-        ...(typeof mapping.chain_id === 'string'
-          ? { chainId: mapping.chain_id }
-          : {}),
-        unpStart,
-        unpEnd,
-        // SEQRES/label_seq_id is 1-based, structure positions are 0-based
-        structStart: structStart - 1,
-        structEnd: structEnd - 1,
-        ...(authorStart === undefined ? {} : { authorStart }),
-        ...(authorEnd === undefined ? {} : { authorEnd }),
-      }
-}
-
-/**
- * Parses a PDBe `mappings/uniprot/{pdbId}` response into one entry per UniProt
- * accession. Unparseable segments are skipped rather than failing the whole
- * response — a chimera with one malformed segment still maps its other chains.
- * The response is keyed by pdb id, so the single entry is taken whatever its key.
- */
-export function parseUniProtStructureMappings(
-  json: unknown,
-): UniProtStructureMapping[] {
-  const entry = isRecord(json) ? Object.values(json)[0] : undefined
-  const uniprot = isRecord(entry) ? entry.UniProt : undefined
-  if (!isRecord(uniprot)) {
-    return []
-  }
-  const result: UniProtStructureMapping[] = []
-  for (const [accession, value] of Object.entries(uniprot)) {
-    const mappings = isRecord(value) ? value.mappings : undefined
-    const segments = Array.isArray(mappings)
-      ? mappings.map(parseSegment).filter(s => s !== undefined)
-      : []
-    if (segments.length > 0) {
-      result.push({
-        accession,
-        name:
-          isRecord(value) && typeof value.name === 'string'
-            ? value.name
-            : undefined,
-        segments,
-      })
-    }
-  }
-  return result
-}
-
 function coveredResidues(segments: UniProtStructureSegment[]) {
   return segments.reduce((a, s) => a + (s.structEnd - s.structStart + 1), 0)
 }
 
-/** The entity a SIFTS segment is matched against: its mmCIF id and the author
+/** The entity a segment is matched against: its mmCIF id and the author
  * chains carrying it. */
 export interface SegmentEntity {
   entityId: string
@@ -190,10 +51,10 @@ export interface SegmentEntity {
 }
 
 /**
- * The segments of one accession that describe this entity. SIFTS numbers
- * entities as the mmCIF does, and a PDB-format file loaded through Mol* numbers
- * them per chain (1H26.pdb's chain C is entity 2, which in SIFTS is cyclin A),
- * so a segment naming its chain is matched by chain.
+ * The segments of one accession that describe this entity. The mapping
+ * numbers entities as the mmCIF does, and a PDB-format file loaded through
+ * Mol* numbers them per chain (1H26.pdb's chain C is entity 2, which in the
+ * mmCIF is cyclin A), so a segment naming its chain is matched by chain.
  */
 function segmentsForEntity(
   mapping: UniProtStructureMapping,
@@ -209,12 +70,11 @@ function segmentsForEntity(
 }
 
 /**
- * Picks the UniProt entry that describes a given entity, with its segments
- * narrowed to that entity. Only the entity the plugin has mapped to the
- * transcript is relevant — a heteromer maps each of its chains to a different
- * accession, and using the wrong one would silently annotate the wrong protein.
- * When several accessions cover the same entity (a chimeric construct) the one
- * contributing the most residues wins.
+ * Picks the UniProt entry for a given entity, with its segments narrowed to
+ * that entity. Pass the entity mapped to the transcript: a heteromer's chains
+ * align to different accessions, and the wrong one would annotate the wrong
+ * protein. When several accessions cover one entity (a chimeric construct), the
+ * one covering the most residues wins.
  */
 export function chooseUniProtMappingForEntity(
   mappings: UniProtStructureMapping[],
@@ -240,10 +100,11 @@ const OWN_PSEUDOCOUNT = 5
 const MIN_OWN_IDENTITY = 0.5
 
 /**
- * Mapped structure positions that SIFTS assigns to a protein other than the
- * transcript's, on a chain that fuses two. Local alignment bridges a fusion
- * boundary, and on every GPCR fusion construct checked it scattered receptor
- * residues onto the partner, 33 of them onto T4 lysozyme in 2RH1.
+ * Mapped structure positions the entry's UniProt alignment assigns to a
+ * protein other than the transcript's, on a chain that fuses two. Local
+ * alignment bridges a fusion boundary, and on every GPCR fusion construct
+ * checked it scattered receptor residues onto the partner, 33 of them onto T4
+ * lysozyme in 2RH1.
  *
  * `mapped` is each mapped structure position and whether its pair is
  * identical. The transcript's own accession is the one whose covered positions
@@ -252,7 +113,7 @@ const MIN_OWN_IDENTITY = 0.5
  * fused to CDK2 covers 11 positions against 224 chance hits on the kinase, and
  * counting unmapped the peptide. Unless that accession reaches half identity
  * the transcript is taken to be neither protein, and nothing is unmapped.
- * Residues SIFTS assigns to no accession, such as tags, stay mapped.
+ * Residues assigned to no accession, such as tags, stay mapped.
  */
 export function fusionPartnerPositions(
   mappings: UniProtStructureMapping[],
@@ -297,8 +158,8 @@ export function fusionPartnerPositions(
   return partners
 }
 
-// SIFTS lists one mapping per *chain*, so the several chains of a homodimer
-// repeat the same entity-level correspondence. They collapse to one segment.
+// The mapping lists one segment per *chain*, so the several chains of a
+// homodimer repeat the same entity-level correspondence. They collapse to one.
 function dedupeSegments(segments: UniProtStructureSegment[]) {
   const seen = new Set<string>()
   return segments.filter(s => {

package/src/structureFormat.ts

@@ -1,19 +1,14 @@
 /**
  * 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.
+ * A wrong choice fails either way. Parsing a PDB file as mmCIF throws
+ * ("Unexpected token. Expected data_, loop_, or data name"). Parsing an mmCIF
+ * as PDB succeeds and yields a model with zero polymer entities and thousands of
+ * misread atoms, so the structure loads with no sequence, no alignment and no
+ * genome mapping, and with no 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.
+ * The two names are the subset of molstar's `BuiltInTrajectoryFormat` that a
+ * structure file or URL can be, written out so nothing here imports molstar.
  */
 export type StructureFormat = 'pdb' | 'mmcif'
 
@@ -35,8 +30,7 @@ export function structureFileExtension(nameOrUrl: 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`).
+ * what AlphaFold and RCSB serve (`.cif`).
  */
 export function structureFormatFromName(nameOrUrl: string): StructureFormat {
   return PDB_EXTENSIONS.has(structureFileExtension(nameOrUrl)) ? 'pdb' : 'mmcif'
@@ -49,10 +43,9 @@ export function isBinaryStructureUrl(url: string) {
 }
 
 /**
- * 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.
+ * Format for structure text with no filename, such as inline data, a pasted
+ * file, or a PDB built by `caCoordsToPdb`. The content is more reliable than a
+ * name, and here it is the only signal.
  *
  * mmCIF is line-oriented and its first meaningful line is a `data_` block
  * header (comments and blank lines may precede it); PDB has none.