# Molstudio

Molstudio is a browser-based molecular renderer, animator and scene authoring
environment. It combines deposited molecular structures, independent scene
components, ordinary editable animation records, procedural retained-unit
assemblies, custom illustrative Shape Lab assets, cameras, materials, VFX,
audio and rendering.

## Canonical documentation

- https://molstudio.app/docs.html — complete current product manual
- https://molstudio.app/motion-lab.html — animation, interaction and examples
- https://molstudio.app/api/manifest.json — machine-readable capabilities
- https://molstudio.app/api/tools.json — semantic LLM tool definitions
- https://molstudio.app/api/plan-schema.json — molstudio.llm-plan/1 JSON Schema
- https://molstudio.app/api/environment-schema.json — sanitized live-context JSON Schema
- https://molstudio.app/api/environment-example.json — representative sanitized context
- https://molstudio.app/api/examples.json — valid example plans
- https://molstudio.app/api/openapi.json — discovery for the static GET surface
- https://molstudio.app/api/system-prompt.txt — compact planning instructions
- https://molstudio.app/science.html — Molstudio Lab scientific workbench
- https://molstudio.app/lab-docs.html — Molstudio Lab technical reference
- https://molstudio.app/api/lab/manifest.json — Lab automation discovery
- https://molstudio.app/api/lab/tools.json — Lab typed scientific operations
- https://molstudio.app/api/lab/plan-schema.json — molstudio.science-automation-plan/1 schema
- https://molstudio.app/api/lab/examples.json — empty-to-complete scientific plans
- https://molstudio.app/api/lab/system-prompt.txt — Lab planning and evidence rules

## How model control works

Molstudio's planning API remains a set of static discovery documents and does
not mutate an open Studio over HTTP. Live model context is assembled in the
user's browser and is never read from optional cloud-project storage. A model
can work with it in three ways:

1. The user opens AI Director and connects a browser-accessible model endpoint.
2. The user copies a sanitized scene brief to any model and pastes its plan back.
3. An embedding page establishes a user-approved postMessage session with the
   live window.MolstudioLLM bridge.

Every mutating plan is validated, previewed and staged. Model output cannot run
JavaScript and cannot directly access the renderer bridge. In the default
review mode a plan cannot apply without an explicit user confirmation in
Molstudio; the user may opt into an autonomous run loop in which plans execute
as they arrive and every pass returns a molstudio.llm-result/1 payload — the
steps that executed, the steps skipped and why, errors with exact paths, and
the refreshed environment — so the model corrects its own next pass. A run
ends when a pass changes nothing, when an identical failing plan repeats, or
at the visible Stop, and the finished run offers a single Undo. After every
applied plan Molstudio captures one downscaled viewport frame per shot and
attaches the frames to the model's next request as native image input on
Ollama, Anthropic and OpenAI-compatible endpoints; text-only models continue
without them. structure.align superposes one imported actor onto another with
a sequence-guided rigid fit, changing only the moving actor's transform.
structure.import_rcsb accepts assemblyId; each imported component lists its
displayed non-polymer chemistry as exact comp codes with names, and a failed
selection.resolve_chemical reports the candidates it could have matched. A plan may begin with
strict prerequisite tools: structure.import_rcsb, structure.import_file,
structure.import_url, shape.create, asset.remove and project.blank. Molstudio
executes that prerequisite stage separately, publishes a fresh sanitized
environment/revision, and revalidates the remaining scene, style and animation
steps before any of them can run. A later top-level actorId, targetActorId,
subjectActorId, unitActorId, componentId, selectionId or assetId may consume a
published generated id using the exact whole-string grammar
$result.<stepId>.(actorId|componentId|selectionId|assetId|id), replacing the
parenthesized choice with one field name and stepId with an earlier step. The
producer must be an earlier step that publishes ids — an acquisition or
construction prerequisite, or a selection resolver (selection.resolve_sequence
and selection.resolve_chemical persist a named selection and publish its
selectionId; resolver results are substituted while the scene stage executes,
in step order) — and must publish a compatible field; references cannot appear
in prose, URLs, nested records or arbitrary parameters. If the generated field is unavailable or the refreshed scene no
longer validates, no scene step runs and the model replans from the new
snapshot.

structure.import_file opens a visible browser file chooser; file contents stay
on the device. structure.import_url is available only when the current host
installs an HTTPS importer and the source permits browser CORS; the first-party
Studio accepts exact RCSB and AlphaFold coordinate URLs and directs other
providers through the local-file chooser. No import tool
accepts raw PDB/mmCIF text or binary data in a model plan. shape.create accepts
only bounded semantic primitives, swept paths and twisted bundles. asset.remove
and project.blank require both a literal destructive-intent token and a second
visible user confirmation.

