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

package/dist/protein/structure.d.ts

@@ -0,0 +1,184 @@
+/**
+ * What a parsed molecule *is*, and the three things derived from it that no
+ * coordinate file states outright: which atoms are bonded, which curve each
+ * chain traces, and how big the whole thing is.
+ *
+ * The shape here is the seam between the parser (`parse.ts`) and the node
+ * (`protein.ts`), and it is deliberately flat and numeric: parallel arrays of
+ * plain numbers rather than a graph of objects. A mid-sized structure is tens of
+ * thousands of atoms, the node rebuilds its command list every frame, and an
+ * object per atom would put a few hundred thousand allocations between the
+ * scrubber and the picture.
+ *
+ * Parsing happens **once, ahead of the build** — the same arrangement a chart's
+ * CSV gets (see `SceneAsset.rows`), and for the same reason: `buildScene` is
+ * synchronous, so anything that has to be read off a network or a file has to
+ * already be here by the time it runs.
+ */
+import { type ResidueKind } from "./chemistry.js";
+/** One atom, as the file gave it. Coordinates are in Ångströms. */
+export interface ProteinAtom {
+    /** The file's own serial number, kept so `CONECT` records can be resolved. */
+    serial: number;
+    /** The atom's name within its residue — `CA`, `OG1`, `FE`. */
+    name: string;
+    /** The element symbol, upper-cased. Derived when the file omits it. */
+    element: string;
+    /** The residue's three-letter code — `ALA`, `HOH`, `HEM`. */
+    residue: string;
+    /** The residue's number within its chain, as the file numbers it. */
+    residueSeq: number;
+    /** The chain the residue belongs to — `A`, `B`, … */
+    chain: string;
+    x: number;
+    y: number;
+    z: number;
+    /** Whether the file filed this under `HETATM` — a ligand, an ion, a water. */
+    hetero: boolean;
+    /** What the residue is, resolved once here so nothing downstream re-derives it. */
+    kind: ResidueKind;
+}
+/**
+ * What a stretch of backbone is doing, which is the one property of a protein
+ * that a picture of it is usually *about*.
+ *
+ * Taken from the file's own `HELIX`/`SHEET` annotations rather than computed:
+ * assigning secondary structure from coordinates alone is DSSP, which is a
+ * hydrogen-bond model and a paper of its own. A file that annotates none draws
+ * as an even tube, which is the honest picture of "nobody said".
+ */
+export type SecondaryStructure = "helix" | "sheet" | "coil";
+/** One residue's place on a chain's backbone curve. */
+export interface TracePoint {
+    x: number;
+    y: number;
+    z: number;
+    /** What this residue is part of, for the ribbon's shape and its colouring. */
+    secondary: SecondaryStructure;
+    /**
+     * The residue's position along **this trace**, 0-based. Against the trace's
+     * own length this is what a spectrum colouring needs: N terminus to C
+     * terminus, per chain, independent of how long the others are.
+     */
+    index: number;
+    /**
+     * The residue's number as the file gives it, which is what ties a trace point
+     * back to the atoms of the same residue.
+     *
+     * Both are needed and neither substitutes for the other: {@link index} is
+     * dense and ordered, so it is what a spectrum is computed against, while this
+     * is sparse and arbitrary — files skip numbers, start at 17, and number
+     * insertions — so it is what a *lookup* has to be keyed on.
+     */
+    residueSeq: number;
+    /**
+     * Which way this residue's ribbon faces — the unit vector its **wide**
+     * direction is swept along.
+     *
+     * A tube needs a point and nothing else; a cartoon ribbon needs to know which
+     * way round it is, and that is not something a curve through α-carbons can
+     * answer. The residue's own carbonyl does: CA→O is roughly perpendicular to
+     * the chain and turns with the fold, so sweeping the ribbon's width along it
+     * is what makes a helix read as a twisted band and a strand as a flat one.
+     * This is the same vector every molecular viewer builds its cartoon frame
+     * from.
+     *
+     * `null` when the file has no carbonyl for the residue — a Cα-only model, a
+     * nucleotide, the last residue of a truncated chain — and the ribbon builder
+     * falls back to the curve's own binormal there. See `ribbonFrames`.
+     *
+     * Not orthogonalized here: it is a *direction*, and the frame that has to be
+     * square is built against the tangent, which only exists once the neighbours
+     * are known.
+     */
+    normal: {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+}
+/** One polymer chain: its identity and the curve its backbone follows. */
+export interface ProteinChain {
+    /** The chain identifier the file uses — `A`, `B`, … */
+    id: string;
+    /** The α-carbon (or phosphorus) trace, in residue order. */
+    trace: TracePoint[];
+}
+/**
+ * A parsed molecule.
+ *
+ * Bonds and chains are *derived* (see {@link deriveStructure}) rather than read,
+ * because coordinate files mostly don't state them: `CONECT` records cover the
+ * ligands and little else, and the chain break between two residues is implied
+ * by their distance.
+ */
+export interface ProteinStructure {
+    /** The accession or filename this came from, for labelling. */
+    id: string;
+    /** The file's `TITLE`, when it has one. */
+    title: string;
+    atoms: ProteinAtom[];
+    /** Bonded pairs, as indices into {@link atoms}. */
+    bonds: ProteinBond[];
+    chains: ProteinChain[];
+    /** The centroid of every atom — what the node translates to the origin. */
+    center: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Distance from {@link center} to the furthest atom, in Ångströms. */
+    radius: number;
+}
+/** One bond, as a pair of indices into {@link ProteinStructure.atoms}. */
+export interface ProteinBond {
+    a: number;
+    b: number;
+}
+/** An empty molecule — what an unresolved or unparseable source draws as. */
+export declare const EMPTY_STRUCTURE: ProteinStructure;
+/**
+ * A secondary-structure span as the file states it: a run of residue numbers on
+ * one chain. Collected by the parser, applied to the traces here.
+ */
+export interface SecondarySpan {
+    chain: string;
+    start: number;
+    end: number;
+    kind: Exclude<SecondaryStructure, "coil">;
+}
+/**
+ * Completes a parsed atom list into a {@link ProteinStructure}: infers the
+ * bonds, walks out each chain's backbone, and measures the whole thing.
+ *
+ * Split from the parsers because both formats reach the same place — an atom
+ * list and a set of annotated spans — and everything past that point is
+ * geometry rather than syntax.
+ */
+export declare function deriveStructure(id: string, title: string, atoms: ProteinAtom[], spans: SecondarySpan[]): ProteinStructure;
+/**
+ * Infers bonds by distance, over a uniform grid.
+ *
+ * The grid is what makes this affordable. Bonding is a nearest-neighbour
+ * question and the naïve form is every atom against every other — 20,000 atoms
+ * is 200 million comparisons, which is a visible freeze on the frame someone
+ * picks a structure. Bucketed at the maximum bond length, each atom only looks
+ * at the 27 cells around it, and since the cells are that size no bond can span
+ * further, so nothing is missed. The work becomes linear in the atom count.
+ *
+ * Waters are skipped outright: they are a single oxygen with nothing to bond to
+ * (their hydrogens are almost never in the file), so every comparison against
+ * one is wasted, and there can be more of them than there are protein atoms.
+ */
+export declare function inferBonds(atoms: ProteinAtom[]): ProteinBond[];
+/**
+ * The backbone curve of every chain, in residue order, with each residue's
+ * secondary structure attached.
+ *
+ * A chain break starts a **new trace** rather than being drawn through — see
+ * {@link CHAIN_BREAK_DISTANCE} — so one chain identifier can produce several
+ * entries. That is the right unit downstream anyway: each entry is one
+ * continuous curve, which is exactly what a tube is swept along.
+ */
+export declare function traceChains(atoms: ProteinAtom[], spans: SecondarySpan[]): ProteinChain[];
+//# sourceMappingURL=structure.d.ts.map

package/dist/protein/structure.d.ts.map

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

package/dist/protein/structure.js

@@ -0,0 +1,324 @@
+/**
+ * What a parsed molecule *is*, and the three things derived from it that no
+ * coordinate file states outright: which atoms are bonded, which curve each
+ * chain traces, and how big the whole thing is.
+ *
+ * The shape here is the seam between the parser (`parse.ts`) and the node
+ * (`protein.ts`), and it is deliberately flat and numeric: parallel arrays of
+ * plain numbers rather than a graph of objects. A mid-sized structure is tens of
+ * thousands of atoms, the node rebuilds its command list every frame, and an
+ * object per atom would put a few hundred thousand allocations between the
+ * scrubber and the picture.
+ *
+ * Parsing happens **once, ahead of the build** — the same arrangement a chart's
+ * CSV gets (see `SceneAsset.rows`), and for the same reason: `buildScene` is
+ * synchronous, so anything that has to be read off a network or a file has to
+ * already be here by the time it runs.
+ */
+import { covalentRadius, traceAtomName } from "./chemistry.js";
+/** An empty molecule — what an unresolved or unparseable source draws as. */
+export const EMPTY_STRUCTURE = {
+    id: "",
+    title: "",
+    atoms: [],
+    bonds: [],
+    chains: [],
+    center: { x: 0, y: 0, z: 0 },
+    radius: 1,
+};
+/**
+ * Completes a parsed atom list into a {@link ProteinStructure}: infers the
+ * bonds, walks out each chain's backbone, and measures the whole thing.
+ *
+ * Split from the parsers because both formats reach the same place — an atom
+ * list and a set of annotated spans — and everything past that point is
+ * geometry rather than syntax.
+ */
+export function deriveStructure(id, title, atoms, spans) {
+    if (atoms.length === 0)
+        return { ...EMPTY_STRUCTURE, id, title };
+    return {
+        id,
+        title,
+        atoms,
+        bonds: inferBonds(atoms),
+        chains: traceChains(atoms, spans),
+        ...measure(atoms),
+    };
+}
+// --- Bonds -----------------------------------------------------------------
+/**
+ * How much further apart than the sum of their covalent radii two atoms may sit
+ * and still count as bonded, in Ångströms.
+ *
+ * The conventional tolerance. It has to be generous enough to survive a
+ * moderate-resolution structure's coordinate error and mean enough not to bond
+ * a residue to the one packed against it — 0.45 Å is where every viewer has
+ * settled, and the gap between a real bond (~1.5 Å) and the closest non-bonded
+ * contact (~2.8 Å) is wide enough that the exact number rarely decides anything.
+ */
+const BOND_TOLERANCE = 0.45;
+/**
+ * The shortest separation treated as a bond. Two atoms closer than this are
+ * alternate conformations of the same one, or a duplicate record — bonding them
+ * would draw a stick of no length and a mesh with no orientation.
+ */
+const MIN_BOND_LENGTH = 0.4;
+/**
+ * The furthest two atoms can be bonded, which sets the neighbour grid's cell
+ * size: the largest pair of covalent radii here (potassium's, twice) plus the
+ * tolerance.
+ */
+const MAX_BOND_LENGTH = 2.5;
+/**
+ * Infers bonds by distance, over a uniform grid.
+ *
+ * The grid is what makes this affordable. Bonding is a nearest-neighbour
+ * question and the naïve form is every atom against every other — 20,000 atoms
+ * is 200 million comparisons, which is a visible freeze on the frame someone
+ * picks a structure. Bucketed at the maximum bond length, each atom only looks
+ * at the 27 cells around it, and since the cells are that size no bond can span
+ * further, so nothing is missed. The work becomes linear in the atom count.
+ *
+ * Waters are skipped outright: they are a single oxygen with nothing to bond to
+ * (their hydrogens are almost never in the file), so every comparison against
+ * one is wasted, and there can be more of them than there are protein atoms.
+ */
+export function inferBonds(atoms) {
+    const bonds = [];
+    const cells = new Map();
+    const radii = new Float32Array(atoms.length);
+    for (let i = 0; i < atoms.length; i++) {
+        const atom = atoms[i];
+        if (atom.kind === "water")
+            continue;
+        radii[i] = covalentRadius(atom.element);
+        const key = cellKey(atom.x, atom.y, atom.z);
+        const bucket = cells.get(key);
+        if (bucket)
+            bucket.push(i);
+        else
+            cells.set(key, [i]);
+    }
+    for (const [key, bucket] of cells) {
+        const [cx, cy, cz] = key.split(",").map(Number);
+        for (let dx = -1; dx <= 1; dx++) {
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dz = -1; dz <= 1; dz++) {
+                    const neighbours = cells.get(`${cx + dx},${cy + dy},${cz + dz}`);
+                    if (!neighbours)
+                        continue;
+                    for (const i of bucket) {
+                        for (const j of neighbours) {
+                            // Each unordered pair is reached from both cells, so keep only one
+                            // ordering. This also excludes an atom against itself.
+                            if (j <= i)
+                                continue;
+                            const a = atoms[i];
+                            const b = atoms[j];
+                            const limit = radii[i] + radii[j] + BOND_TOLERANCE;
+                            const dxx = a.x - b.x;
+                            const dyy = a.y - b.y;
+                            const dzz = a.z - b.z;
+                            const squared = dxx * dxx + dyy * dyy + dzz * dzz;
+                            if (squared > limit * limit)
+                                continue;
+                            if (squared < MIN_BOND_LENGTH * MIN_BOND_LENGTH)
+                                continue;
+                            bonds.push({ a: i, b: j });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return bonds;
+}
+/** The grid cell a coordinate falls in, as a map key. */
+function cellKey(x, y, z) {
+    const cx = Math.floor(x / MAX_BOND_LENGTH);
+    const cy = Math.floor(y / MAX_BOND_LENGTH);
+    const cz = Math.floor(z / MAX_BOND_LENGTH);
+    return `${cx},${cy},${cz}`;
+}
+// --- Chains ----------------------------------------------------------------
+/**
+ * How far apart two consecutive α-carbons may sit and still be the same chain,
+ * in Ångströms.
+ *
+ * Consecutive α-carbons are 3.8 Å apart — the distance is fixed by the peptide
+ * bond's geometry, not by what the protein is doing — so a larger gap is a
+ * *chain break*: a disordered loop the crystallographer could not resolve, which
+ * the file records by simply skipping those residues. Drawing through one would
+ * run a ribbon across the middle of the molecule between two ends that are not
+ * joined. Nucleotide phosphorus atoms sit further apart (~6 Å), which is why the
+ * threshold is well above 3.8 rather than snug against it.
+ */
+const CHAIN_BREAK_DISTANCE = 7.5;
+/**
+ * The backbone curve of every chain, in residue order, with each residue's
+ * secondary structure attached.
+ *
+ * A chain break starts a **new trace** rather than being drawn through — see
+ * {@link CHAIN_BREAK_DISTANCE} — so one chain identifier can produce several
+ * entries. That is the right unit downstream anyway: each entry is one
+ * continuous curve, which is exactly what a tube is swept along.
+ */
+export function traceChains(atoms, spans) {
+    const assign = secondaryLookup(spans);
+    // Built ahead of the walk rather than during it, because the carbonyl comes
+    // *after* the α-carbon in a residue's records and the trace point is written
+    // as the α-carbon is reached. One pass over the atoms costs nothing beside
+    // the bond inference already running over them.
+    const carbonyls = carbonylDirections(atoms);
+    const chains = [];
+    let current = null;
+    let previous = null;
+    for (const atom of atoms) {
+        if (atom.name !== traceAtomName(atom.kind))
+            continue;
+        const broken = previous !== null &&
+            (previous.chain !== atom.chain ||
+                distance(previous, atom) > CHAIN_BREAK_DISTANCE);
+        if (current === null || broken) {
+            current = { id: atom.chain, trace: [] };
+            chains.push(current);
+        }
+        current.trace.push({
+            x: atom.x,
+            y: atom.y,
+            z: atom.z,
+            secondary: assign(atom.chain, atom.residueSeq),
+            index: current.trace.length,
+            residueSeq: atom.residueSeq,
+            normal: carbonyls.get(residueKey(atom)) ?? null,
+        });
+        previous = atom;
+    }
+    // A single point is not a curve — nothing can be swept along it and no
+    // direction can be taken from it — so a lone resolved residue is dropped
+    // rather than left for the tube builder to divide by zero over.
+    return chains.filter((chain) => chain.trace.length > 1);
+}
+/**
+ * Builds the residue → secondary-structure lookup.
+ *
+ * A map per chain of residue number to kind, rather than a scan of the span list
+ * per residue: a large structure has thousands of residues and hundreds of
+ * spans, and the product of the two is the sort of quiet quadratic that only
+ * shows up on the file somebody actually cares about.
+ */
+function secondaryLookup(spans) {
+    const byChain = new Map();
+    for (const span of spans) {
+        let residues = byChain.get(span.chain);
+        if (!residues) {
+            residues = new Map();
+            byChain.set(span.chain, residues);
+        }
+        // A malformed span (end before start, or one covering the whole file) would
+        // otherwise fill the map with junk; the loop simply doesn't run backwards.
+        for (let seq = span.start; seq <= span.end; seq++) {
+            residues.set(seq, span.kind);
+        }
+    }
+    return (chain, residue) => byChain.get(chain)?.get(residue) ?? "coil";
+}
+/** A residue's identity across the whole file — its chain and its number. */
+function residueKey(atom) {
+    return `${atom.chain}:${atom.residueSeq}`;
+}
+/**
+ * The unit CA→O vector of every amino-acid residue that has both atoms.
+ *
+ * This is the one piece of chemistry a *cartoon* needs and a tube does not. A
+ * ribbon has a width, so it has a side, and nothing about a curve through
+ * α-carbons says which way round it should be: sweep a flat band along that
+ * curve with an arbitrary frame and a helix comes out as a twisted ribbon in
+ * the wrong plane, its face turning at random rather than with the fold.
+ *
+ * The carbonyl is what every molecular viewer resolves that with. It points
+ * roughly across the chain, it is what hydrogen-bonds a helix to itself and a
+ * strand to its neighbour, and so it turns *with* the structure — which makes a
+ * band swept along it lie the way the fold does.
+ *
+ * Amino acids only. A nucleotide's ribbon has no equivalent (its trace atom is
+ * the phosphorus and its "width" is the base pair), and a residue whose file
+ * gives no `O` — a Cα-only model, a truncated terminus — simply has no entry;
+ * both fall back to the curve's own binormal in the ribbon builder.
+ */
+function carbonylDirections(atoms) {
+    const alpha = new Map();
+    const oxygen = new Map();
+    for (const atom of atoms) {
+        if (atom.kind !== "amino")
+            continue;
+        // The first record of each name wins, which is what picks conformation A
+        // out of a residue the file gives two of: alternates are written in order
+        // and the ribbon needs one frame, not an average of two.
+        if (atom.name === "CA") {
+            if (!alpha.has(residueKey(atom)))
+                alpha.set(residueKey(atom), atom);
+        }
+        else if (atom.name === "O") {
+            if (!oxygen.has(residueKey(atom)))
+                oxygen.set(residueKey(atom), atom);
+        }
+    }
+    const directions = new Map();
+    for (const [key, ca] of alpha) {
+        const o = oxygen.get(key);
+        if (!o)
+            continue;
+        const x = o.x - ca.x;
+        const y = o.y - ca.y;
+        const z = o.z - ca.z;
+        const length = Math.hypot(x, y, z);
+        // A zero-length carbonyl is a duplicated record rather than a direction.
+        if (length < 1e-6)
+            continue;
+        directions.set(key, { x: x / length, y: y / length, z: z / length });
+    }
+    return directions;
+}
+/** Straight-line distance between two atoms, in Ångströms. */
+function distance(a, b) {
+    return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+}
+// --- Bounds ----------------------------------------------------------------
+/**
+ * The molecule's centroid and the radius of the sphere about it that holds every
+ * atom.
+ *
+ * The centroid rather than the centre of the bounding box: a structure with one
+ * long tail — a coiled-coil, a nucleic acid strand hanging off a complex —
+ * has a box whose centre is nowhere near the mass of it, and the camera would
+ * frame the empty half.
+ *
+ * The radius is floored above zero so a single-atom file (or one whose
+ * coordinates are all identical) still gives the camera a distance to work from
+ * rather than parking it inside the atom.
+ */
+function measure(atoms) {
+    let sx = 0;
+    let sy = 0;
+    let sz = 0;
+    for (const atom of atoms) {
+        sx += atom.x;
+        sy += atom.y;
+        sz += atom.z;
+    }
+    const center = {
+        x: sx / atoms.length,
+        y: sy / atoms.length,
+        z: sz / atoms.length,
+    };
+    let radius = 0;
+    for (const atom of atoms) {
+        const d = Math.hypot(atom.x - center.x, atom.y - center.y, atom.z - center.z);
+        if (d > radius)
+            radius = d;
+    }
+    return { center, radius: Math.max(radius, 1) };
+}
+//# sourceMappingURL=structure.js.map

package/dist/protein/structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/protein/structure.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a parsed molecule *is*, and the three things derived from it that no\n * coordinate file states outright: which atoms are bonded, which curve each\n * chain traces, and how big the whole thing is.\n *\n * The shape here is the seam between the parser (`parse.ts`) and the node\n * (`protein.ts`), and it is deliberately flat and numeric: parallel arrays of\n * plain numbers rather than a graph of objects. A mid-sized structure is tens of\n * thousands of atoms, the node rebuilds its command list every frame, and an\n * object per atom would put a few hundred thousand allocations between the\n * scrubber and the picture.\n *\n * Parsing happens **once, ahead of the build** — the same arrangement a chart's\n * CSV gets (see `SceneAsset.rows`), and for the same reason: `buildScene` is\n * synchronous, so anything that has to be read off a network or a file has to\n * already be here by the time it runs.\n */\n\nimport { covalentRadius, traceAtomName, type ResidueKind } from \"./chemistry\"\n\n/** One atom, as the file gave it. Coordinates are in Ångströms. */\nexport interface ProteinAtom {\n  /** The file's own serial number, kept so `CONECT` records can be resolved. */\n  serial: number\n  /** The atom's name within its residue — `CA`, `OG1`, `FE`. */\n  name: string\n  /** The element symbol, upper-cased. Derived when the file omits it. */\n  element: string\n  /** The residue's three-letter code — `ALA`, `HOH`, `HEM`. */\n  residue: string\n  /** The residue's number within its chain, as the file numbers it. */\n  residueSeq: number\n  /** The chain the residue belongs to — `A`, `B`, … */\n  chain: string\n  x: number\n  y: number\n  z: number\n  /** Whether the file filed this under `HETATM` — a ligand, an ion, a water. */\n  hetero: boolean\n  /** What the residue is, resolved once here so nothing downstream re-derives it. */\n  kind: ResidueKind\n}\n\n/**\n * What a stretch of backbone is doing, which is the one property of a protein\n * that a picture of it is usually *about*.\n *\n * Taken from the file's own `HELIX`/`SHEET` annotations rather than computed:\n * assigning secondary structure from coordinates alone is DSSP, which is a\n * hydrogen-bond model and a paper of its own. A file that annotates none draws\n * as an even tube, which is the honest picture of \"nobody said\".\n */\nexport type SecondaryStructure = \"helix\" | \"sheet\" | \"coil\"\n\n/** One residue's place on a chain's backbone curve. */\nexport interface TracePoint {\n  x: number\n  y: number\n  z: number\n  /** What this residue is part of, for the ribbon's shape and its colouring. */\n  secondary: SecondaryStructure\n  /**\n   * The residue's position along **this trace**, 0-based. Against the trace's\n   * own length this is what a spectrum colouring needs: N terminus to C\n   * terminus, per chain, independent of how long the others are.\n   */\n  index: number\n  /**\n   * The residue's number as the file gives it, which is what ties a trace point\n   * back to the atoms of the same residue.\n   *\n   * Both are needed and neither substitutes for the other: {@link index} is\n   * dense and ordered, so it is what a spectrum is computed against, while this\n   * is sparse and arbitrary — files skip numbers, start at 17, and number\n   * insertions — so it is what a *lookup* has to be keyed on.\n   */\n  residueSeq: number\n  /**\n   * Which way this residue's ribbon faces — the unit vector its **wide**\n   * direction is swept along.\n   *\n   * A tube needs a point and nothing else; a cartoon ribbon needs to know which\n   * way round it is, and that is not something a curve through α-carbons can\n   * answer. The residue's own carbonyl does: CA→O is roughly perpendicular to\n   * the chain and turns with the fold, so sweeping the ribbon's width along it\n   * is what makes a helix read as a twisted band and a strand as a flat one.\n   * This is the same vector every molecular viewer builds its cartoon frame\n   * from.\n   *\n   * `null` when the file has no carbonyl for the residue — a Cα-only model, a\n   * nucleotide, the last residue of a truncated chain — and the ribbon builder\n   * falls back to the curve's own binormal there. See `ribbonFrames`.\n   *\n   * Not orthogonalized here: it is a *direction*, and the frame that has to be\n   * square is built against the tangent, which only exists once the neighbours\n   * are known.\n   */\n  normal: { x: number; y: number; z: number } | null\n}\n\n/** One polymer chain: its identity and the curve its backbone follows. */\nexport interface ProteinChain {\n  /** The chain identifier the file uses — `A`, `B`, … */\n  id: string\n  /** The α-carbon (or phosphorus) trace, in residue order. */\n  trace: TracePoint[]\n}\n\n/**\n * A parsed molecule.\n *\n * Bonds and chains are *derived* (see {@link deriveStructure}) rather than read,\n * because coordinate files mostly don't state them: `CONECT` records cover the\n * ligands and little else, and the chain break between two residues is implied\n * by their distance.\n */\nexport interface ProteinStructure {\n  /** The accession or filename this came from, for labelling. */\n  id: string\n  /** The file's `TITLE`, when it has one. */\n  title: string\n  atoms: ProteinAtom[]\n  /** Bonded pairs, as indices into {@link atoms}. */\n  bonds: ProteinBond[]\n  chains: ProteinChain[]\n  /** The centroid of every atom — what the node translates to the origin. */\n  center: { x: number; y: number; z: number }\n  /** Distance from {@link center} to the furthest atom, in Ångströms. */\n  radius: number\n}\n\n/** One bond, as a pair of indices into {@link ProteinStructure.atoms}. */\nexport interface ProteinBond {\n  a: number\n  b: number\n}\n\n/** An empty molecule — what an unresolved or unparseable source draws as. */\nexport const EMPTY_STRUCTURE: ProteinStructure = {\n  id: \"\",\n  title: \"\",\n  atoms: [],\n  bonds: [],\n  chains: [],\n  center: { x: 0, y: 0, z: 0 },\n  radius: 1,\n}\n\n/**\n * A secondary-structure span as the file states it: a run of residue numbers on\n * one chain. Collected by the parser, applied to the traces here.\n */\nexport interface SecondarySpan {\n  chain: string\n  start: number\n  end: number\n  kind: Exclude<SecondaryStructure, \"coil\">\n}\n\n/**\n * Completes a parsed atom list into a {@link ProteinStructure}: infers the\n * bonds, walks out each chain's backbone, and measures the whole thing.\n *\n * Split from the parsers because both formats reach the same place — an atom\n * list and a set of annotated spans — and everything past that point is\n * geometry rather than syntax.\n */\nexport function deriveStructure(\n  id: string,\n  title: string,\n  atoms: ProteinAtom[],\n  spans: SecondarySpan[]\n): ProteinStructure {\n  if (atoms.length === 0) return { ...EMPTY_STRUCTURE, id, title }\n\n  return {\n    id,\n    title,\n    atoms,\n    bonds: inferBonds(atoms),\n    chains: traceChains(atoms, spans),\n    ...measure(atoms),\n  }\n}\n\n// --- Bonds -----------------------------------------------------------------\n\n/**\n * How much further apart than the sum of their covalent radii two atoms may sit\n * and still count as bonded, in Ångströms.\n *\n * The conventional tolerance. It has to be generous enough to survive a\n * moderate-resolution structure's coordinate error and mean enough not to bond\n * a residue to the one packed against it — 0.45 Å is where every viewer has\n * settled, and the gap between a real bond (~1.5 Å) and the closest non-bonded\n * contact (~2.8 Å) is wide enough that the exact number rarely decides anything.\n */\nconst BOND_TOLERANCE = 0.45\n\n/**\n * The shortest separation treated as a bond. Two atoms closer than this are\n * alternate conformations of the same one, or a duplicate record — bonding them\n * would draw a stick of no length and a mesh with no orientation.\n */\nconst MIN_BOND_LENGTH = 0.4\n\n/**\n * The furthest two atoms can be bonded, which sets the neighbour grid's cell\n * size: the largest pair of covalent radii here (potassium's, twice) plus the\n * tolerance.\n */\nconst MAX_BOND_LENGTH = 2.5\n\n/**\n * Infers bonds by distance, over a uniform grid.\n *\n * The grid is what makes this affordable. Bonding is a nearest-neighbour\n * question and the naïve form is every atom against every other — 20,000 atoms\n * is 200 million comparisons, which is a visible freeze on the frame someone\n * picks a structure. Bucketed at the maximum bond length, each atom only looks\n * at the 27 cells around it, and since the cells are that size no bond can span\n * further, so nothing is missed. The work becomes linear in the atom count.\n *\n * Waters are skipped outright: they are a single oxygen with nothing to bond to\n * (their hydrogens are almost never in the file), so every comparison against\n * one is wasted, and there can be more of them than there are protein atoms.\n */\nexport function inferBonds(atoms: ProteinAtom[]): ProteinBond[] {\n  const bonds: ProteinBond[] = []\n  const cells = new Map<string, number[]>()\n  const radii = new Float32Array(atoms.length)\n\n  for (let i = 0; i < atoms.length; i++) {\n    const atom = atoms[i]!\n    if (atom.kind === \"water\") continue\n    radii[i] = covalentRadius(atom.element)\n    const key = cellKey(atom.x, atom.y, atom.z)\n    const bucket = cells.get(key)\n    if (bucket) bucket.push(i)\n    else cells.set(key, [i])\n  }\n\n  for (const [key, bucket] of cells) {\n    const [cx, cy, cz] = key.split(\",\").map(Number) as [number, number, number]\n\n    for (let dx = -1; dx <= 1; dx++) {\n      for (let dy = -1; dy <= 1; dy++) {\n        for (let dz = -1; dz <= 1; dz++) {\n          const neighbours = cells.get(`${cx + dx},${cy + dy},${cz + dz}`)\n          if (!neighbours) continue\n\n          for (const i of bucket) {\n            for (const j of neighbours) {\n              // Each unordered pair is reached from both cells, so keep only one\n              // ordering. This also excludes an atom against itself.\n              if (j <= i) continue\n              const a = atoms[i]!\n              const b = atoms[j]!\n              const limit = radii[i]! + radii[j]! + BOND_TOLERANCE\n              const dxx = a.x - b.x\n              const dyy = a.y - b.y\n              const dzz = a.z - b.z\n              const squared = dxx * dxx + dyy * dyy + dzz * dzz\n              if (squared > limit * limit) continue\n              if (squared < MIN_BOND_LENGTH * MIN_BOND_LENGTH) continue\n              bonds.push({ a: i, b: j })\n            }\n          }\n        }\n      }\n    }\n  }\n\n  return bonds\n}\n\n/** The grid cell a coordinate falls in, as a map key. */\nfunction cellKey(x: number, y: number, z: number): string {\n  const cx = Math.floor(x / MAX_BOND_LENGTH)\n  const cy = Math.floor(y / MAX_BOND_LENGTH)\n  const cz = Math.floor(z / MAX_BOND_LENGTH)\n  return `${cx},${cy},${cz}`\n}\n\n// --- Chains ----------------------------------------------------------------\n\n/**\n * How far apart two consecutive α-carbons may sit and still be the same chain,\n * in Ångströms.\n *\n * Consecutive α-carbons are 3.8 Å apart — the distance is fixed by the peptide\n * bond's geometry, not by what the protein is doing — so a larger gap is a\n * *chain break*: a disordered loop the crystallographer could not resolve, which\n * the file records by simply skipping those residues. Drawing through one would\n * run a ribbon across the middle of the molecule between two ends that are not\n * joined. Nucleotide phosphorus atoms sit further apart (~6 Å), which is why the\n * threshold is well above 3.8 rather than snug against it.\n */\nconst CHAIN_BREAK_DISTANCE = 7.5\n\n/**\n * The backbone curve of every chain, in residue order, with each residue's\n * secondary structure attached.\n *\n * A chain break starts a **new trace** rather than being drawn through — see\n * {@link CHAIN_BREAK_DISTANCE} — so one chain identifier can produce several\n * entries. That is the right unit downstream anyway: each entry is one\n * continuous curve, which is exactly what a tube is swept along.\n */\nexport function traceChains(\n  atoms: ProteinAtom[],\n  spans: SecondarySpan[]\n): ProteinChain[] {\n  const assign = secondaryLookup(spans)\n  // Built ahead of the walk rather than during it, because the carbonyl comes\n  // *after* the α-carbon in a residue's records and the trace point is written\n  // as the α-carbon is reached. One pass over the atoms costs nothing beside\n  // the bond inference already running over them.\n  const carbonyls = carbonylDirections(atoms)\n  const chains: ProteinChain[] = []\n\n  let current: ProteinChain | null = null\n  let previous: ProteinAtom | null = null\n\n  for (const atom of atoms) {\n    if (atom.name !== traceAtomName(atom.kind)) continue\n\n    const broken =\n      previous !== null &&\n      (previous.chain !== atom.chain ||\n        distance(previous, atom) > CHAIN_BREAK_DISTANCE)\n\n    if (current === null || broken) {\n      current = { id: atom.chain, trace: [] }\n      chains.push(current)\n    }\n\n    current.trace.push({\n      x: atom.x,\n      y: atom.y,\n      z: atom.z,\n      secondary: assign(atom.chain, atom.residueSeq),\n      index: current.trace.length,\n      residueSeq: atom.residueSeq,\n      normal: carbonyls.get(residueKey(atom)) ?? null,\n    })\n    previous = atom\n  }\n\n  // A single point is not a curve — nothing can be swept along it and no\n  // direction can be taken from it — so a lone resolved residue is dropped\n  // rather than left for the tube builder to divide by zero over.\n  return chains.filter((chain) => chain.trace.length > 1)\n}\n\n/**\n * Builds the residue → secondary-structure lookup.\n *\n * A map per chain of residue number to kind, rather than a scan of the span list\n * per residue: a large structure has thousands of residues and hundreds of\n * spans, and the product of the two is the sort of quiet quadratic that only\n * shows up on the file somebody actually cares about.\n */\nfunction secondaryLookup(\n  spans: SecondarySpan[]\n): (chain: string, residue: number) => SecondaryStructure {\n  const byChain = new Map<string, Map<number, SecondaryStructure>>()\n\n  for (const span of spans) {\n    let residues = byChain.get(span.chain)\n    if (!residues) {\n      residues = new Map()\n      byChain.set(span.chain, residues)\n    }\n    // A malformed span (end before start, or one covering the whole file) would\n    // otherwise fill the map with junk; the loop simply doesn't run backwards.\n    for (let seq = span.start; seq <= span.end; seq++) {\n      residues.set(seq, span.kind)\n    }\n  }\n\n  return (chain, residue) => byChain.get(chain)?.get(residue) ?? \"coil\"\n}\n\n/** A residue's identity across the whole file — its chain and its number. */\nfunction residueKey(atom: ProteinAtom): string {\n  return `${atom.chain}:${atom.residueSeq}`\n}\n\n/**\n * The unit CA→O vector of every amino-acid residue that has both atoms.\n *\n * This is the one piece of chemistry a *cartoon* needs and a tube does not. A\n * ribbon has a width, so it has a side, and nothing about a curve through\n * α-carbons says which way round it should be: sweep a flat band along that\n * curve with an arbitrary frame and a helix comes out as a twisted ribbon in\n * the wrong plane, its face turning at random rather than with the fold.\n *\n * The carbonyl is what every molecular viewer resolves that with. It points\n * roughly across the chain, it is what hydrogen-bonds a helix to itself and a\n * strand to its neighbour, and so it turns *with* the structure — which makes a\n * band swept along it lie the way the fold does.\n *\n * Amino acids only. A nucleotide's ribbon has no equivalent (its trace atom is\n * the phosphorus and its \"width\" is the base pair), and a residue whose file\n * gives no `O` — a Cα-only model, a truncated terminus — simply has no entry;\n * both fall back to the curve's own binormal in the ribbon builder.\n */\nfunction carbonylDirections(\n  atoms: ProteinAtom[]\n): Map<string, { x: number; y: number; z: number }> {\n  const alpha = new Map<string, ProteinAtom>()\n  const oxygen = new Map<string, ProteinAtom>()\n\n  for (const atom of atoms) {\n    if (atom.kind !== \"amino\") continue\n    // The first record of each name wins, which is what picks conformation A\n    // out of a residue the file gives two of: alternates are written in order\n    // and the ribbon needs one frame, not an average of two.\n    if (atom.name === \"CA\") {\n      if (!alpha.has(residueKey(atom))) alpha.set(residueKey(atom), atom)\n    } else if (atom.name === \"O\") {\n      if (!oxygen.has(residueKey(atom))) oxygen.set(residueKey(atom), atom)\n    }\n  }\n\n  const directions = new Map<string, { x: number; y: number; z: number }>()\n  for (const [key, ca] of alpha) {\n    const o = oxygen.get(key)\n    if (!o) continue\n    const x = o.x - ca.x\n    const y = o.y - ca.y\n    const z = o.z - ca.z\n    const length = Math.hypot(x, y, z)\n    // A zero-length carbonyl is a duplicated record rather than a direction.\n    if (length < 1e-6) continue\n    directions.set(key, { x: x / length, y: y / length, z: z / length })\n  }\n  return directions\n}\n\n/** Straight-line distance between two atoms, in Ångströms. */\nfunction distance(a: ProteinAtom, b: ProteinAtom): number {\n  return Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z)\n}\n\n// --- Bounds ----------------------------------------------------------------\n\n/**\n * The molecule's centroid and the radius of the sphere about it that holds every\n * atom.\n *\n * The centroid rather than the centre of the bounding box: a structure with one\n * long tail — a coiled-coil, a nucleic acid strand hanging off a complex —\n * has a box whose centre is nowhere near the mass of it, and the camera would\n * frame the empty half.\n *\n * The radius is floored above zero so a single-atom file (or one whose\n * coordinates are all identical) still gives the camera a distance to work from\n * rather than parking it inside the atom.\n */\nfunction measure(atoms: ProteinAtom[]): {\n  center: { x: number; y: number; z: number }\n  radius: number\n} {\n  let sx = 0\n  let sy = 0\n  let sz = 0\n  for (const atom of atoms) {\n    sx += atom.x\n    sy += atom.y\n    sz += atom.z\n  }\n  const center = {\n    x: sx / atoms.length,\n    y: sy / atoms.length,\n    z: sz / atoms.length,\n  }\n\n  let radius = 0\n  for (const atom of atoms) {\n    const d = Math.hypot(\n      atom.x - center.x,\n      atom.y - center.y,\n      atom.z - center.z\n    )\n    if (d > radius) radius = d\n  }\n\n  return { center, radius: Math.max(radius, 1) }\n}\n"]}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@motionscript/molecule",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.0",
+  "type": "module",
+  "description": "Animated molecular structures for Motion Script: cartoon ribbons, sticks and surfaces from a PDB entry.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motionscript-dev/motionscript.git",
+    "directory": "packages/components/molecule"
+  },
+  "homepage": "https://motionscript.dev",
+  "bugs": {
+    "url": "https://github.com/motionscript-dev/motionscript/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "registry.json",
+    "CHANGELOG.md",
+    "!dist/**/*.tsbuildinfo",
+    "!src/**/tests/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.fixtures.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "motion-script",
+    "motion script",
+    "molecule",
+    "animation"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@motionscript/core": "^0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "eslint": "^9.39.4",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.1.5",
+    "@motionscript/core": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node ../../../scripts/build-browser.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --resolve-full-paths -w",
+    "clean": "rimraf --glob dist .turbo *.tsbuildinfo",
+    "test": "vitest --passWithNoTests",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/registry.json

@@ -0,0 +1,22 @@
+{
+  "kit": {
+    "barrel": "src/index.ts",
+    "specifier": "@motionscript/molecule"
+  },
+  "items": [
+    {
+      "name": "protein",
+      "description": "A molecular structure from a PDB entry, as cartoon ribbons or sticks.",
+      "root": "src/protein",
+      "files": [
+        "chemistry.ts",
+        "index.ts",
+        "parse.ts",
+        "protein.ts",
+        "ribbon.ts",
+        "shared.ts",
+        "structure.ts"
+      ]
+    }
+  ]
+}