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

package/src/protein/protein.ts

@@ -0,0 +1,897 @@
+import {
+  command,
+  driveCommand,
+  easeInOut,
+  node,
+  type Command,
+  type CommandArgs,
+  Canvas3D,
+  Geo,
+  Graphics3D,
+  Mat,
+  Scene3D,
+  property,
+  type BufferGeometry3D,
+  type Canvas3DProps,
+  type Color,
+  type NodeConfig,
+  type Transform3D,
+  type Vector3,
+} from "@motionscript/core"
+
+import {
+  lerpColor3D,
+  cameraOrbit,
+  resolveColor3D,
+  snapValue,
+  orbitProps,
+  type OrbitTarget,
+} from "@motionscript/core/component"
+import {
+  atomColors,
+  atomRadius,
+  backboneRuns,
+  DEFAULT_PROTEIN_PALETTE,
+  hexOf,
+  lerpHexColor,
+  stickPlacement,
+  traceColors,
+  type ProteinColorScheme,
+  type ProteinPalette,
+  type ProteinRepresentation,
+} from "./shared"
+import { cartoonGeometry, cartoonSpans } from "./ribbon"
+import {
+  EMPTY_STRUCTURE,
+  type ProteinAtom,
+  type ProteinStructure,
+} from "./structure"
+
+export interface ProteinProps extends Canvas3DProps {
+  /**
+   * The molecule to draw, already parsed.
+   *
+   * A value rather than a source, and that is the whole arrangement: reading a
+   * coordinate file means a network round-trip or a file read, and this node is
+   * constructed inside a synchronous render pass. So the fetching and the
+   * parsing happen *before* the build — see `parseStructure` and the app's
+   * structure store — and what arrives here is finished data. It is the same
+   * bargain a chart makes with its rows.
+   */
+  structure: ProteinStructure
+  /** How the molecule is drawn. See {@link ProteinRepresentation}. */
+  representation: ProteinRepresentation
+  /** What decides an atom's colour. See {@link ProteinColorScheme}. */
+  colorScheme: ProteinColorScheme
+  /** The colour the `uniform` scheme paints, and every scheme's fallback. */
+  color: Color
+  /**
+   * Every colour the *other* schemes paint from — see {@link ProteinPalette},
+   * which is the shape these are read as rather than a prop of its own.
+   *
+   * Thirteen props rather than one palette because a prop is a whole value: a
+   * single one would make a `to` that reddens the helices a statement about the
+   * eight chain colours too, and the ones the author never touched would snap.
+   * Each of these carries over and tweens on its own, like every other colour in
+   * the app.
+   */
+  helixColor: string
+  sheetColor: string
+  coilColor: string
+  /** The two ends of the N→C ramp, swept through HSL between them. */
+  residueStartColor: string
+  residueEndColor: string
+  /** One per chain, cycling past the eighth. */
+  chainColor1: string
+  chainColor2: string
+  chainColor3: string
+  chainColor4: string
+  chainColor5: string
+  chainColor6: string
+  chainColor7: string
+  chainColor8: string
+  /**
+   * Atom size as a fraction of the true van der Waals radius.
+   *
+   * 1 is the space-filling model — atoms at the size they actually are, touching
+   * their neighbours. Ball-and-stick shrinks them further on its own, so this
+   * stays "how big are the atoms" in both rather than meaning something
+   * different in each.
+   */
+  atomScale: number
+  /** Bond stick radius, in Ångströms. */
+  bondRadius: number
+  /** Backbone tube radius, in Ångströms. A ribbon swells past this on a helix. */
+  ribbonRadius: number
+  /** Whether to draw ligands, ions and cofactors — everything that isn't polymer. */
+  ligands: boolean
+  /** Whether to draw crystallographic waters. Off, because there are hundreds. */
+  waters: boolean
+  /** Mesh detail: segments around a sphere or a stick. */
+  quality: number
+  /** Camera orbit about the vertical axis, in **degrees**. Animate this to spin. */
+  orbit: number
+  /** Camera elevation above the horizon, in **degrees**. */
+  elevation: number
+  /**
+   * How far back the camera sits, as a multiple of the molecule's own radius.
+   *
+   * A multiple rather than a distance, because the things this node draws differ
+   * in size by two orders of magnitude — crambin is 12 Å across and a ribosome
+   * is 300 — and a stored distance that framed one would put the other off
+   * screen or inside the camera. As a ratio the same number frames both, and it
+   * goes on meaning the same thing when the structure is swapped.
+   */
+  zoom: number
+  /** Strength of the ambient fill. */
+  ambientIntensity: number
+  /** Colour of the ambient fill. White leaves the molecule's own colours alone. */
+  ambientColor: Color
+  /** Strength of the key light; the rim light is derived from it. */
+  keyIntensity: number
+  /** Colour of the key light, and of the rim derived from it. */
+  keyColor: Color
+}
+
+/** {@link ProteinProps.zoom}, held inside what can actually be framed. */
+const MIN_ZOOM = 0.2
+const MAX_ZOOM = 12
+const DEFAULT_ZOOM = 2.6
+
+/**
+ * How much of its true size an atom is drawn at in ball-and-stick, on top of
+ * whatever {@link ProteinProps.atomScale} says.
+ *
+ * Ball-and-stick is not a smaller space-filling model — it is a different claim
+ * about what matters. Atoms at a quarter of their radius stop touching, which is
+ * what makes room for the bonds that are the whole point of the representation.
+ */
+const BALL_SCALE = 0.28
+
+/**
+ * A molecular structure viewer.
+ *
+ * Extends {@link Canvas3D} — as `Graph3D` does — so this class only has to say
+ * *what* to draw, and the bridge from the 2D scene graph into the 3D renderer is
+ * the base class's business. It overrides `buildScene3D`, the single seam both
+ * the real render and the asset declaration pass go through.
+ *
+ *   <Protein width="fill" height="fill"
+ *     structure={parseStructure(text, "6LU7")}
+ *     representation="ribbon" colorScheme="secondary" />
+ *
+ * **There is no pointer here.** Every other molecular viewer is driven by
+ * dragging the molecule around, and this one cannot be: the studio renders a
+ * timeline, so the camera has to be something a `to` command can tween and a
+ * scrub can reproduce exactly — frame 300 must be identical whether it was
+ * reached by playing forward or by dragging the playhead backwards. So the
+ * camera is three tweenable numbers (`orbit`, `elevation`, `zoom`), and spinning
+ * the molecule is a command rather than a gesture.
+ *
+ * Atoms and bonds are drawn **instanced**: one sphere geometry and one cylinder
+ * geometry, placed thousands of times in a single draw call each. A mesh per
+ * atom would be tens of thousands of draw calls a frame, which no renderer
+ * survives — and the instance lists themselves are cached (see {@link built}),
+ * because they don't change when the camera moves and the camera is what
+ * normally moves.
+ */
+@node({
+  key: "protein",
+  parentKey: "node",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    acceptsChildren: false,
+    defaultWidthMode: "fixed",
+    defaultHeightMode: "fixed",
+  },
+  seed: {
+    width: 720,
+    height: 560,
+  },
+})
+export class Protein extends Canvas3D<ProteinProps> {
+  /**
+   * The molecule.
+   *
+   * Snaps rather than interpolating, and every other non-scalar prop here
+   * interpolates. There is no halfway point between two different molecules —
+   * atom 4,000 of one is not the same atom as atom 4,000 of the other, and
+   * blending their coordinates would produce a cloud that is neither. Swapping
+   * the structure is a change of *subject*, so it lands at the end of a tween
+   * the way a change of text does.
+   */
+  @property({ default: EMPTY_STRUCTURE, tween: snapValue })
+  declare structure: ProteinStructure
+
+  @property({ default: "ribbon", tween: snapValue })
+  declare representation: ProteinRepresentation
+
+  @property({ default: "secondary", tween: snapValue })
+  declare colorScheme: ProteinColorScheme
+
+  @property({ default: "#4f9dff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare color: Color
+
+  /**
+   * The palette, thirteen props of it — see {@link ProteinProps.helixColor} for
+   * why it is thirteen and not one.
+   *
+   * No `mapper`, unlike the three `Color` props around them: these stay hex
+   * strings because a hex string is what an instance tint is handed, and
+   * {@link lerpHexColor} is the tween that goes with that. The defaults are
+   * written out rather than read off {@link DEFAULT_PROTEIN_PALETTE} because a
+   * decorator default has to be a literal the class carries; the two are pinned
+   * against each other by a test.
+   */
+  @property({ default: "#f0605d", tween: lerpHexColor })
+  declare helixColor: string
+
+  @property({ default: "#f5c451", tween: lerpHexColor })
+  declare sheetColor: string
+
+  @property({ default: "#c8ccd4", tween: lerpHexColor })
+  declare coilColor: string
+
+  @property({
+    default: DEFAULT_PROTEIN_PALETTE.residueStart,
+    tween: lerpHexColor,
+  })
+  declare residueStartColor: string
+
+  @property({
+    default: DEFAULT_PROTEIN_PALETTE.residueEnd,
+    tween: lerpHexColor,
+  })
+  declare residueEndColor: string
+
+  @property({ default: "#4f9dff", tween: lerpHexColor })
+  declare chainColor1: string
+
+  @property({ default: "#ff8a3d", tween: lerpHexColor })
+  declare chainColor2: string
+
+  @property({ default: "#4ddb9a", tween: lerpHexColor })
+  declare chainColor3: string
+
+  @property({ default: "#e05fd0", tween: lerpHexColor })
+  declare chainColor4: string
+
+  @property({ default: "#ffd166", tween: lerpHexColor })
+  declare chainColor5: string
+
+  @property({ default: "#8b7bff", tween: lerpHexColor })
+  declare chainColor6: string
+
+  @property({ default: "#ff6b6b", tween: lerpHexColor })
+  declare chainColor7: string
+
+  @property({ default: "#3fd0d6", tween: lerpHexColor })
+  declare chainColor8: string
+
+  @property({ default: 1 }) declare atomScale: number
+  @property({ default: 0.18 }) declare bondRadius: number
+  @property({ default: 0.45 }) declare ribbonRadius: number
+
+  @property({ default: true, tween: snapValue }) declare ligands: boolean
+  @property({ default: false, tween: snapValue }) declare waters: boolean
+
+  /**
+   * Structural, like `Graph3D.segments`: a geometry is immutable, so every
+   * intermediate value of a tween reallocates the sphere and the cylinder. Set
+   * once; the appearance schema marks it non-animatable to say the same thing
+   * from the other side.
+   */
+  @property({ default: 12 }) declare quality: number
+
+  @property({ default: 35 }) declare orbit: number
+  @property({ default: 18 }) declare elevation: number
+  @property({ default: DEFAULT_ZOOM }) declare zoom: number
+
+  /**
+   * The default rig, and only the default rig — the same four controls the 3D
+   * viewport carries, in the same order and with the same defaults, because
+   * "how is this lit" is one question and a molecule is not a special case of
+   * it. Each light is a **strength and a colour**, in that order: how much
+   * light, and what colour it is.
+   *
+   * Both colours default to white rather than to a tint, so a rig nobody has
+   * touched grades nothing. A coloured default would be a look applied to every
+   * structure in every scene by a control the author never opened.
+   */
+  @property({ default: 0.55 }) declare ambientIntensity: number
+
+  @property({ default: "#ffffff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare ambientColor: Color
+
+  @property({ default: 1.6 }) declare keyIntensity: number
+
+  @property({ default: "#ffffff", mapper: resolveColor3D, tween: lerpColor3D })
+  declare keyColor: Color
+
+  constructor(props?: NodeConfig<Protein, ProteinProps>) {
+    super(props as NodeConfig<Canvas3D<ProteinProps>, ProteinProps>)
+  }
+
+  /**
+   * Frame the scene at a spherical camera placement. Every axis is optional,
+   * so "pull back" and "spin round" stay separate intentions — see
+   * {@link OrbitTarget}.
+   */
+  @command({
+    args: [
+      {
+        key: "target", kind: "orbit", properties: {
+          orbit: { kind: "number", step: 1, unit: "°" },
+          elevation: { kind: "number", min: -89, max: 89, step: 1, unit: "°" },
+          zoom: { kind: "number", min: 0.2, max: 24, step: 0.1, unit: "×" },
+        },
+      },
+    ],
+  })
+  orbitTo(args: CommandArgs<{ target: OrbitTarget }> & { duration: number }): Command<ProteinProps> {
+    return this.to({
+      data: orbitProps(args.data?.target ?? {}) as Partial<ProteinProps>,
+      duration: args.duration,
+      easing: args.easing ?? easeInOut(),
+    })
+  }
+
+  /**
+   * Drift the camera around the molecule for the command's duration — a
+   * continuous orbit at `speed` with a lateral `sway` and a `zoom` pulse
+   * (`breathe`), both on a shared `cycle` so they don't beat against each
+   * other. `settle` eases in from wherever the camera already is, so `float`
+   * after an `orbitTo` does not snap.
+   */
+  @command({
+    args: [
+      { key: "speed", kind: "number", default: 36, min: -360, max: 360, step: 1, unit: "°/s" },
+      { key: "elevation", kind: "number", default: 18, min: -89, max: 89, step: 1, unit: "°" },
+      { key: "zoom", kind: "number", default: 2.6, min: 0.2, max: 12, step: 0.1, unit: "×" },
+      { key: "sway", kind: "number", default: 6, min: 0, max: 45, step: 1, unit: "°" },
+      { key: "breathe", kind: "number", default: 0.08, min: 0, max: 0.6, step: 0.01, scale: 100, unit: "%" },
+      { key: "cycle", kind: "number", default: 8, min: 0.5, max: 60, step: 0.5, unit: "s" },
+      { key: "settle", kind: "number", default: 1, min: 0, max: 20, step: 0.1, unit: "s" },
+    ],
+  })
+  float(args: CommandArgs<{
+    speed?: number
+    elevation?: number
+    zoom?: number
+    sway?: number
+    breathe?: number
+    cycle?: number
+    settle?: number
+  }> & { duration?: number }): Command<ProteinProps> {
+    const {
+      speed = 36,
+      elevation = 18,
+      zoom = 2.6,
+      sway = 6,
+      breathe = 0.08,
+      cycle = 8,
+      settle = 1,
+    } = args.data ?? {}
+    const duration = args.duration ?? 8
+    const easing = args.easing ?? easeInOut()
+
+    const fromOrbit = this.orbit
+    const fromElevation = this.elevation
+    const fromZoom = this.zoom
+    const period = Math.max(cycle, 0.0001)
+
+    return driveCommand(duration, (t) => {
+      const seconds = t * duration
+      // Ease from the camera's current placement into the drift over `settle`
+      // seconds. A zero `settle` starts the drift immediately.
+      const blend = settle <= 0 ? 1 : easing(Math.min(1, seconds / settle))
+      const phase = (seconds / period) * Math.PI * 2
+
+      const driftOrbit = fromOrbit + speed * seconds + Math.sin(phase) * sway
+      const driftZoom = zoom * (1 + Math.sin(phase) * breathe)
+
+      this.set({
+        orbit: fromOrbit + (driftOrbit - fromOrbit) * blend,
+        elevation: fromElevation + (elevation - fromElevation) * blend,
+        zoom: fromZoom + (driftZoom - fromZoom) * blend,
+      } as Partial<ProteinProps>)
+    }) as Command<ProteinProps>
+  }
+
+  /**
+   * The thirteen colour props, as the one value the colourers take.
+   *
+   * Rebuilt per call rather than cached: it is thirteen property reads behind
+   * `built()`'s own cache, which is what stops it happening per frame.
+   */
+  private paletteOf(): ProteinPalette {
+    return {
+      helix: this.helixColor,
+      sheet: this.sheetColor,
+      coil: this.coilColor,
+      residueStart: this.residueStartColor,
+      residueEnd: this.residueEndColor,
+      chains: [
+        this.chainColor1,
+        this.chainColor2,
+        this.chainColor3,
+        this.chainColor4,
+        this.chainColor5,
+        this.chainColor6,
+        this.chainColor7,
+        this.chainColor8,
+      ],
+    }
+  }
+
+  // ---- Drawing ------------------------------------------------------------
+
+  protected override buildScene3D(): Scene3D {
+    const scene = new Scene3D()
+    const structure = this.structure
+    // Framed on what is actually **drawn**, not on the whole file. A crystal
+    // structure carries hundreds of ordered waters scattered well beyond the
+    // molecule, and they are hidden by default — framing the sphere that holds
+    // them would park the camera 40% further back than the picture needs, which
+    // reads as a molecule adrift in an empty box.
+    const radius = this.built().radius
+    const distance = radius * clampZoom(this.zoom)
+
+    // The clipping planes are cut to the molecule rather than fixed, because
+    // "far enough away to see all of it" differs a hundredfold between a peptide
+    // and a virus capsid — and a depth buffer stretched over a range it doesn't
+    // need spends its precision on empty space, which shows up as z-fighting
+    // between atoms that are genuinely an Ångström apart.
+    // Kept explicit rather than left to the camera's own derivation: that sizes
+    // the planes to the scene's bounding box, and a molecule's *atoms* are what
+    // need the precision here, not its extent.
+    //
+    // Polar placement is the camera's vocabulary now, so the three props pass
+    // straight through; `cameraOrbit` is the quarter turn between the stored
+    // zero and the camera's.
+    scene.perspective({
+      fov: 45,
+      near: Math.max(0.1, radius * 0.02),
+      far: distance + radius * 4,
+      orbit: cameraOrbit(this.orbit),
+      elevation: this.elevation,
+      distance,
+    })
+
+    // The backdrop is the node's own **Fills** section — a `Canvas3D`
+    // composites its 3D pass over its fill layers, so a paint stack behind a
+    // molecule is not merely possible but strictly better than one colour, and
+    // an empty stack is what transparency already means everywhere else in the
+    // app. There is no 3D background pass to reach for and no clear colour to
+    // set; see `resolveViewport3DFills`, which carries the colour this node
+    // used to hold in its appearance bag across to that stack.
+
+    // A key light, a weaker rim from the opposite side, and enough ambient that
+    // an atom facing away is still an atom rather than a silhouette. Placed
+    // relative to the molecule so the lighting holds at any size — a light's
+    // parameters and its placement are separate arguments, because placement is
+    // a transform rather than a property of the lamp.
+    //
+    // The rim takes the key's colour as well as a fraction of its strength: it
+    // is the key seen from the other side rather than a light of its own, which
+    // is why there are four controls and not six. The same rig, and the same
+    // argument, as the 3D viewport's — see `Canvas3DView.buildScene3D`.
+    scene
+      .light({
+        type: "ambient",
+        intensity: this.ambientIntensity,
+        color: this.ambientColor,
+      })
+      .light(
+        {
+          type: "directional",
+          intensity: this.keyIntensity,
+          color: this.keyColor,
+        },
+        { position: [radius, radius * 2, radius * 2] }
+      )
+      .light(
+        {
+          type: "directional",
+          intensity: this.keyIntensity * 0.4,
+          color: this.keyColor,
+        },
+        { position: [-radius * 2, -radius, -radius * 1.5] }
+      )
+
+    // Everything is drawn inside one group that puts the molecule's centroid on
+    // the origin, so the camera — which always looks at the origin — frames it
+    // wherever the crystallographer's coordinate system happened to put it. PDB
+    // coordinates are in the crystal's frame and routinely sit hundreds of
+    // Ångströms from zero.
+    //
+    // `begin`/`end` is what a `Graphics3D.group` was: a transform pushed over
+    // everything drawn between them. It lives on the scene now rather than on
+    // the graphics, because hierarchy is a property of the scene.
+    const g3 = new Graphics3D()
+    this.addMolecule(g3)
+
+    const { center } = structure
+    scene.begin({
+      id: "molecule",
+      transform: { position: [-center.x, -center.y, -center.z] },
+    })
+    scene.draw(g3)
+    scene.end()
+
+    return scene
+  }
+
+  /** The molecule itself, in whichever representation is showing. */
+  private addMolecule(g3: Graphics3D): void {
+    const built = this.built()
+
+    this.addSpheres(g3, built.spheres, built.sphereTints, "atoms")
+    this.addSticks(g3, built.sticks, built.stickTints, "bonds")
+
+    for (const run of built.runs) {
+      g3.mesh(
+        Geo.tube({
+          points: run.points,
+          radius: run.radius,
+          // `[along the curve, around it]`. Segments along the curve are
+          // proportional to the run's own length, so the sweep follows it rather
+          // than cutting corners across a tight turn — and a short run doesn't
+          // pay for a long one's tessellation.
+          segments: [Math.max(6, run.points.length * 4), this.stickQuality()],
+        }),
+        Mat.standard({ color: run.color, roughness: 0.45, metalness: 0.05 })
+      )
+    }
+
+    for (const ribbon of built.ribbons) {
+      g3.mesh(
+        ribbon,
+        // `vertexColors`, where every other material here takes a `color`. A
+        // cartoon span is one mesh covering many residues and the colouring is
+        // per residue, so the colour varies *within* the primitive — which is
+        // the one thing a material's uniform colour cannot express. Safe in a
+        // way it would not be on the instanced spheres (see {@link addSpheres}):
+        // this geometry genuinely carries a `color` attribute.
+        Mat.standard({
+          vertexColors: true,
+          roughness: 0.45,
+          metalness: 0.05,
+        })
+      )
+    }
+  }
+
+  /** One instanced sphere op, skipped entirely when there is nothing in it. */
+  private addSpheres(
+    g3: Graphics3D,
+    placements: Transform3D[],
+    tints: string[],
+    key: string
+  ): void {
+    if (placements.length === 0) return
+    const quality = this.sphereQuality()
+    g3.instances(
+      // A unit sphere, sized per instance. One geometry for the whole molecule:
+      // the renderer dedupes by identity and uploads it once, where a radius
+      // baked into the geometry would mean one upload per element.
+      Geo.sphere({
+        radius: 1,
+        // `[longitude, latitude]` — half as many bands as meridians, which is
+        // what a sphere wants and what three's own defaults do.
+        segments: [quality, Math.max(4, Math.round(quality / 2))],
+      }),
+      // No `vertexColors` here, and that is the whole trick rather than an
+      // omission. An instance's tint arrives as its own attribute and the
+      // renderer samples it whenever one is present; asking for *vertex* colours
+      // as well makes the shader read a per-vertex `color` the geometry doesn't
+      // have, which supplies zeroes — and the molecule renders solid black.
+      Mat.standard({ roughness: 0.35, metalness: 0.05 }),
+      placements,
+      { colors: tints, transform: { key } }
+    )
+  }
+
+  /** One instanced cylinder op. */
+  private addSticks(
+    g3: Graphics3D,
+    placements: Transform3D[],
+    tints: string[],
+    key: string
+  ): void {
+    if (placements.length === 0) return
+    g3.instances(
+      // A unit cylinder — one tall, centred on the origin, running along +Y —
+      // which `stickPlacement` moves, turns and stretches onto each bond.
+      Geo.cylinder({
+        radius: 1,
+        height: 1,
+        segments: this.stickQuality(),
+        // The ends are inside the atoms they join, so nothing can see them.
+        capped: false,
+      }),
+      // Bare of `vertexColors` for the reason the spheres are — see above.
+      Mat.standard({ roughness: 0.4, metalness: 0.05 }),
+      placements,
+      { colors: tints, transform: { key } }
+    )
+  }
+
+  // ---- What gets drawn ----------------------------------------------------
+
+  /**
+   * Everything the builder needs, cached against the inputs that decide it.
+   *
+   * This is the node's one piece of memoisation and it earns its keep. The
+   * builder runs every frame; between two frames the thing that has normally
+   * changed is the camera; and none of what is cached here depends on the
+   * camera. Without it, orbiting a 20,000-atom structure would rebuild a
+   * 20,000-entry placement list and a 40,000-entry stick list sixty times a
+   * second — for a picture whose atoms have not moved.
+   *
+   * The structure is compared by **identity** rather than by contents: it is a
+   * parsed value produced once, upstream, so a different object genuinely means
+   * a different molecule.
+   */
+  private cache: {
+    key: string
+    structure: ProteinStructure
+    built: Built
+  } | null = null
+
+  private built(): Built {
+    const structure = this.structure
+    const key = [
+      this.representation,
+      this.colorScheme,
+      hexOf(this.color),
+      // The palette decides every colour the scheme paints, so a change to it
+      // changes the tint arrays this cache is holding — exactly as `color` does.
+      // Missing it meant editing a chain colour repainted nothing until
+      // something else in this key happened to move.
+      paletteKey(this.paletteOf()),
+      this.ligands,
+      this.waters,
+      this.atomScale,
+      this.bondRadius,
+      this.ribbonRadius,
+      // In the key now, where it never used to be: the cartoon's curve is
+      // subdivided against the mesh detail (see `subdivisionsFor`), so a change
+      // to it changes the geometry this cache is holding. The atoms never
+      // needed it — `quality` reaches their spheres as a `segments` count the
+      // renderer reads off the descriptor, not as anything built here.
+      this.quality,
+    ].join("|")
+
+    const cached = this.cache
+    if (cached && cached.structure === structure && cached.key === key) {
+      return cached.built
+    }
+
+    const built = this.build(structure)
+    this.cache = { key, structure, built }
+    return built
+  }
+
+  /** Builds the placement lists for the current representation. */
+  private build(structure: ProteinStructure): Built {
+    const palette = this.paletteOf()
+    const colors = atomColors(
+      structure,
+      this.colorScheme,
+      hexOf(this.color),
+      palette
+    )
+    const showing = structure.atoms.map((atom) => this.isShowing(atom))
+    const representation = this.representation
+    const spaceFilling = representation === "spacefill"
+    const atomic = spaceFilling || representation === "ballAndStick"
+
+    // On a backbone or a ribbon the polymer is the curve, so only what *isn't*
+    // polymer keeps its atoms — an inhibitor sitting in an active site is
+    // usually the entire subject of the picture, and a bare backbone doesn't
+    // show it. On the atomic representations everything showing is drawn.
+    const drawAtom = (index: number): boolean => {
+      if (!showing[index]) return false
+      if (atomic) return true
+      const kind = structure.atoms[index]!.kind
+      return kind !== "amino" && kind !== "nucleic"
+    }
+
+    const built: Built = {
+      spheres: [],
+      sphereTints: [],
+      sticks: [],
+      stickTints: [],
+      runs: [],
+      ribbons: [],
+      radius: structure.radius,
+    }
+
+    const scale = this.atomScale * (spaceFilling ? 1 : BALL_SCALE)
+    for (let i = 0; i < structure.atoms.length; i++) {
+      if (!drawAtom(i)) continue
+      const atom = structure.atoms[i]!
+      built.spheres.push({
+        position: [atom.x, atom.y, atom.z],
+        scale: atomRadius(atom, scale),
+      })
+      built.sphereTints.push(colors[i]!)
+    }
+
+    // A space-filling model has no visible bonds — the atoms are at their true
+    // radii and already overlapping — so the sticks are simply not built.
+    if (!spaceFilling) {
+      for (const bond of structure.bonds) {
+        if (!drawAtom(bond.a) || !drawAtom(bond.b)) continue
+        const a = structure.atoms[bond.a]!
+        const b = structure.atoms[bond.b]!
+        // Two half-sticks rather than one, each in its own atom's colour: a
+        // single stick has to be *some* colour, and whichever atom's it takes,
+        // the far end reads as belonging to the wrong one. Splitting at the
+        // midpoint is what ball-and-stick models have done since they were brass.
+        const mid: Vector3 = {
+          x: (a.x + b.x) / 2,
+          y: (a.y + b.y) / 2,
+          z: (a.z + b.z) / 2,
+        }
+        built.sticks.push(stickPlacement(a, mid, this.bondRadius))
+        built.stickTints.push(colors[bond.a]!)
+        built.sticks.push(stickPlacement(mid, b, this.bondRadius))
+        built.stickTints.push(colors[bond.b]!)
+      }
+    }
+
+    if (!atomic) this.addRuns(built, structure)
+    built.radius = framingRadius(built, structure)
+    return built
+  }
+
+  /**
+   * The polymer, as whichever sweep its representation calls for.
+   *
+   * Two genuinely different builds rather than one with a radius switch, and
+   * the split is the same one the representations themselves are: `backbone`
+   * asks *where does the chain go*, which an even round tube answers exactly
+   * and completely; `ribbon` asks *what is it folded into*, which is the
+   * cartoon convention and needs a cross-section with a width, a thickness and
+   * a side (see `ribbon.ts`).
+   */
+  private addRuns(built: Built, structure: ProteinStructure): void {
+    const cartoon = this.representation === "ribbon"
+    const uniform = hexOf(this.color)
+    const palette = this.paletteOf()
+
+    structure.chains.forEach((chain, index) => {
+      const colors = traceColors(
+        structure,
+        chain,
+        this.colorScheme,
+        uniform,
+        palette
+      )
+
+      if (cartoon) {
+        for (const span of cartoonSpans(chain, colors)) {
+          const geometry = cartoonGeometry(span, {
+            radius: this.ribbonRadius,
+            quality: this.quality,
+          })
+          if (geometry) built.ribbons.push(geometry)
+        }
+        return
+      }
+
+      backboneRuns(chain, colors, false).forEach((run, runIndex) => {
+        built.runs.push({
+          points: run.points,
+          color: run.color,
+          radius: this.ribbonRadius,
+          // Keyed by its place in the chain rather than by its slot in the op
+          // list, so adding a run doesn't renumber every later one and force the
+          // tail of the renderer's cache to rebuild.
+          key: `chain:${index}:${runIndex}`,
+        })
+      })
+    })
+  }
+
+  /** Whether an atom passes the ligand and water filters. */
+  private isShowing(atom: ProteinAtom): boolean {
+    if (atom.kind === "water") return this.waters
+    if (atom.kind === "amino" || atom.kind === "nucleic") return true
+    return this.ligands
+  }
+
+  /** Segments around a sphere's equator. */
+  private sphereQuality(): number {
+    return Math.max(4, Math.round(this.quality))
+  }
+
+  /** Segments around a stick or a tube — half a sphere's, since it has no poles. */
+  private stickQuality(): number {
+    return Math.max(3, Math.round(this.quality / 2))
+  }
+}
+
+/** A palette flattened for {@link Protein.built}'s cache key. */
+function paletteKey(palette: ProteinPalette): string {
+  return [
+    palette.helix,
+    palette.sheet,
+    palette.coil,
+    palette.residueStart,
+    palette.residueEnd,
+    ...palette.chains,
+  ].join(",")
+}
+
+/** One swept stretch of backbone. */
+interface BuiltRun {
+  points: Vector3[]
+  color: string
+  radius: number
+  key: string
+}
+
+/** Everything the per-frame builder emits, built once per change and cached. */
+interface Built {
+  spheres: Transform3D[]
+  sphereTints: string[]
+  sticks: Transform3D[]
+  stickTints: string[]
+  /** Even round tubes — the `backbone` representation. */
+  runs: BuiltRun[]
+  /** Cartoon meshes, one per secondary-structure span — the `ribbon` one. */
+  ribbons: BufferGeometry3D[]
+  /** How far the drawn parts reach from the molecule's centroid, in Ångströms. */
+  radius: number
+}
+
+/**
+ * The radius the camera frames: the furthest *drawn* thing from the centroid.
+ *
+ * Measured over the placements rather than over the atom list, so it covers
+ * exactly what will appear — the backbone runs when a ribbon is showing, the
+ * atoms when it isn't, and neither the hidden waters nor the ligands somebody
+ * switched off.
+ *
+ * Falls back to the whole structure's radius when nothing is drawn at all, so a
+ * node whose filters have hidden everything still has a camera distance rather
+ * than a zero.
+ */
+function framingRadius(built: Built, structure: ProteinStructure): number {
+  const { center } = structure
+  let furthest = 0
+
+  const reach = (x: number, y: number, z: number) => {
+    const d = Math.hypot(x - center.x, y - center.y, z - center.z)
+    if (d > furthest) furthest = d
+  }
+
+  for (const sphere of built.spheres) {
+    const [x, y, z] = sphere.position as [number, number, number]
+    reach(x, y, z)
+  }
+  for (const run of built.runs) {
+    for (const point of run.points) reach(point.x, point.y, point.z)
+  }
+  // The cartoon's vertices rather than its residues: it is already a finished
+  // buffer by the time this runs, and reading it is both exact — a strand's
+  // arrowhead reaches wider than the α-carbons it was built from — and cheaper
+  // than keeping a parallel copy of the curve alive to measure instead.
+  for (const ribbon of built.ribbons) {
+    const position = ribbon.position
+    for (let i = 0; i + 2 < position.length; i += 3) {
+      reach(position[i]!, position[i + 1]!, position[i + 2]!)
+    }
+  }
+
+  return furthest > 0 ? furthest : structure.radius
+}
+
+function clampZoom(zoom: number): number {
+  if (!Number.isFinite(zoom)) return DEFAULT_ZOOM
+  return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom))
+}