## Molstudio Lab automation

Molstudio Lab is a separate scientific workbench. Its browser-resident
MolstudioScienceAutomation controller can begin at a genuinely empty workspace
and execute the same typed operations used by the visible Lab UI: import or
fetch structures, create independent ligands from SMILES or explicit graphs,
manage molecular objects, define selections and representations, run analyses
and compute, attach authorized trajectories/maps, save/export the project and
prepare a same-browser Studio handoff.

Lab plans use schema molstudio.science-automation-plan/1 and pin the live
starting revision. Validation checks the strict operation and argument schemas
plus typed prior-step references. Dry run then verifies that exact live revision
and adapter support without mutating state. workspace.new additionally requires
the literal confirmation NEW_WORKSPACE. A failed or cancelled atomic plan
restores the exact prior Lab state; a successful plan retains the ordinary
granular history entries created by its scientific edits. Generated stable
identifiers can be consumed only as a whole value using
$result.<earlierStep>.<allowlistedField>. Forward, embedded, unknown-field and
unresolved references are rejected.

Receipts are deterministic semantic audit records: they expose plan/argument
digests, status, identifiers, counts, algorithms, evidence and revisions while
excluding source bytes, local paths, credentials and one-time transfer tokens.
They are not standalone full-reproducibility packages. Retain the reviewed plan
and complete Lab project, sources, parameters, results and history for that.

source.import_text is a local Lab host operation for explicitly supplied
PDB/mmCIF/SDF/MOL/MOL2 text. source.import_file, trajectory.import and
map.import consume a ticketId created by a visible, user-authorized local-file
picker rather than file paths or model-provided binary payloads. Archive fetches
identify RCSB, AlphaFold DB or EMDB as the source. The static api/lab paths are
discovery documents, not an unauthenticated HTTP mutation endpoint; execution
occurs only inside the user's open Lab.

Automation does not impose arbitrary scientific atom, frame, result, step or
wall-time budgets and never silently truncates requested work. Parser-security
depth checks and genuine format or semantic constraints fail explicitly.

Lab computed objects are scene objects that are not molecules: scalar fields
sampled on a grid, and geometric shapes such as search boxes, planes, arrows
and dot clouds. A field object carries one required evidence origin, so a
measured density map and a calculated potential share the same contouring,
slicing and display path without ever being mistaken for one another. A
computed field cannot exist without the producer, parameters and coordinate
hash that made it; a deposited field cannot exist without its source. Grid
requests are honoured exactly or refused with the arithmetic. When the
coordinates a field was calculated from change, the field is marked stale and
stops being drawn rather than being recomputed silently. Projects store a
calculated field's recipe rather than its samples unless it is explicitly
pinned. Any mesh can be drawn solid, as wireframe mesh, or as dots.

Lab binding pockets are detected by sampling a carbon probe on a grid and
keeping the connected regions that are both energetically favourable and
enclosed, where enclosure is counted as protein-solvent-protein events along
seven grid directions. Each pocket becomes its own computed field, so it is a
separately coloured, clickable envelope in the viewport with its volume,
enclosure, buriedness and lining residues. Pocket volume is grid-point volume
for that probe, not a solvent-excluded cavity volume; counts and shapes depend
on the energy level and grid spacing, which are retained with every result.
No druggability score, binding affinity or binding-site claim is produced.

Lab surfaces can be coloured by a property: a published residue hydrophobicity
scale, an atom field such as B factor, occupancy or charge, the surface's own
concavity, distance from a point, or a per-residue dataset the user supplies
such as a conservation score. Values reach vertices through the atom each
vertex belongs to rather than by nearest-atom guessing, and a vertex with no
value is drawn in an undefined colour and counted rather than given one. Ramps
are lightness-ordered so they survive greyscale and colour-vision deficiency.
Colour is a display of the values in the result; it is not itself a
measurement.

Lab docking can search inside a box object that is visible in the viewport.
The typed box dimensions can be materialised as a box object, and any box
object in the scene can be chosen as the search region for a pose search.

Lab interface analysis measures what each pair of chains buries: each side's
solvent-accessible area alone and in the complex, the difference being what the
partner covered. Interface area is half the total buried area and both are
reported. Interface residues are listed per side, the buried area is split into
polar and apolar, and cross-interface contacts, geometric hydrogen bonds and
salt bridges are counted at declared cutoffs. Without explicit hydrogens no
angle criterion is applied, so the hydrogen-bond count is an upper bound.
Buried area is not a binding free energy and does not distinguish a biological
assembly from a crystal contact.

