MolVis renders molecules, simulation boxes, and trajectories in the browser, with one product surface shared across the web, VS Code, and Jupyter. Its bidirectional RPC layer lets an agent operate the live scene while the user inspects every result, selects the relevant atoms or bonds, and sends that precise visual context back to the agent.

Vision

Molecular visualization tools have long made you choose: a powerful desktop application that is hard to install and impossible to share, or a lightweight web viewer that cannot keep up once your work gets serious. MolVis exists to erase that trade-off — a single rendering stack that runs anywhere a browser does, with no compromise on what you can see or do.

We want looking at a structure to be frictionless. Drag a file onto a page, open it in your editor next to its input deck, or display it inline in a notebook cell — the viewport, the modes, and the shortcuts are identical everywhere, so the muscle memory you build transfers across every context you work in.

And we want visualization to be more than a picture. MolVis treats editing, measurement, pipeline transforms, and analysis as first-class, fully reversible operations on live molecular data — so the viewer becomes a place where you actually do the work, not just admire the result.

Human-in-the-loop agent workflow

MolVis is designed to be the visual boundary between an agent and molecular data:

1. An agent uses JSON-RPC commands to load data, move the camera, change the representation, select atoms, edit the scene, or run pipeline operations.
2. The user reviews the exact result in the shared viewer instead of auditing a textual description of it.
3. The user selects atoms or bonds that need attention. MolVis emits the selection, active frame, and interaction state back to the host.
4. The agent receives a structured subset with get_selected(), acts on the feedback, and presents the next visible result.

RPC requests and responses are structured and snapshots can capture the visible state, making the workflow straightforward for an agent host to record and audit. MolVis provides the observable interaction boundary; durable audit-log storage remains the responsibility of the host application.

See Agent workflows for a complete selection-feedback loop.

Packages

| Package | Role | |---------|------| | @molcrafts/molvis-stage | 3D stage — Babylon.js rendering, commands, modes, pipeline, RPC | | @molcrafts/molvis-sketch | 2D sketch — Canvas structure editor | | @molcrafts/molvis | Umbrella (repo root) — re-exports stage + sketch + plugin SDK | | @molcrafts/molvis-plugin | Plugin authoring SDK (base class, contract, host-aligned UI) | | @molcrafts/molvis-core | Shared molrs gateway + element catalog (transitive; not a product install) | | page | React 19 product UI (ships inside Python / VS Code hosts) | | VS Code extension | Custom editor for molecular formats | | molcrafts-molvis (PyPI) | Python driver over WebSocket |

Install

# both engines (root package)
npm install @molcrafts/molvis

# 3D only
npm install @molcrafts/molvis-stage

# 2D only
npm install @molcrafts/molvis-sketch

Requires Node.js 22+. The Python package (pip install molcrafts-molvis) needs Python 3.12+; the VS Code extension installs from the Marketplace.

Quick start

import { mountMolvis } from "@molcrafts/molvis-stage";
import { loadFileContent } from "@molcrafts/molvis-stage/io";

const container = document.getElementById("viewer");
if (!container) throw new Error("viewer container not found");

const app = mountMolvis(container);
await app.start();

const pdbText = await (await fetch("/structure.pdb")).text();
await loadFileContent(app, pdbText, "structure.pdb");

See the documentation for the web viewer, the VSCode extension, the Python API, and how to extend the engine.

Documentation

• Tutorial — frames, camera, representations, selection, pipeline, trajectories, export
• Agent workflows — RPC control, visual review, selection feedback, and audit records
• Interfaces — Web/TypeScript, Python/Jupyter, and VS Code guides
• Development — embed MolVis and write custom modifiers and commands
• API Reference — TypeScript library and Python package

MolCrafts ecosystem

| Project | Role | |---------|------| | molpy | Python toolkit — shared molecular data model & workflow layer | | molrs | Rust core — molecular data structures & compute kernels (native + WASM) | | molpack | Packmol-grade molecular packing (Rust + Python) | | molvis — this repo | WebGL molecular visualization & editing | | molexp | Workflow & experiment-management platform | | molnex | Molecular machine-learning framework | | molq | Unified job queue — local / SLURM / PBS / LSF | | molcfg | Layered configuration library | | mollog | Structured logging, stdlib-compatible | | molhub | Molecular dataset hub | | molmcp | MCP server for the ecosystem | | molrec | Atomistic record specification |

Contributing

Contributions are welcome — see the development guide.

License

BSD-3-Clause — see LICENSE.