@motionscript/molecule 0.0.0-stage → 0.1.0-alpha.0

package/dist/protein/parse.js

@@ -0,0 +1,387 @@
+/**
+ * Reads a coordinate file into a {@link ProteinStructure}.
+ *
+ * Two formats, because the Protein Data Bank serves two and which one an entry
+ * has is not the author's choice: the legacy **PDB** format numbers atoms in
+ * five columns and names chains in one, so an entry that outgrew either — a
+ * ribosome, a capsid — exists only as **mmCIF**. Refusing the second would mean
+ * refusing exactly the structures most worth looking at.
+ *
+ * Both are read the same way: pull out an atom list and whatever secondary
+ * structure the file annotates, then hand both to `deriveStructure`, which does
+ * the geometry. {@link parseStructure} sniffs which is which, so a caller
+ * holding a downloaded file never has to.
+ *
+ * **The first model only.** An NMR ensemble is twenty superposed conformations
+ * of the same molecule; drawing all of them at once produces a blur, and
+ * choosing between them is a question this node does not ask. The first is the
+ * conventional representative.
+ */
+import { elementOf, residueKind } from "./chemistry.js";
+import { deriveStructure, EMPTY_STRUCTURE, } from "./structure.js";
+/**
+ * Reads a coordinate file, detecting its format from the contents.
+ *
+ * `id` labels the result — an accession, or the asset's name. Anything that
+ * can't be read at all comes back as {@link EMPTY_STRUCTURE} rather than
+ * throwing: this runs against a file someone just uploaded or an accession
+ * someone is halfway through typing, and both of those are ordinary states
+ * rather than errors. An empty structure draws nothing, which is the honest
+ * picture of a file with no atoms in it.
+ */
+export function parseStructure(text, id = "") {
+    if (typeof text !== "string" || text.trim() === "") {
+        return { ...EMPTY_STRUCTURE, id };
+    }
+    return isMmcif(text) ? parseMmcif(text, id) : parsePdb(text, id);
+}
+/**
+ * Whether a file is mmCIF.
+ *
+ * The `data_` block header is mmCIF's first line and appears in no PDB file, so
+ * it decides on its own — but only over the first stretch, since `data_` is also
+ * an ordinary substring that could turn up in a PDB `REMARK`. The category
+ * prefix is the belt-and-braces check for a fragment handed over without its
+ * header.
+ */
+function isMmcif(text) {
+    const head = text.slice(0, 4096);
+    return /^\s*data_/.test(head) || head.includes("_atom_site.");
+}
+// --- PDB -------------------------------------------------------------------
+/**
+ * Reads the legacy PDB format, which is **fixed-column**: every field is at a
+ * known offset and the whitespace between them is padding rather than a
+ * separator. Splitting on spaces is the classic way to get this wrong — a
+ * residue number that runs into its insertion code, or a `-` sign that eats the
+ * gap between two coordinates, and the record silently comes apart.
+ *
+ * Columns, 1-based as the specification numbers them:
+ *
+ *     7–11  serial     13–16 name      18–20 resName   22 chainID
+ *     23–26 resSeq     31–38 x         39–46 y         47–54 z
+ *     77–78 element
+ */
+function parsePdb(text, id) {
+    const atoms = [];
+    const spans = [];
+    let title = "";
+    for (const line of text.split("\n")) {
+        const record = line.slice(0, 6).trim();
+        // Everything after the first `ENDMDL` is another conformation of what we
+        // already have. Stopping at it rather than filtering by model number also
+        // ends the read early on a large ensemble.
+        if (record === "ENDMDL")
+            break;
+        if (record === "ATOM" || record === "HETATM") {
+            const atom = parsePdbAtom(line, record === "HETATM");
+            if (atom)
+                atoms.push(atom);
+            continue;
+        }
+        if (record === "TITLE") {
+            // A long title is continued across several records, with the continuation
+            // number in columns 9–10 and the text always from column 11.
+            title = `${title} ${line.slice(10).trim()}`.trim();
+            continue;
+        }
+        // The two annotation records. Their first-residue fields sit at *different*
+        // offsets from each other — a genuine wart of the format rather than a
+        // mistake here — while their last-residue fields agree.
+        if (record === "HELIX") {
+            const span = pdbSpan(line, 19, 21, "helix");
+            if (span)
+                spans.push(span);
+            continue;
+        }
+        if (record === "SHEET") {
+            const span = pdbSpan(line, 21, 22, "sheet");
+            if (span)
+                spans.push(span);
+        }
+    }
+    return deriveStructure(id, title, atoms, spans);
+}
+/** One `ATOM`/`HETATM` record, or `null` when its coordinates don't read. */
+function parsePdbAtom(line, hetero) {
+    // Truncated before the coordinates. Worth checking outright: a short slice of
+    // a fixed-column record reads as the empty string, and `Number("")` is 0
+    // rather than `NaN` — so without this a mangled line becomes an atom sitting
+    // at the origin, which is far harder to notice than a missing one.
+    if (line.length < 54)
+        return null;
+    // An alternate location: the same atom modelled twice because the side chain
+    // is disordered. Keeping both would double the sticks through that residue,
+    // so take the first (blank or `A`), which is the convention.
+    const altLoc = line.slice(16, 17).trim();
+    if (altLoc !== "" && altLoc !== "A")
+        return null;
+    const x = Number(line.slice(30, 38));
+    const y = Number(line.slice(38, 46));
+    const z = Number(line.slice(46, 54));
+    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+        return null;
+    }
+    const name = line.slice(12, 16).trim();
+    const residue = line.slice(17, 20).trim();
+    const kind = residueKind(residue);
+    return {
+        serial: Number(line.slice(6, 11)) || 0,
+        name,
+        element: elementOf(line.slice(76, 78), name, kind),
+        residue,
+        residueSeq: Number(line.slice(22, 26)) || 0,
+        // A file with a single unnamed chain leaves the column blank; calling that
+        // `A` keeps "group by chain" from producing one group named nothing.
+        chain: line.slice(21, 22).trim() || "A",
+        x,
+        y,
+        z,
+        hetero,
+        kind,
+    };
+}
+/** Where the last residue's number sits on both `HELIX` and `SHEET` — columns 34–37. */
+const PDB_SPAN_END_AT = 33;
+/**
+ * One `HELIX`/`SHEET` record as a residue span.
+ *
+ * The first-residue offsets differ between the two records, so they are passed
+ * in rather than hard-coded: a helix names its chain in column 20 and its first
+ * residue in 22–25, a sheet names its chain in 22 and its first residue in
+ * 23–26. Their *last* residue is in the same place in both, which is the one
+ * thing they agree on.
+ */
+function pdbSpan(line, chainAt, startAt, kind) {
+    const chain = line.slice(chainAt, chainAt + 1).trim() || "A";
+    // Read as text first: a blank fixed-column field slices to `""`, and
+    // `Number("")` is 0, so a `Number.isFinite` check alone would accept a record
+    // that states nothing as a span over residue 0.
+    const startText = line.slice(startAt, startAt + 4).trim();
+    const endText = line.slice(PDB_SPAN_END_AT, PDB_SPAN_END_AT + 4).trim();
+    if (startText === "" || endText === "")
+        return null;
+    const start = Number(startText);
+    const end = Number(endText);
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return null;
+    return { chain, start, end, kind };
+}
+// --- mmCIF -----------------------------------------------------------------
+/**
+ * Reads mmCIF, which is a tagged format rather than a positional one: values are
+ * whitespace-separated and their meaning comes from the column headers declared
+ * above them, so the reader has to learn the layout before it can read a row.
+ *
+ * Only three categories are consulted — the atoms, and the two that annotate
+ * secondary structure. mmCIF carries dozens more, and every one this doesn't
+ * read is one this can't be broken by.
+ */
+function parseMmcif(text, id) {
+    const lines = text.split("\n");
+    const atoms = mmcifAtoms(lines);
+    const spans = [
+        ...mmcifSpans(lines, "_struct_conf", "helix"),
+        ...mmcifSpans(lines, "_struct_sheet_range", "sheet"),
+    ];
+    return deriveStructure(id, mmcifTitle(lines), atoms, spans);
+}
+/** The atoms of the first model in an `_atom_site` loop. */
+function mmcifAtoms(lines) {
+    const atoms = [];
+    let model = null;
+    for (const row of mmcifRows(lines, "_atom_site")) {
+        // `auth_*` is the numbering the literature uses and the one a PDB file would
+        // have carried; `label_*` is the internal, re-derived scheme. Preferring
+        // auth means a residue number quoted in a paper matches what is drawn, and
+        // falling back keeps a file that omits it readable.
+        const chain = row("auth_asym_id") || row("label_asym_id") || "A";
+        const residue = row("auth_comp_id") || row("label_comp_id");
+        const name = row("auth_atom_id") || row("label_atom_id");
+        const thisModel = row("pdbx_PDB_model_num");
+        if (model === null)
+            model = thisModel;
+        else if (thisModel !== model)
+            break;
+        const altLoc = row("label_alt_id");
+        if (altLoc !== "" && altLoc !== "." && altLoc !== "?" && altLoc !== "A") {
+            continue;
+        }
+        const x = Number(row("Cartn_x"));
+        const y = Number(row("Cartn_y"));
+        const z = Number(row("Cartn_z"));
+        if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+            continue;
+        }
+        const kind = residueKind(residue);
+        atoms.push({
+            serial: Number(row("id")) || 0,
+            name,
+            element: elementOf(row("type_symbol"), name, kind),
+            residue,
+            residueSeq: Number(row("auth_seq_id") || row("label_seq_id")) || 0,
+            chain,
+            x,
+            y,
+            z,
+            hetero: row("group_PDB") === "HETATM",
+            kind,
+        });
+    }
+    return atoms;
+}
+/** The residue spans of one annotation category. */
+function mmcifSpans(lines, category, kind) {
+    const spans = [];
+    for (const row of mmcifRows(lines, category)) {
+        // `_struct_conf` covers turns and bends as well as helices, all under one
+        // category and told apart by this tag. A sheet range has no such tag, so an
+        // absent one passes.
+        const type = row("conf_type_id");
+        if (type !== "" && !type.startsWith("HELX"))
+            continue;
+        const chain = row("beg_auth_asym_id") || row("beg_label_asym_id") || "A";
+        const start = Number(row("beg_auth_seq_id") || row("beg_label_seq_id"));
+        const end = Number(row("end_auth_seq_id") || row("end_label_seq_id"));
+        if (!Number.isFinite(start) || !Number.isFinite(end))
+            continue;
+        spans.push({ chain, start, end, kind });
+    }
+    return spans;
+}
+/** The entry's title, from the `_struct.title` item. */
+function mmcifTitle(lines) {
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.startsWith("_struct.title"))
+            continue;
+        const inline = line.slice("_struct.title".length).trim();
+        // A value too long for the line is carried on the next one, or in a
+        // semicolon-delimited block below it; the inline form covers the rest.
+        if (inline !== "")
+            return unquote(inline);
+        const next = lines[i + 1]?.trim() ?? "";
+        return unquote(next.startsWith(";") ? next.slice(1) : next);
+    }
+    return "";
+}
+/**
+ * Walks the rows of one mmCIF category, yielding a field reader for each.
+ *
+ * The reader is a closure over the current row rather than an object, so
+ * nothing allocates a record per atom — this runs over hundreds of thousands of
+ * rows on a large entry, and the caller only ever wants a handful of the fields.
+ *
+ * Handles both forms a category takes: a `loop_` with a header block and many
+ * rows, and the flat `_category.field value` form mmCIF uses when there is
+ * exactly one row.
+ */
+function* mmcifRows(lines, category) {
+    const prefix = `${category}.`;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // The flat, single-row form: consecutive `_category.field value` lines.
+        if (line.startsWith(prefix)) {
+            const single = new Map();
+            while (i < lines.length) {
+                const item = lines[i].trim();
+                if (!item.startsWith(prefix))
+                    break;
+                const gap = item.search(/\s/);
+                if (gap === -1) {
+                    // A field whose value is on the following line.
+                    single.set(item.slice(prefix.length), unquote(lines[++i]?.trim() ?? ""));
+                }
+                else {
+                    single.set(item.slice(prefix.length, gap), unquote(item.slice(gap).trim()));
+                }
+                i++;
+            }
+            yield (field) => single.get(field) ?? "";
+            return;
+        }
+        if (line !== "loop_")
+            continue;
+        // The header block: every `_category.field` line, in the order the values
+        // will arrive in.
+        const columns = new Map();
+        let cursor = i + 1;
+        while (cursor < lines.length) {
+            const header = lines[cursor].trim();
+            if (!header.startsWith("_"))
+                break;
+            if (header.startsWith(prefix)) {
+                columns.set(header.slice(prefix.length), columns.size);
+            }
+            cursor++;
+        }
+        // A `loop_` for some other category. Its rows carry no leading underscore
+        // and aren't `loop_`, so the outer scan walks past them harmlessly.
+        if (columns.size === 0)
+            continue;
+        for (; cursor < lines.length; cursor++) {
+            const row = lines[cursor];
+            const trimmed = row.trim();
+            // A loop ends at the next block, the next loop, or a blank line.
+            if (trimmed === "" || trimmed === "#" || trimmed.startsWith("_"))
+                break;
+            if (trimmed === "loop_" || trimmed.startsWith("data_"))
+                break;
+            const values = splitCifRow(trimmed);
+            yield (field) => {
+                const index = columns.get(field);
+                if (index === undefined)
+                    return "";
+                const value = values[index] ?? "";
+                return value === "." || value === "?" ? "" : value;
+            };
+        }
+        return;
+    }
+}
+/**
+ * Splits one mmCIF row into values, respecting quotes.
+ *
+ * Quoting is not decoration here: a chain identifier can be `'A'`, and a residue
+ * name can contain a space that a plain `split` would turn into two columns and
+ * shift every field after it by one.
+ */
+function splitCifRow(row) {
+    const values = [];
+    let i = 0;
+    while (i < row.length) {
+        const char = row[i];
+        if (char === " " || char === "\t") {
+            i++;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            const end = row.indexOf(char, i + 1);
+            if (end === -1) {
+                values.push(row.slice(i + 1));
+                break;
+            }
+            values.push(row.slice(i + 1, end));
+            i = end + 1;
+            continue;
+        }
+        let end = i;
+        while (end < row.length && row[end] !== " " && row[end] !== "\t")
+            end++;
+        values.push(row.slice(i, end));
+        i = end;
+    }
+    return values;
+}
+/** Strips the quotes mmCIF wraps a value in, and the null placeholders. */
+function unquote(value) {
+    const text = value.trim();
+    if (text === "." || text === "?")
+        return "";
+    const first = text[0];
+    if ((first === "'" || first === '"') && text.endsWith(first) && text.length > 1) {
+        return text.slice(1, -1);
+    }
+    return text;
+}
+//# sourceMappingURL=parse.js.map