Lab interaction typing covers what hydrogen bonds and salt bridges do not:
aromatic stacking typed separately as face-to-face and edge-to-face, cation-pi,
halogen bonds using the carbon-halogen-acceptor angle, amide-aromatic stacking
and water-mediated bridges. Each is a geometric rule at declared cutoffs and
each result carries the distances and angles that qualified it. Aromatic rings
come from standard residue and nucleobase templates; rings found only in a bond
graph are reported as planar rings: interaction typing does not yet consult the
Lab's aromaticity perception, so it does not claim that such a ring is aromatic.
Hydrogens, protonation and lone-pair directions are not used. None of these is
an energy, an occupancy or a strength.

Lab ligand descriptors report constitutional counts, ring and saturation
figures, Ertl topological polar surface area, and Wildman-Crippen logP and molar
refractivity, plus Lipinski, Veber and Egan rule filters. The partition
coefficient applies the published atom-contribution table verbatim and is
checked atom by atom against RDKit over 114 molecules exercising all 72 of its
atom types; it is a model of octanol-water partitioning, never a measurement,
and it describes the neutral species as drawn rather than any particular
protonation state, tautomer or salt form. A logP measured or modelled elsewhere
can be supplied and takes precedence, keeping its own source, with the
calculated value still reported beside it. Rule criteria whose input is missing
report as not evaluated rather than as passed. Polar surface area is refused,
naming the atom, when a polar atom's hydrogen count cannot be determined,
because aromatic nitrogen contributions depend entirely on it. Rule filters are
historical selection heuristics, not predictions.

Lab figure export saves the viewport as an image at a chosen multiple of its
resolution. The frame is rendered immediately before the pixels are read, which is
what makes capture work on a context without a preserved drawing buffer, and text
and line widths are scaled with the image so the exported figure is the one on
screen at a higher resolution rather than a differently proportioned one. The
resolution, megapixel count and the physical width implied at 300 and 600 dpi are
reported, because a journal submission asks for millimetres. PNG, JPEG and WebP are
offered and JPEG states its own cost - lossy artefacts on every bond and label. A
transparent background is refused rather than delivered opaque, because the
viewport is opaque by choice. A request beyond the device's maximum texture size is
refused with the limit rather than silently reduced. Nothing is uploaded; the file
is written by the browser.

Lab chemical superposition finds the largest connected substructure two ligands
share and reports the rigid transform placing one on the other by it, with the
deviation over that scaffold. The match is induced - a bond in one molecule must be
a bond in the other and a non-bond must be a non-bond - so six carbons in a ring
never map onto six in a chain; and it is connected, because a scaffold is one piece
rather than the largest scattering of unrelated fragments. Hydrogens are excluded,
since two analogues rarely share a scaffold's hydrogens. The search is exhaustive
within a step budget and reports whether it finished: exhausted, the result is a
common substructure and is explicitly not claimed to be the largest, because a
lower bound presented as a maximum would let somebody conclude two molecules share
less than they do. A rigid transform needs three matched non-collinear atoms; when
the scaffold cannot supply them the reason is named rather than a rotation returned
that is one of infinitely many. The transform is reported and never applied, so no
coordinate moves until that is done deliberately. A low deviation over a shared
scaffold says the scaffolds can be superposed and says nothing about whether the
two ligands bind the same way.

Lab displacement ellipsoids draw the anisotropic displacement parameters
deposited in ANISOU records as probability surfaces, which show not only how much
an atom moves but in which direction. The reader retains those parameters rather
than discarding them, reporting any record that names a serial no coordinate
record uses. The probability enclosed is computed by inverting the chi-squared
distribution on three degrees of freedom rather than read from a table, so any
probability can be requested and the scale factor applied is the one reported; the
probability is quoted with every result because ellipsoids drawn at 50% and 95%
cannot be compared by eye. An atom whose displacement matrix is not positive
definite describes no ellipsoid, is left without a shape and is counted, because
this is a property of the deposited refinement rather than of the display. No
ellipsoid is ever derived from an isotropic B factor: that is a different
measurement, and drawing it as an ellipsoid would invent the direction the
ellipsoid exists to show. The values are the depositor's refined model including
whatever restraints were applied, not a direct observation of atomic motion.

