Molecular Motion

Overview

Molecular Motion is an open-source library for explaining what molecules do in a mechanism. A short YAML or JSON document lists the molecules that take part, their sites, and what happens step by step; the library turns it into an animated SVG figure a reader can play, step through, or jump into at any point.

Interactive pathway figures are usually one-off combinations of SVG markup, animation code and scientific content, which makes them expensive to draw and hard to review or reuse. Here the mechanism is data: it is validated, versioned and reviewed like code, and the engine handles layout, state, animation, playback controls and export.

It is not a 3D structure viewer and not a simulation. It works at the level of a review figure or a lecture: causal, spatial and temporal relationships between molecules.

Tech & Architecture

Three MIT-licensed packages, versioned together and published on npm:

• @molecular-motion/core — framework-agnostic compiler and state engine. It validates a mechanism against a JSON Schema and folds its steps into immutable snapshots, so moving backward, forward or straight to a step always gives the same state. No DOM, no rendering.
• @molecular-motion/svg — renderer that draws a snapshot from reusable primitives: proteins, DNA, RNA, small molecules, complexes, membranes and cell compartments. It runs in the browser and in Node, and exports any step as a standalone SVG or PNG.
• @molecular-motion/react — the interactive player: step timeline, playback controls, actor selection, keyboard navigation and reduced-motion support.

The language covers binding, recruitment, activation, inhibition, phosphorylation and other modifications, cleavage, ligation, synthesis, degradation and translocation. Older documents are migrated automatically when the schema version changes.

Results & Highlights

• Seven example mechanisms: PARP1 single-strand break repair, homologous recombination by SDSA, a double Holliday junction resolved as a crossover, EGFR dimerization, p53–MDM2 feedback, cGAS–STING sensing and gene expression with splicing
• A viewer and a playground where an editable YAML document sits next to the figure it generates
• Used on this site: the homologous recombination mechanism in the HRD wiki article is a Molecular Motion document, and the article’s share card is rendered from one of its steps

Status

Experimental. The schema is not stable before 1.0, and the figures are explanatory models, not clinical decision tools.