package/dist/protein/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/protein/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EACL,eAAe,EACf,eAAe,GAIhB,MAAM,aAAa,CAAA;AAEpB;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,EAAE,GAAG,EAAE;IAClD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,OAAO,EAAE,GAAG,eAAe,EAAE,EAAE,EAAE,CAAA;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IAChC,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAA;AAC/D,CAAC;AAED,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,EAAU;IACxC,MAAM,KAAK,GAAkB,EAAE,CAAA;IAC/B,MAAM,KAAK,GAAoB,EAAE,CAAA;IACjC,IAAI,KAAK,GAAG,EAAE,CAAA;IAEd,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAEtC,yEAAyE;QACzE,0EAA0E;QAC1E,2CAA2C;QAC3C,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAK;QAE9B,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAA;YACpD,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC1B,SAAQ;QACV,CAAC;QAED,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,0EAA0E;YAC1E,6DAA6D;YAC7D,KAAK,GAAG,GAAG,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAA;YAClD,SAAQ;QACV,CAAC;QAED,4EAA4E;QAC5E,uEAAuE;QACvE,wDAAwD;QACxD,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;YAC3C,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC1B,SAAQ;QACV,CAAC;QACD,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;YAC3C,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,eAAe,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;AACjD,CAAC;AAED,6EAA6E;AAC7E,SAAS,YAAY,CAAC,IAAY,EAAE,MAAe;IACjD,8EAA8E;IAC9E,yEAAyE;IACzE,6EAA6E;IAC7E,mEAAmE;IACnE,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE;QAAE,OAAO,IAAI,CAAA;IAEjC,6EAA6E;IAC7E,4EAA4E;IAC5E,6DAA6D;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACxC,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAEhD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;IACpC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;IACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACzC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;IAEjC,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC;QACtC,IAAI;QACJ,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;QAClD,OAAO;QACP,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC;QAC3C,2EAA2E;QAC3E,qEAAqE;QACrE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG;QACvC,CAAC;QACD,CAAC;QACD,CAAC;QACD,MAAM;QACN,IAAI;KACL,CAAA;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,eAAe,GAAG,EAAE,CAAA;AAE1B;;;;;;;;GAQG;AACH,SAAS,OAAO,CACd,IAAY,EACZ,OAAe,EACf,OAAe,EACf,IAA2B;IAE3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,CAAA;IAC5D,qEAAqE;IACrE,8EAA8E;IAC9E,gDAAgD;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACzD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,eAAe,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACvE,IAAI,SAAS,KAAK,EAAE,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAEnD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;IAC/B,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;IAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC;AAED,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,IAAY,EAAE,EAAU;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAC/B,MAAM,KAAK,GAAG;QACZ,GAAG,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC;QAC7C,GAAG,UAAU,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,CAAC;KACrD,CAAA;IACD,OAAO,eAAe,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;AAC7D,CAAC;AAED,4DAA4D;AAC5D,SAAS,UAAU,CAAC,KAAe;IACjC,MAAM,KAAK,GAAkB,EAAE,CAAA;IAC/B,IAAI,KAAK,GAAkB,IAAI,CAAA;IAE/B,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC;QACjD,6EAA6E;QAC7E,yEAAyE;QACzE,2EAA2E;QAC3E,oDAAoD;QACpD,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,IAAI,GAAG,CAAA;QAChE,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,CAAA;QAC3D,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC,CAAA;QAExD,MAAM,SAAS,GAAG,GAAG,CAAC,oBAAoB,CAAC,CAAA;QAC3C,IAAI,KAAK,KAAK,IAAI;YAAE,KAAK,GAAG,SAAS,CAAA;aAChC,IAAI,SAAS,KAAK,KAAK;YAAE,MAAK;QAEnC,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC,CAAA;QAClC,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACxE,SAAQ;QACV,CAAC;QAED,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAA;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAA;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAA;QAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,SAAQ;QACV,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;QACjC,KAAK,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;YAC9B,IAAI;YACJ,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;YAClD,OAAO;YACP,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC;YAClE,KAAK;YACL,CAAC;YACD,CAAC;YACD,CAAC;YACD,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ;YACrC,IAAI;SACL,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,oDAAoD;AACpD,SAAS,UAAU,CACjB,KAAe,EACf,QAAgB,EAChB,IAA2B;IAE3B,MAAM,KAAK,GAAoB,EAAE,CAAA;IAEjC,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC7C,0EAA0E;QAC1E,4EAA4E;QAC5E,qBAAqB;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,CAAC,CAAA;QAChC,IAAI,IAAI,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAQ;QAErD,MAAM,KAAK,GAAG,GAAG,CAAC,kBAAkB,CAAC,IAAI,GAAG,CAAC,mBAAmB,CAAC,IAAI,GAAG,CAAA;QACxE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAA;QACvE,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAA;QACrE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAA;IACzC,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,wDAAwD;AACxD,SAAS,UAAU,CAAC,KAAe;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAA;QACtB,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC;YAAE,SAAQ;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;QACxD,oEAAoE;QACpE,uEAAuE;QACvE,IAAI,MAAM,KAAK,EAAE;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAA;QACzC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;QACvC,OAAO,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAC7D,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED;;;;;;;;;;GAUG;AACH,QAAQ,CAAC,CAAC,SAAS,CACjB,KAAe,EACf,QAAgB;IAEhB,MAAM,MAAM,GAAG,GAAG,QAAQ,GAAG,CAAA;IAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAA;QAE7B,wEAAwE;QACxE,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAA;YACxC,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBACxB,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAA;gBAC7B,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,MAAK;gBACnC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;gBAC7B,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;oBACf,gDAAgD;oBAChD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;gBAC1E,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,GAAG,CACR,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAChC,CAAA;gBACH,CAAC;gBACD,CAAC,EAAE,CAAA;YACL,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;YACxC,OAAM;QACR,CAAC;QAED,IAAI,IAAI,KAAK,OAAO;YAAE,SAAQ;QAE9B,0EAA0E;QAC1E,kBAAkB;QAClB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA;QACzC,IAAI,MAAM,GAAG,CAAC,GAAG,CAAC,CAAA;QAClB,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAE,CAAC,IAAI,EAAE,CAAA;YACpC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,MAAK;YAClC,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;YACxD,CAAC;YACD,MAAM,EAAE,CAAA;QACV,CAAC;QACD,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,SAAQ;QAEhC,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAE,CAAA;YAC1B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;YAC1B,iEAAiE;YACjE,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,MAAK;YACvE,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;gBAAE,MAAK;YAE7D,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;YACnC,MAAM,CAAC,KAAK,EAAE,EAAE;gBACd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;gBAChC,IAAI,KAAK,KAAK,SAAS;oBAAE,OAAO,EAAE,CAAA;gBAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;gBACjC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;YACpD,CAAC,CAAA;QACH,CAAC;QACD,OAAM;IACR,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,IAAI,CAAC,GAAG,CAAC,CAAA;IAET,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,CAAA;QACpB,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClC,CAAC,EAAE,CAAA;YACH,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAA;YACpC,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;gBAC7B,MAAK;YACP,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;YAClC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAA;YACX,SAAQ;QACV,CAAC;QACD,IAAI,GAAG,GAAG,CAAC,CAAA;QACX,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI;YAAE,GAAG,EAAE,CAAA;QACvE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;QAC9B,CAAC,GAAG,GAAG,CAAA;IACT,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,2EAA2E;AAC3E,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IACzB,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,EAAE,CAAA;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACrB,IAAI,CAAC,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["/**\n * Reads a coordinate file into a {@link ProteinStructure}.\n *\n * Two formats, because the Protein Data Bank serves two and which one an entry\n * has is not the author's choice: the legacy **PDB** format numbers atoms in\n * five columns and names chains in one, so an entry that outgrew either — a\n * ribosome, a capsid — exists only as **mmCIF**. Refusing the second would mean\n * refusing exactly the structures most worth looking at.\n *\n * Both are read the same way: pull out an atom list and whatever secondary\n * structure the file annotates, then hand both to `deriveStructure`, which does\n * the geometry. {@link parseStructure} sniffs which is which, so a caller\n * holding a downloaded file never has to.\n *\n * **The first model only.** An NMR ensemble is twenty superposed conformations\n * of the same molecule; drawing all of them at once produces a blur, and\n * choosing between them is a question this node does not ask. The first is the\n * conventional representative.\n */\n\nimport { elementOf, residueKind } from \"./chemistry\"\nimport {\n  deriveStructure,\n  EMPTY_STRUCTURE,\n  type ProteinAtom,\n  type ProteinStructure,\n  type SecondarySpan,\n} from \"./structure\"\n\n/**\n * Reads a coordinate file, detecting its format from the contents.\n *\n * `id` labels the result — an accession, or the asset's name. Anything that\n * can't be read at all comes back as {@link EMPTY_STRUCTURE} rather than\n * throwing: this runs against a file someone just uploaded or an accession\n * someone is halfway through typing, and both of those are ordinary states\n * rather than errors. An empty structure draws nothing, which is the honest\n * picture of a file with no atoms in it.\n */\nexport function parseStructure(text: string, id = \"\"): ProteinStructure {\n  if (typeof text !== \"string\" || text.trim() === \"\") {\n    return { ...EMPTY_STRUCTURE, id }\n  }\n  return isMmcif(text) ? parseMmcif(text, id) : parsePdb(text, id)\n}\n\n/**\n * Whether a file is mmCIF.\n *\n * The `data_` block header is mmCIF's first line and appears in no PDB file, so\n * it decides on its own — but only over the first stretch, since `data_` is also\n * an ordinary substring that could turn up in a PDB `REMARK`. The category\n * prefix is the belt-and-braces check for a fragment handed over without its\n * header.\n */\nfunction isMmcif(text: string): boolean {\n  const head = text.slice(0, 4096)\n  return /^\\s*data_/.test(head) || head.includes(\"_atom_site.\")\n}\n\n// --- PDB -------------------------------------------------------------------\n\n/**\n * Reads the legacy PDB format, which is **fixed-column**: every field is at a\n * known offset and the whitespace between them is padding rather than a\n * separator. Splitting on spaces is the classic way to get this wrong — a\n * residue number that runs into its insertion code, or a `-` sign that eats the\n * gap between two coordinates, and the record silently comes apart.\n *\n * Columns, 1-based as the specification numbers them:\n *\n *     7–11  serial     13–16 name      18–20 resName   22 chainID\n *     23–26 resSeq     31–38 x         39–46 y         47–54 z\n *     77–78 element\n */\nfunction parsePdb(text: string, id: string): ProteinStructure {\n  const atoms: ProteinAtom[] = []\n  const spans: SecondarySpan[] = []\n  let title = \"\"\n\n  for (const line of text.split(\"\\n\")) {\n    const record = line.slice(0, 6).trim()\n\n    // Everything after the first `ENDMDL` is another conformation of what we\n    // already have. Stopping at it rather than filtering by model number also\n    // ends the read early on a large ensemble.\n    if (record === \"ENDMDL\") break\n\n    if (record === \"ATOM\" || record === \"HETATM\") {\n      const atom = parsePdbAtom(line, record === \"HETATM\")\n      if (atom) atoms.push(atom)\n      continue\n    }\n\n    if (record === \"TITLE\") {\n      // A long title is continued across several records, with the continuation\n      // number in columns 9–10 and the text always from column 11.\n      title = `${title} ${line.slice(10).trim()}`.trim()\n      continue\n    }\n\n    // The two annotation records. Their first-residue fields sit at *different*\n    // offsets from each other — a genuine wart of the format rather than a\n    // mistake here — while their last-residue fields agree.\n    if (record === \"HELIX\") {\n      const span = pdbSpan(line, 19, 21, \"helix\")\n      if (span) spans.push(span)\n      continue\n    }\n    if (record === \"SHEET\") {\n      const span = pdbSpan(line, 21, 22, \"sheet\")\n      if (span) spans.push(span)\n    }\n  }\n\n  return deriveStructure(id, title, atoms, spans)\n}\n\n/** One `ATOM`/`HETATM` record, or `null` when its coordinates don't read. */\nfunction parsePdbAtom(line: string, hetero: boolean): ProteinAtom | null {\n  // Truncated before the coordinates. Worth checking outright: a short slice of\n  // a fixed-column record reads as the empty string, and `Number(\"\")` is 0\n  // rather than `NaN` — so without this a mangled line becomes an atom sitting\n  // at the origin, which is far harder to notice than a missing one.\n  if (line.length < 54) return null\n\n  // An alternate location: the same atom modelled twice because the side chain\n  // is disordered. Keeping both would double the sticks through that residue,\n  // so take the first (blank or `A`), which is the convention.\n  const altLoc = line.slice(16, 17).trim()\n  if (altLoc !== \"\" && altLoc !== \"A\") return null\n\n  const x = Number(line.slice(30, 38))\n  const y = Number(line.slice(38, 46))\n  const z = Number(line.slice(46, 54))\n  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {\n    return null\n  }\n\n  const name = line.slice(12, 16).trim()\n  const residue = line.slice(17, 20).trim()\n  const kind = residueKind(residue)\n\n  return {\n    serial: Number(line.slice(6, 11)) || 0,\n    name,\n    element: elementOf(line.slice(76, 78), name, kind),\n    residue,\n    residueSeq: Number(line.slice(22, 26)) || 0,\n    // A file with a single unnamed chain leaves the column blank; calling that\n    // `A` keeps \"group by chain\" from producing one group named nothing.\n    chain: line.slice(21, 22).trim() || \"A\",\n    x,\n    y,\n    z,\n    hetero,\n    kind,\n  }\n}\n\n/** Where the last residue's number sits on both `HELIX` and `SHEET` — columns 34–37. */\nconst PDB_SPAN_END_AT = 33\n\n/**\n * One `HELIX`/`SHEET` record as a residue span.\n *\n * The first-residue offsets differ between the two records, so they are passed\n * in rather than hard-coded: a helix names its chain in column 20 and its first\n * residue in 22–25, a sheet names its chain in 22 and its first residue in\n * 23–26. Their *last* residue is in the same place in both, which is the one\n * thing they agree on.\n */\nfunction pdbSpan(\n  line: string,\n  chainAt: number,\n  startAt: number,\n  kind: SecondarySpan[\"kind\"]\n): SecondarySpan | null {\n  const chain = line.slice(chainAt, chainAt + 1).trim() || \"A\"\n  // Read as text first: a blank fixed-column field slices to `\"\"`, and\n  // `Number(\"\")` is 0, so a `Number.isFinite` check alone would accept a record\n  // that states nothing as a span over residue 0.\n  const startText = line.slice(startAt, startAt + 4).trim()\n  const endText = line.slice(PDB_SPAN_END_AT, PDB_SPAN_END_AT + 4).trim()\n  if (startText === \"\" || endText === \"\") return null\n\n  const start = Number(startText)\n  const end = Number(endText)\n  if (!Number.isFinite(start) || !Number.isFinite(end)) return null\n  return { chain, start, end, kind }\n}\n\n// --- mmCIF -----------------------------------------------------------------\n\n/**\n * Reads mmCIF, which is a tagged format rather than a positional one: values are\n * whitespace-separated and their meaning comes from the column headers declared\n * above them, so the reader has to learn the layout before it can read a row.\n *\n * Only three categories are consulted — the atoms, and the two that annotate\n * secondary structure. mmCIF carries dozens more, and every one this doesn't\n * read is one this can't be broken by.\n */\nfunction parseMmcif(text: string, id: string): ProteinStructure {\n  const lines = text.split(\"\\n\")\n  const atoms = mmcifAtoms(lines)\n  const spans = [\n    ...mmcifSpans(lines, \"_struct_conf\", \"helix\"),\n    ...mmcifSpans(lines, \"_struct_sheet_range\", \"sheet\"),\n  ]\n  return deriveStructure(id, mmcifTitle(lines), atoms, spans)\n}\n\n/** The atoms of the first model in an `_atom_site` loop. */\nfunction mmcifAtoms(lines: string[]): ProteinAtom[] {\n  const atoms: ProteinAtom[] = []\n  let model: string | null = null\n\n  for (const row of mmcifRows(lines, \"_atom_site\")) {\n    // `auth_*` is the numbering the literature uses and the one a PDB file would\n    // have carried; `label_*` is the internal, re-derived scheme. Preferring\n    // auth means a residue number quoted in a paper matches what is drawn, and\n    // falling back keeps a file that omits it readable.\n    const chain = row(\"auth_asym_id\") || row(\"label_asym_id\") || \"A\"\n    const residue = row(\"auth_comp_id\") || row(\"label_comp_id\")\n    const name = row(\"auth_atom_id\") || row(\"label_atom_id\")\n\n    const thisModel = row(\"pdbx_PDB_model_num\")\n    if (model === null) model = thisModel\n    else if (thisModel !== model) break\n\n    const altLoc = row(\"label_alt_id\")\n    if (altLoc !== \"\" && altLoc !== \".\" && altLoc !== \"?\" && altLoc !== \"A\") {\n      continue\n    }\n\n    const x = Number(row(\"Cartn_x\"))\n    const y = Number(row(\"Cartn_y\"))\n    const z = Number(row(\"Cartn_z\"))\n    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {\n      continue\n    }\n\n    const kind = residueKind(residue)\n    atoms.push({\n      serial: Number(row(\"id\")) || 0,\n      name,\n      element: elementOf(row(\"type_symbol\"), name, kind),\n      residue,\n      residueSeq: Number(row(\"auth_seq_id\") || row(\"label_seq_id\")) || 0,\n      chain,\n      x,\n      y,\n      z,\n      hetero: row(\"group_PDB\") === \"HETATM\",\n      kind,\n    })\n  }\n\n  return atoms\n}\n\n/** The residue spans of one annotation category. */\nfunction mmcifSpans(\n  lines: string[],\n  category: string,\n  kind: SecondarySpan[\"kind\"]\n): SecondarySpan[] {\n  const spans: SecondarySpan[] = []\n\n  for (const row of mmcifRows(lines, category)) {\n    // `_struct_conf` covers turns and bends as well as helices, all under one\n    // category and told apart by this tag. A sheet range has no such tag, so an\n    // absent one passes.\n    const type = row(\"conf_type_id\")\n    if (type !== \"\" && !type.startsWith(\"HELX\")) continue\n\n    const chain = row(\"beg_auth_asym_id\") || row(\"beg_label_asym_id\") || \"A\"\n    const start = Number(row(\"beg_auth_seq_id\") || row(\"beg_label_seq_id\"))\n    const end = Number(row(\"end_auth_seq_id\") || row(\"end_label_seq_id\"))\n    if (!Number.isFinite(start) || !Number.isFinite(end)) continue\n    spans.push({ chain, start, end, kind })\n  }\n\n  return spans\n}\n\n/** The entry's title, from the `_struct.title` item. */\nfunction mmcifTitle(lines: string[]): string {\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i]!\n    if (!line.startsWith(\"_struct.title\")) continue\n    const inline = line.slice(\"_struct.title\".length).trim()\n    // A value too long for the line is carried on the next one, or in a\n    // semicolon-delimited block below it; the inline form covers the rest.\n    if (inline !== \"\") return unquote(inline)\n    const next = lines[i + 1]?.trim() ?? \"\"\n    return unquote(next.startsWith(\";\") ? next.slice(1) : next)\n  }\n  return \"\"\n}\n\n/**\n * Walks the rows of one mmCIF category, yielding a field reader for each.\n *\n * The reader is a closure over the current row rather than an object, so\n * nothing allocates a record per atom — this runs over hundreds of thousands of\n * rows on a large entry, and the caller only ever wants a handful of the fields.\n *\n * Handles both forms a category takes: a `loop_` with a header block and many\n * rows, and the flat `_category.field value` form mmCIF uses when there is\n * exactly one row.\n */\nfunction* mmcifRows(\n  lines: string[],\n  category: string\n): Generator<(field: string) => string> {\n  const prefix = `${category}.`\n\n  for (let i = 0; i < lines.length; i++) {\n    const line = lines[i]!.trim()\n\n    // The flat, single-row form: consecutive `_category.field value` lines.\n    if (line.startsWith(prefix)) {\n      const single = new Map<string, string>()\n      while (i < lines.length) {\n        const item = lines[i]!.trim()\n        if (!item.startsWith(prefix)) break\n        const gap = item.search(/\\s/)\n        if (gap === -1) {\n          // A field whose value is on the following line.\n          single.set(item.slice(prefix.length), unquote(lines[++i]?.trim() ?? \"\"))\n        } else {\n          single.set(\n            item.slice(prefix.length, gap),\n            unquote(item.slice(gap).trim())\n          )\n        }\n        i++\n      }\n      yield (field) => single.get(field) ?? \"\"\n      return\n    }\n\n    if (line !== \"loop_\") continue\n\n    // The header block: every `_category.field` line, in the order the values\n    // will arrive in.\n    const columns = new Map<string, number>()\n    let cursor = i + 1\n    while (cursor < lines.length) {\n      const header = lines[cursor]!.trim()\n      if (!header.startsWith(\"_\")) break\n      if (header.startsWith(prefix)) {\n        columns.set(header.slice(prefix.length), columns.size)\n      }\n      cursor++\n    }\n    // A `loop_` for some other category. Its rows carry no leading underscore\n    // and aren't `loop_`, so the outer scan walks past them harmlessly.\n    if (columns.size === 0) continue\n\n    for (; cursor < lines.length; cursor++) {\n      const row = lines[cursor]!\n      const trimmed = row.trim()\n      // A loop ends at the next block, the next loop, or a blank line.\n      if (trimmed === \"\" || trimmed === \"#\" || trimmed.startsWith(\"_\")) break\n      if (trimmed === \"loop_\" || trimmed.startsWith(\"data_\")) break\n\n      const values = splitCifRow(trimmed)\n      yield (field) => {\n        const index = columns.get(field)\n        if (index === undefined) return \"\"\n        const value = values[index] ?? \"\"\n        return value === \".\" || value === \"?\" ? \"\" : value\n      }\n    }\n    return\n  }\n}\n\n/**\n * Splits one mmCIF row into values, respecting quotes.\n *\n * Quoting is not decoration here: a chain identifier can be `'A'`, and a residue\n * name can contain a space that a plain `split` would turn into two columns and\n * shift every field after it by one.\n */\nfunction splitCifRow(row: string): string[] {\n  const values: string[] = []\n  let i = 0\n\n  while (i < row.length) {\n    const char = row[i]!\n    if (char === \" \" || char === \"\\t\") {\n      i++\n      continue\n    }\n    if (char === \"'\" || char === '\"') {\n      const end = row.indexOf(char, i + 1)\n      if (end === -1) {\n        values.push(row.slice(i + 1))\n        break\n      }\n      values.push(row.slice(i + 1, end))\n      i = end + 1\n      continue\n    }\n    let end = i\n    while (end < row.length && row[end] !== \" \" && row[end] !== \"\\t\") end++\n    values.push(row.slice(i, end))\n    i = end\n  }\n\n  return values\n}\n\n/** Strips the quotes mmCIF wraps a value in, and the null placeholders. */\nfunction unquote(value: string): string {\n  const text = value.trim()\n  if (text === \".\" || text === \"?\") return \"\"\n  const first = text[0]\n  if ((first === \"'\" || first === '\"') && text.endsWith(first) && text.length > 1) {\n    return text.slice(1, -1)\n  }\n  return text\n}\n"]}