Lab sequence conservation colours a structure by how much a set of homologous
sequences agree at each of its residues, through the same gradient machinery as B
factor. Agreement is measured per alignment column as identity, Shannon entropy
normalised against the disorder that many observations could show, and BLOSUM62
substitution similarity; gap fraction and observed count are reported per column.
Conservation is a property of the alignment and not of the coordinates, so every
result carries the sequence count and the mean identity between those sequences -
above about 90% mutual identity nearly every column agrees and the figure looks
conserved everywhere regardless of what is constrained. A column with fewer than
two observed residues carries no value at all rather than a high one, and those
residues are left uncoloured and counted. The structure's own chain must appear in
the alignment and is matched on its residues rather than its name; if it is absent,
or its residue count does not match the aligned sequence, nothing is coloured and
the reason is stated. Residue keys come from the canonical polymer topology rather
than from a walk over atoms, so waters and ligands sharing a chain letter cannot
shift every value onto the wrong residue.

Lab representations include nonbonded crosses. Lines draw bonds, so an atom
nothing is bonded to - a water oxygen, a chloride, a metal ion - has no line to
draw and would not appear at all. The nonbonded representation draws a cross at
exactly the atoms nothing is bonded to, and only those, so switching it on reveals
the waters and ions rather than crossing out the structure; where everything is
bonded it draws nothing. Arm length is a layer setting in angstrom and selection
scoping still applies.

Lab viewports can shade the finished frame in screen space: ambient occlusion
darkens crevices where the structure occludes itself, and outlines mark
silhouettes and creases. Both read the depth buffer of the scene they shade, so
neither adds anything the geometry does not already contain. Depth is linearised
before use, so an outline keeps a constant visual weight and an occlusion radius
means angstrom at every distance rather than pixels. Occlusion sampling is a
deterministic golden-angle spiral rather than a noise texture, so the same view
always renders identically. Both are off by default. There is deliberately no
bloom, depth of field, colour grading, vignette or motion blur, and no claim of
ray tracing: those invent appearance, and a test guards against them.

Lab viewports fade colour towards the page with distance, which is on by default
because a structure without it reads flat and gives the eye no way to tell which
of two overlapping features is in front. Strength moves the fade towards the
viewer rather than relocating it, and the interval is derived from the scene
unless given explicitly, so it rescales with the structure. It can be turned off
for a figure that wants flat colour. Clipping and depth cue are both properties of
the view: neither is recorded as a change to the coordinates.

Lab cartoons are swept as any of eight shapes: automatic (width following the
secondary structure), rectangle, arrow, oval, tube, loop, dumbbell, and putty. An
arrow gives every strand a head, not only the strand that ends the chain. A putty
scales its radius by the deposited B factors between a stated pair of radii, and
the mapping is reported as a display scaling of what the depositor wrote rather
than as a measurement of motion; a residue with no B factor is drawn at the mid
radius and counted, and a structure with no B factors at all is refused rather
than drawn at an invented thickness. Choosing a shape rebuilds the cached mesh,
and a shape that cannot be built leaves the one on screen untouched.

Lab labels write text into the viewport, tracking the atoms they name: element,
atom name, residue name, residue number, chain, B factor, occupancy, formal
charge, or text you supply, one label per atom, residue or chain. A residue-level
label sits on a representative atom — Cα for a protein residue, C1' for a
nucleotide — and says which. A label quoting a number shows the value deposited
in the record; an atom carrying no such value is left unlabelled and counted in a
diagnostic rather than labelled with a substitute, and a request to label by a
column the structure does not have is refused outright. Labels that overlap on
screen are thinned nearest-first and the number hidden is reported; they return
as the view turns and nothing is removed from the structure. Labels are a
property of the view and are cleared when new coordinates are loaded, because a
label naming a residue of the previous structure would be a false statement about
this one.

Lab aromaticity is perceived rather than assumed: smallest rings by a
smallest-ring construction, then Hückel 4n+2 over each ring and over fused
perimeters that are aromatic only as a whole. Ring and aromatic-atom assignment
matches RDKit's default model across 96 cases chosen to break it — antiaromatics,
exocyclic carbonyls, charged rings, macrocycles and partly saturated fused
systems. Aromatic bonds a file already declares are believed rather than
re-derived, and every result says which of the two produced it. Hydrogens absent
from a record are added from a declared count, a molfile hydrogen-count field, a
Kekulé valence sum, or the σ positions an aromatic atom holds; an aromatic
nitrogen that could carry a hydrogen or not is settled by its ring's electron
count, and refused outright when the ring does not settle it.

Lab pharmacophores are typed feature points with tolerance radii: donor,
acceptor, hydrophobe, aromatic, positive and negative ionisable, and
halogen-bond donor. A model can be derived from a bound pose by keeping only
the ligand features within a chosen distance of the receptor. Matching is
deterministic greedy nearest-first geometric assignment; one pose feature never
satisfies two model points. Feature direction is not used and nothing is
rotated, translated or conformationally searched to make a model fit. A
satisfied model is not a prediction of activity, affinity or selectivity.

Lab two-dimensional interaction diagrams project the ligand onto its own
principal plane, so the drawing keeps the shape of the observed pose rather
than being re-laid-out from connectivity. Contacting residues are placed in the
direction they occupy relative to the ligand; the ring radius is a drawing
choice and does not encode distance. Residues stepped around the ring to avoid
overlapping are marked as moved, and ligand atoms that coincide in projection
are reported rather than nudged apart. Edge counts are not interaction
strengths, and a diagram describes one pose at one set of coordinates.

Lab nucleic acid geometry classifies base pairs by Leontis-Westhof edge
(Watson-Crick, Hoogsteen or sugar) and cis/trans glycosidic orientation, with
the edge decided by which edge atoms actually hydrogen bond, so a pair on an
unexpected edge is reported as such. Only a canonical base combination on
Watson-Crick edges in cis is called canonical. The glycosidic nitrogen is
excluded from pairing because it carries the sugar. Also reported: base
stacking, alpha to zeta and chi backbone torsions, Altona-Sundaralingam sugar
pucker phase and conformation, and groove widths where a duplex was recognised.
Hydrogen bonds are heavy-atom distances with no angle or protonation criterion.

Lab virtual screening filters a library on descriptors and docks what survives
into a visible search box object. The ranking is the pose-search heuristic
score and orders compounds only against each other within one run; it is not an
affinity and does not compare across receptors, boxes or parameter sets. Each
compound is docked with its own recorded seed so a single row is reproducible.
Compounds removed by a filter are listed with the criterion, compounds that
fail to dock are listed with the error, a library above an explicit maxLigands
limit is refused rather than truncated, and a cancelled run returns nothing
rather than a partial ranking.

Lab normal modes come from elastic network models: a Gaussian network for the
size of each residue's fluctuation and an anisotropic network for its
direction. A mode predicts the shape of a possible collective motion, never its
rate, its energy or whether it occurs, and eigenvalues are in the units of the
chosen spring constant rather than physical frequencies. Zero modes are
reported rather than removed: six for one rigid body, more when the network is
disconnected at the chosen cutoff. Predicted fluctuations compared against
deposited B factors are a check on the model, not a validation of either.
Mode arrows are drawn at a stated display scale because the model has no
amplitude of its own.

The Lab tool surface is six named families — Inspect, Analyse, Maps and
crystallography, Model and ligands, Dynamics and compute, Automate and report.
The tool workspace opens with a search across every tool, indexed from the
live document so tools contributed by any module are found, matching on name,
description, id and family, with a recently-used list when the box is empty. No
capability is listed in two families.

Lab selection measurements are first-class persisted scientific records.
Centroid distance uses the arithmetic centroid of every atom in each of two
named selections. Raw RMSD is unfitted and requires an explicit one-to-one
correspondence by exact source identity (including one matching immutable
source fingerprint) or by deliberately mapped saved-selection order. Stable
endpoint atom IDs, correspondence pairs, units, coordinate revision and frame
are retained; unequal, missing, duplicate or ambiguous identities fail rather
than being dropped, padded or matched heuristically. Scientific Batch accepts
measurement.add and measurement.create with the same semantics and requires
atomic execution for these two selection-measurement kinds.

## Scientific interpretation

Deposited or imported coordinates retain their provenance. Guided motion,
procedural growth, docking placement, authored physical ripples and Shape Lab
geometry are illustrative unless backed by an explicitly imported experimental
or simulation source. Morph interpolation is not a physical pathway. Dock and
Bind do not calculate affinity, free energy or a preferred pose. A model must
not invent exact molecular-surface points: plans that need them hand control to
Molstudio's representation-aware viewport picker.

## Privacy and transport

Sanitized model context excludes raw PDB/mmCIF text, atom coordinates,
trajectories, audio bytes, custom mesh buffers, local file payloads, cloud
project contents and API credentials. If a user connects an external model,
the context shown in AI Director is sent directly from that browser to the
selected endpoint. Cloud authentication and project storage do not proxy model
requests. Browser endpoints must permit the required CORS request; otherwise
use copy/paste mode or the user-approved live bridge.