experimental sequence theme

* add intro scene

* fixes

* add author name

.eslintignore

@@ -1,4 +0,0 @@
-node_modules/*
-build/*
-docs/site/*
-lib/*

.eslintrc.json

@@ -1,122 +0,0 @@
-{
-    "env": {
-        "browser": true,
-        "node": true
-    },
-    "parserOptions": {
-        "ecmaVersion": 2018,
-        "sourceType": "module",
-        "ecmaFeatures": {
-            "impliedStrict": true
-        }
-    },
-    "rules": {
-        "indent": "off",
-        "arrow-parens": [
-            "off",
-            "as-needed"
-        ],
-        "brace-style": "off",
-        "comma-spacing": "off",
-        "space-infix-ops": "off",
-        "comma-dangle": "off",
-        "eqeqeq": [
-            "error",
-            "smart"
-        ],
-        "import/order": "off",
-        "no-eval": "warn",
-        "no-new-wrappers": "warn",
-        "no-trailing-spaces": "error",
-        "no-unsafe-finally": "warn",
-        "no-var": "error",
-        "spaced-comment": "error",
-        "semi": "warn",
-        "no-restricted-syntax": [
-            "error",
-            {
-                "selector": "ExportDefaultDeclaration",
-                "message": "Default exports are not allowed"
-            }
-        ],
-        "no-throw-literal": "error",
-        "key-spacing": "error",
-        "object-curly-spacing": ["error", "always"],
-        "array-bracket-spacing": "error",
-        "space-in-parens": "error",
-        "computed-property-spacing": "error",
-        "prefer-const": ["error", {
-            "destructuring": "all",
-            "ignoreReadBeforeAssign": false
-        }],
-        "space-before-function-paren": "off",
-        "func-call-spacing": "off",
-        "no-multi-spaces": "error",
-        "block-spacing": "error",
-        "keyword-spacing": "off",
-        "space-before-blocks": "error",
-        "semi-spacing": "error",
-        "no-constant-binary-expression": "error"
-    },
-    "overrides": [
-        {
-            "files": ["**/*.ts", "**/*.tsx"],
-            "parser": "@typescript-eslint/parser",
-            "parserOptions": {
-                "project": ["tsconfig.json", "tsconfig.commonjs.json"],
-                "sourceType": "module"
-            },
-            "plugins": [
-                "@typescript-eslint"
-            ],
-            "rules": {
-                "@typescript-eslint/ban-types": "off",
-                "@typescript-eslint/class-name-casing": "off",
-                "@typescript-eslint/indent": [
-                    "error",
-                    4
-                ],
-                "@typescript-eslint/member-delimiter-style": [
-                    "off",
-                    {
-                        "multiline": {
-                            "delimiter": "none",
-                            "requireLast": true
-                        },
-                        "singleline": {
-                            "delimiter": "semi",
-                            "requireLast": false
-                        }
-                    }
-                ],
-                "@typescript-eslint/prefer-namespace-keyword": "warn",
-                "@typescript-eslint/quotes": [
-                    "error",
-                    "single",
-                    {
-                        "avoidEscape": true,
-                        "allowTemplateLiterals": true
-                    }
-                ],
-                "@typescript-eslint/semi": [
-                    "off",
-                    null
-                ],
-                "@typescript-eslint/type-annotation-spacing": "error",
-                "@typescript-eslint/brace-style": [
-                    "error",
-                    "1tbs", { "allowSingleLine": true }
-                ],
-                "@typescript-eslint/comma-spacing": "error",
-                "@typescript-eslint/space-infix-ops": "error",
-                "@typescript-eslint/space-before-function-paren": ["error", {
-                    "anonymous": "always",
-                    "named": "never",
-                    "asyncArrow": "always"
-                }],
-                "@typescript-eslint/func-call-spacing": ["error"],
-                "@typescript-eslint/keyword-spacing": ["error"]
-            }
-        }
-    ]
-}

.gitignore

@@ -1,4 +1,5 @@
 build/
+deploy/
 lib/
 docs/site/
 
@@ -13,3 +14,6 @@ tsconfig.commonjs.tsbuildinfo
 
 .DS_Store
 tmp/
+
+dev.pem
+dev-key.pem

.vscode/settings.json

@@ -6,9 +6,4 @@
         "*.vert.ts": "glsl",
         "*.gql.ts": "graphql"
     },
-    "eslint.options": {
-        "overrideConfig": {
-            "ignorePatterns": ["webpack.config.js", "scripts/*"],
-        },
-    }
 }

CHANGELOG.md

@@ -4,7 +4,119 @@ All notable changes to this project will be documented in this file, following t
 Note that since we don't clearly distinguish between a public and private interfaces there will be changes in non-major versions that are potentially breaking. If we make breaking changes to less used interfaces we will highlight it in here.
 
 ## [Unreleased]
+- [Breaking] Renamed some color schemes ('inferno' -> 'inferno-no-black', 'magma' -> 'magma-no-black', 'turbo' -> 'turbo-no-black', 'rainbow' -> 'simple-rainbow')
+- [Breaking] `Box3D.nearestIntersectionWithRay` -> `Ray3D.intersectBox3D`
+- [Breaking] `Plane3D.distanceToSpher3D` -> `distanceToSphere3D` (fix spelling)
+- [Breaking] fix typo `MarchinCubes` -> `MarchingCubes`
+- [Breaking] `PluginContext.initViewer/initContainer/mount` are now async and have been renamed to include `Async` postfix
+- [Breaking] Add `Volume.instances` support and a `VolumeInstances` transform to dynamically assign it
+  - This change is breaking because all volume objects require the `instances` field now.
+- [Breaking] `Canvas3D.identify` now expects `Vec2` or `Ray3D`
+- [Breaking] `TrackballControlsParams.animate.spin.speed` now means "Number of rotations per second" instead of "radians per second"
+- [Breaking] `PluginStateSnapshotManager.play` now accepts an options object instead of a single boolean value
+- Update production build to use `esbuild`
+- Emit explicit paths in `import`s in `lib/`
+- Fix outlines on opaque elements using illumination mode
+- Change `Representation.Empty` to a lazy property to avoid issue with some bundlers
+- MolViewSpec extension:
+  - Generic color schemes (`palette` parameter for color_from_* nodes)
+  - Annotation field remapping (`field_remapping` parameter for color_from_* nodes)
+  - `representation` node: support custom property `molstar_representation_params`
+  - Add `backbone` and `line` representation types
+  - `primitives` node: support custom property `molstar_mesh/label/line_params`
+  - `canvas` node: support custom property `molstar_postprocessing` with the ability to customize outline, depth of field, bloom, shadow, occlusion (SSAO), and fog
+  - `clip` node support for structure and volume representations
+  - `grid_slice` representation support for volumes
+  - Support tethers and background for primitive labels
+  - Support `snapshot_key` parameter on primitives that enables transition between states via clicking on 3D objects
+  - Inline selectors and MVS annotations support `instance_id`
+  - Support `matrix` on transform params
+  - Support `surface_type` (`molecular` / `gaussian`) on for `surface` representation nodes
+  - Add `instance` node type
+  - Add `transform.rotation_center` property that enables rotating an object around its centroid or a specific point
+  - Support transforming and instancing of structures, components, and volumes
+  - Use params hash for node version for more performant tree diffs
+  - Add `Snapshot.animation` support that enables animating almost every property in a given tree
+  - Add `createMVSX` helper function
+  - Support Mol* trackball animation via `animation.custom.molstar_trackball`
+  - MVSX - use Murmur hash instead of FNV in archive URI
+  - Support additional file formats (pdbqt, gro, xyz, mol, sdf, mol2, xtc, lammpstrj)
+  - Support loading trajectory coordinates from separate nodes
+  - Trigger markdown commands from primitives using `molstar_markdown_commands` custom extensions
+  - Support `molstar_on_load_markdown_commands` custom state on the `root` node
+- Added new color schemes, synchronized with D3.js ('inferno', 'magma', 'turbo', 'rainbow', 'sinebow', 'warm', 'cool', 'cubehelix-default', 'category-10', 'observable-10', 'tableau-10')
+- Snapshot Markdown improvements
+  - Add `MarkdownExtensionManager` (`PluginContext.managers.markdownExtensions`)
+  - Support custom markdown commands to control the plugin via the `[link](!command)` pattern
+  - Support rendering custom elements via the `![alt](!parameters)` pattern
+  - Support tables
+  - Support loading images and audio from MVSX files
+  - Indicate external links with ⤴
+  - Audio support
+  - Add `PluginState.Snapshot.onLoadMarkdownCommands`
+- Avoid calculating rings for coarse-grained structures
+- Fix isosurface compute shader normals when transformation matrix is applied to volume
+- Symmetry operator naming for spacegroup symmetry - parenthesize multi-character indices (1_111-1 -> 1_(11)1(-1))
+- Add `SymmetryOperator.instanceId` that corresponds to a canonical operator name (e.g. ASM-1, ASM-X0-1 for assemblies, 1_555, 1_(11)1(-1) for crystals)
+- Mol2 Reader
+    - Fix column count parsing
+    - Add support for substructure
+- Fix shader error when clipping flags are set without clip objects present
+- Fix wrong group count calculation on geometry update (#1562)
+- Fix wrong instance index in `calcMeshColorSmoothing`
+- Add `Ray3D` object and helpers
+- Volume slice representation: add `relativeX/Y/Z` options for dimension
+- Add `StructureInstances` transform
+- `mvs-stories` app
+  - Add `story-id` URL arg support
+  - Add `story-session-url` URL arg support
+  - Add "Download MVS State" link
+  - Add "Open in Mol*" link
+  - Add "Edit in MolViewStories" link for story states
+- Add ray-based picking
+    - Render narrow view of scene scene from ray origin & direction to a few pixel sized viewport
+    - Cast ray on every input as opposed to the standard "whole screen" picking
+    - Can be enabled with new `Canvas3dInteractionHelperParams.convertCoordsToRay` param
+    - Allows to have input methods that are 3D pointers in the scene
+    - Add `ray: Ray3D` property to `DragInput`, `ClickInput`, and `MoveInput`
+- Add async, non-blocking picking (only WebGL2)
+    - Refactor `Canvas3dInteractionHelper` internals to use async picking for move events
+- Add `enable` param for post-processing effects. If false, no effects are applied.
+- Dot volume representation improvements
+    - Add positional perturbation to avoid camera artifacts
+    - Fix handling of negative isoValues by considering only volume cells with values lower than isoValue (#1559)
+    - Fix volume-value size theme
+- Change the parsing of residue names in PDB files from 3-letter to 4-letter.
+- Support versioning transform using a hash function in `mol-state`
+- Support for "state snapshot transitions"
+    - Add `PluginState.Snapshot.transition` that enables associating a state snapshot with a list states that can be animated
+    - Add `AnimateStateSnapshotTransition` animation
+    - Update the snapshots UI to support this feature
+- Use "proper time" in the animation loop to prevent animation skips during blocking operations (e.g., shader complication)
+- Add `Hsl` and (normalized) `Rgb` color spaces
+- Add `Color.interpolateHsl`
+- Add `rotationCenter` property to `TransformParam`
+- Add Monolayer transparency (exploiting dpoit).
+- Add plugin config item ShowReset (shows/hides "Reset Zoom" button)
+- Fix transform params not being normalized when used together with param hash version
+- Replace `immer` with `mutative`
 
+## [v4.18.0] - 2025-06-08
+- MolViewSpec extension:
+  - Support for label_comp_id and auth_comp_id in annotations
+  - Geometric primitives - do not render if position refers to empty substructure
+  - Primitive arrow - nicer default cap size (relative to tube_radius)
+  - Primitive angle_measurement - added vector_radius param
+  - Fix MVSX file assets being disposed in multi-snapshot states
+- Add `mol-utils/camera.ts` with `fovAdjustedPosition` and `fovNormalizedCameraPosition`
+- Show FOV normalized position in `CameraInfo` UI and use it in "Copy MVS State"
+- Support static resources in `AssetManager`
+- General:
+  - Use `isolatedModules` tsconfig flag
+  - Fix TurboPack build when using ES6 modules
+- Support `pickingAlphaThreshold` when `xrayShaded` is enabled
+- Support sampling from arbitrary planes for structure plane and volume slice representations
+- Refactor SCSS to not use `@import` (fixes deprecation warnings)
 
 ## [v4.17.0] - 2025-05-22
 - Remove `xhr2` dependency for NodeJS, use `fetch`

README.md

@@ -190,9 +190,14 @@ To get syntax highlighting for shader files add the following to Visual Code's s
     npm publish
 
 ## Deploy
+To prepare apps and demos for https://molstar.org deploy, run:
+
     npm run test
-    npm run build
-    node ./scripts/deploy.js # currently updates the viewer on molstar.org/viewer
+    npm run deploy:local
+
+To commit these changes remotely to the `molstar/molstar.github.io` repo:
+
+    npm run deploy:remote
 
 ## Contributing
 Just open an issue or make a pull request. All contributions are welcome.

docs/docs/data-access-tools/volume-server/index.md

@@ -24,7 +24,7 @@ npm install
 Afterwards, build the project source:
 
 ```
-npm run build-tsc
+npm run build:lib
 ```
 
 and run the server by 

docs/docs/extensions/tunnels.md

@@ -94,7 +94,7 @@ The extension uses several transformations to process and visualize tunnel data:
 To help users understand how to use these transformations in practice, include detailed examples:
 
 ### Visualizing Multiple Tunnels
-This example ([runVisualizeTunnels](../../../src/extensions/sb-ncbr/tunnels/examples.ts#L19)) demonstrates how to visualize multiple tunnels from a fetched dataset.
+This example (see `src/extensions/sb-ncbr/tunnels/examples.ts#L19`) demonstrates how to visualize multiple tunnels from a fetched dataset.
 ```typescript
 update.toRoot()
         .apply(TunnelsFromRawData, { data: tunnels })
@@ -104,7 +104,7 @@ update.toRoot()
 ```
 
 ### Visualizing a Single Tunnel
-This example ([runVisualizeTunnel](../../../src/extensions/sb-ncbr/tunnels/examples.ts#L46)) shows how to visualize a single tunnel.
+This example (see `src/extensions/sb-ncbr/tunnels/examples.ts#L46`) shows how to visualize a single tunnel.
 ```typescript
 update.toRoot()
         .apply(TunnelFromRawData, {

docs/docs/plugin/custom-library.md

@@ -141,7 +141,7 @@ export async function loadStructure(plugin: PluginUIContext, url: string, option
 ```
 - Create `src/style.scss`:
 ```scss
-@import '../node_modules/molstar/lib/mol-plugin-ui/skin/light.scss';
+@use '../node_modules/molstar/lib/mol-plugin-ui/skin/light.scss';
 ```
 - Create `build/ui.html`:
 ```html

docs/docs/plugin/instance.md

@@ -247,7 +247,7 @@ async function init() {
     const canvas = <HTMLCanvasElement> document.getElementById('molstar-canvas');
     const parent = <HTMLDivElement> document.getElementById('molstar-parent');
 
-    if (!plugin.initViewer(canvas, parent)) {
+    if (!(await plugin.initViewer(canvas, parent))) {
         console.error('Failed to init Mol*');
         return;
     }

docs/docs/plugin/managers/markdown-extensions.md

@@ -0,0 +1,107 @@
+# Markdown Extension Manager
+
+The `markdownExtensions` manager in `PluginContext.manager` allows customizing
+the `Markdown` React component to enable executing commands and rendering custom content.
+
+The main use case of this is enriching [MolViewSpec](`https://molstar.org/mol-view-spec`) support.
+
+## API
+
+- `PluginContext.manager.markdownExtensions.register*` functions can be used to register extensions and state/data resolvers to make the the manager work with plugin extension
+- `PluginContext.manager.markdownExtensions.remove*` can be used to dynamically remove the above
+
+## Commands
+
+Extends Markdown Hyperlink syntax to support expressions of the form `[title](!c1=v1&c2=v2&...)` into an executable command. The command can be executed either on click, mouse enter, or mouse leave.
+
+Generally, the command should be URL encoded, e.g., `a b` => `a%20b` (in JS, `encodeURIComponent`, in Python `urllib.parse.quote_plus/urlencode`).
+
+### Built-in Commands
+
+- `center-camera` - Centers the camera
+- `apply-snapshot=key` - Loads snapshots with the provided key
+- `next-snapshot[=-1|1]` - Loads next/previous snapshot, the direction is optional and default to `1`
+- `play-snapshots` - Starts playback of state snapshots
+- `play-transition` - Plays an animation associated with the given snapshot
+- `stop-animation` - Stops currently playing animation
+- `focus-refs=ref1,ref2,...` - On click, focuses nodes with the provided refs
+- `highlight-refs=ref1,ref2,...` - On mouse over, highlights the provided refs
+- `query=...&lang=...&action=highlight,focus&focus-radius=...`
+    - `query` is an expression (e.g., `resn HEM` when using PyMol syntax)
+    - (optional) `lang` is one of `mol-script` (default), `pymol`, `vmd`, `jmol`
+    - (optional) `action` is an array of `highlight` (default), `focus` (multiple actions can be specified)
+    - (optional) `focus-radius` is extra distance applied when focusing the selection (default is `3`)
+    - Example: `[HEM](!query=resn%20HEM%26lang=pymol&action=highlight,focus)` highlights or focuses the HEM residue (the query must be URL encoded because it contains spaces and possibly other special characters)
+- `play-audio=src`, `toggle-audio[=src]`, `stop-audio`, `pause-audio`, `dispose-audio` - Audio playback support
+
+## Custom Content
+
+Extends Markdown Image syntax to support expressions of the form `![alt](!c1=v1&c2=v2&...)` to render custom elements instead.
+
+### Built-in Custom Content
+- `color-swatch=color` - Renders a box with the provided color
+-  Color palettes:
+    - `color-palette-name=name` - Renders a gradient with the provided named color palette (see `mol-util/color/lists.ts` for supported color schemes)
+    - `color-palette-colors=color1,color2` - Renders a gradient with the provided colors
+    - `color-palette-width=CCS-value` - Specifies the width of the element, defaults to `150px`
+    - `color-palette-height=CCS-value` - Specified the height of the element, defaults to `0.5em`
+    - `color-palette-discrete` - Renders discrete color list instead of interpolating
+
+
+## Example
+
+```markdown
+### Highlight/Focus:
+- ![blue](!color-swatch=blue) [polymer](!highlight-refs=polymer&focus-refs=polymer)
+- ![blue](!color-swatch=red) [ligand](!highlight-refs=ligand&focus-refs=ligand)
+- [both](!highlight-refs=polymer,ligand&focus-refs=polymer,ligand)
+
+### Color Palettes
+|name|visual|
+|---:|---|
+|viridis|![viridis](!color-palette-name=viridis)|
+|rainbow (discrete)|![simple-rainbow](!color-palette-name=simple-rainbow&color-palette-discrete)|
+|custom|![custom](!color-palette-colors=red,#00ff00,rgb(0,0,255))|
+
+### Camera controls
+- [center](!center-camera)
+
+### Image embedded in MVSX file
+![mvsx image](logo.png)
+```
+
+This works with the MolViewSpec state built by:
+
+```py
+import molviewspec as mvs
+
+builder = mvs.create_builder()
+
+assets = {
+    "1cbs.cif": "https://files.wwpdb.org/download/1cbs.cif",
+    "logo.png": "https://molstar.org/img/molstar-logo.png",
+}
+
+model = (
+    builder.download(url="1cbs.cif")
+        .parse(format="mmcif")
+        .model_structure()
+)
+(
+    model.component(selector="polymer")
+    .representation(ref="polymer")
+    .color(color="blue")
+)
+(
+    model.component(selector="ligand")
+    .representation(ref="ligand")
+    .color(color="red")
+)
+
+mvsx = mvs.MVSX(
+    data=builder.get_state(
+        description="""..."""  # inline the code above
+    ),
+    assets=assets
+)
+```

docs/mkdocs.yml

@@ -25,7 +25,6 @@ markdown_extensions:
       generic: true
 # Scripts for rendering Latex equations (in addition to pymdownx.arithmatex):
 extra_javascript:
-  - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 nav:
   - 'index.md'
@@ -38,6 +37,8 @@ nav:
     - Data State: 'plugin/data-state.md'
     - File Formats: 'plugin/file-formats.md'
     - CIF Schemas: 'plugin/cif-schemas.md'
+    - Managers:
+      - Markdown Extensions: 'plugin/managers/markdown-extensions.md'
     - State Transforms:
       - Custom Trajectory: 'plugin/transforms/custom-trajectory.md'
       - Custom Conformation: 'plugin/transforms/custom-conformation.md'
@@ -59,5 +60,5 @@ nav:
     - Interactions: 'extensions/interactions.md'
   - Misc:
     - Interesting PDB entries: misc/interesting-pdb-entries.md
-    - Exporting component data: exporting-components.md
+    - Exporting component data: misc/exporting-components.md
 repo_url: https://github.com/molstar/docs

eslint.config.mjs

@@ -0,0 +1,111 @@
+import { defineConfig } from "eslint/config";
+import globals from "globals";
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import tsParser from "@typescript-eslint/parser";
+
+export default defineConfig([{
+    ignores: [
+        "node_modules/*",
+        "build/*",
+        "deploy/*",
+        "docs/site/*",
+        "lib/*",
+        "eslint.config.mjs",
+        "build.mjs",
+    ]
+},{
+    languageOptions: {
+        globals: {
+            ...globals.browser,
+            ...globals.node,
+        },
+
+        ecmaVersion: 2018,
+        sourceType: "module",
+
+        parserOptions: {
+            ecmaFeatures: {
+                impliedStrict: true,
+            },
+        },
+    },
+
+    rules: {
+        indent: "off",
+        "arrow-parens": ["off", "as-needed"],
+        "brace-style": ["error", "1tbs", {
+            allowSingleLine: true,
+        }],
+        "comma-spacing": "off",
+        "space-infix-ops": "off",
+        "comma-dangle": "off",
+        quotes: ["warn", "single", { "allowTemplateLiterals": true, "avoidEscape": true }],
+        eqeqeq: ["error", "smart"],
+        "import/order": "off",
+        "no-eval": "warn",
+        "no-extend-native": "warn",
+        "no-new-wrappers": "warn",
+        "no-trailing-spaces": "error",
+        "no-unsafe-finally": "warn",
+        "no-self-compare": "warn",
+        "no-var": "error",
+        "spaced-comment": "error",
+        semi: "warn",
+        "no-restricted-syntax": ["error", {
+            selector: "ExportDefaultDeclaration",
+            message: "Default exports are not allowed",
+        }],
+        "no-throw-literal": "error",
+        "key-spacing": "error",
+        "object-curly-spacing": ["error", "always"],
+        "array-bracket-spacing": "error",
+        "space-in-parens": "error",
+        "computed-property-spacing": "error",
+        "prefer-const": ["error", {
+            destructuring: "all",
+            ignoreReadBeforeAssign: false,
+        }],
+        "space-before-function-paren": "off",
+        "func-call-spacing": "off",
+        "no-multi-spaces": "error",
+        "block-spacing": "error",
+        "keyword-spacing": "warn",
+        "space-before-blocks": "error",
+        "semi-spacing": "error",
+        "no-constant-binary-expression": "error",
+    },
+}, {
+    files: ["**/*.ts", "**/*.tsx"],
+
+    plugins: {
+        "@typescript-eslint": typescriptEslint,
+    },
+
+    languageOptions: {
+        parser: tsParser,
+        ecmaVersion: 5,
+        sourceType: "module",
+
+        parserOptions: {
+            project: ["tsconfig.eslint.json"],
+        },
+    },
+
+    rules: {
+        "@typescript-eslint/ban-types": "off",
+        "@typescript-eslint/class-name-casing": "off",        
+        "@typescript-eslint/member-delimiter-style": ["off", {
+            multiline: {
+                delimiter: "none",
+                requireLast: true,
+            },
+
+            singleline: {
+                delimiter: "semi",
+                requireLast: false,
+            },
+        }],
+        "@typescript-eslint/prefer-namespace-keyword": "warn",
+        "@typescript-eslint/semi": ["off", null],
+    },
+}]);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "molstar",
-  "version": "4.17.0",
+  "version": "5.0.0-dev.10",
   "description": "A comprehensive macromolecular library.",
   "homepage": "https://github.com/molstar/molstar#readme",
   "repository": {
@@ -18,29 +18,22 @@
     "lint-fix": "eslint . --fix",
     "test": "npm install --no-save \"gl@^6.0.2\" && npm run lint && jest",
     "jest": "jest",
-    "build": "npm run build-tsc && npm run build-extra && npm run build-webpack",
-    "clean": "node ./scripts/clean.js",
+    "clean": "node ./scripts/clean.js --all",
+    "clean:build": "node ./scripts/clean.js --build",
+    "build": "npm run build:apps && npm run build:lib",
+    "build:apps": "node ./scripts/build.mjs -a -e --prd",
+    "build:lib": "concurrently \"tsc --incremental\" \"tsc --build tsconfig.commonjs.json --incremental\" && npm run build:lib-extra",
+    "build:lib-extra": "node scripts/write-version.mjs && cpx \"src/**/*.{scss,html,ico,jpg}\" lib/ && cpx \"src/**/*.{scss,html,ico,jpg}\" lib/commonjs/ && tsc-alias -p tsconfig.json",
     "rebuild": "npm run clean && npm run build",
-    "build-viewer": "npm run build-tsc && npm run build-extra && npm run build-webpack-viewer",
-    "build-tsc": "concurrently \"tsc --incremental\" \"tsc --build tsconfig.commonjs.json --incremental\"",
-    "build-extra": "cpx \"src/**/*.{scss,html,ico,jpg}\" lib/",
-    "build-webpack": "webpack --mode production --config ./webpack.config.production.js",
-    "build-webpack-viewer": "webpack --mode production --config ./webpack.config.viewer.js",
-    "watch": "concurrently -c \"green,green,gray,gray\" --names \"tsc,srv,ext,wpc\" --kill-others \"npm:watch-tsc\" \"npm:watch-servers\" \"npm:watch-extra\" \"npm:watch-webpack\"",
-    "watch-viewer": "concurrently -c \"green,gray,gray\" --names \"tsc,ext,wpc\" --kill-others \"npm:watch-tsc\" \"npm:watch-extra\" \"npm:watch-webpack-viewer\"",
-    "watch-viewer-debug": "concurrently -c \"green,gray,gray\" --names \"tsc,ext,wpc\" --kill-others \"npm:watch-tsc\" \"npm:watch-extra\" \"npm:watch-webpack-viewer-debug\"",
-    "watch-tsc": "tsc --watch --incremental",
-    "watch-servers": "tsc --build tsconfig.commonjs.json --watch --incremental",
-    "watch-extra": "cpx \"src/**/*.{scss,html,ico,jpg}\" lib/ --watch",
-    "watch-webpack": "webpack -w --mode development --stats minimal",
-    "watch-webpack-viewer": "webpack -w --mode development --stats minimal --config ./webpack.config.viewer.js",
-    "watch-webpack-viewer-debug": "webpack -w --mode development --stats minimal --config ./webpack.config.viewer.debug.js",
-    "dev": "node build-dev.mjs",
-    "dev:all": "node build-dev.mjs -a -e",
-    "dev:viewer": "node build-dev.mjs -a viewer",
-    "dev:apps": "node build-dev.mjs -a",
-    "dev:examples": "node build-dev.mjs -e",
+    "dev": "node ./scripts/build.mjs",
+    "dev:all": "node ./scripts/build.mjs -a -e -bt",
+    "dev:viewer": "node ./scripts/build.mjs -a viewer",
+    "dev:apps": "node ./scripts/build.mjs -a",
+    "dev:examples": "node ./scripts/build.mjs -e",
+    "dev:browser-tests": "node ./scripts/build.mjs -bt",
     "serve": "http-server -p 1338 -g",
+    "deploy:local": "npm run clean:build && npm run build:apps && node ./scripts/deploy.js --local",
+    "deploy:remote": "npm run clean:build && npm run build:apps && node ./scripts/deploy.js",
     "model-server": "node lib/commonjs/servers/model/server.js",
     "model-server-watch": "nodemon --watch lib lib/commonjs/servers/model/server.js",
     "volume-server-test": "node lib/commonjs/servers/volume/server.js --idMap em 'test/${id}.mdb' --defaultPort 1336",
@@ -127,53 +120,46 @@
     "Ventura Rivera <venturaxrivera@gmail.com>",
     "Andy Turner <agdturner@gmail.com>",
     "Lukáš Polák <admin@lukaspolak.cz>",
-    "Chetan Mishra <chetan.s115@gmail.com>"
+    "Chetan Mishra <chetan.s115@gmail.com>",
+    "Zach Charlop-Powers <zach.charlop.powers@gmail.com>",
+    "Kim Juho <juho_kim@outlook.com>",
+    "Victoria Doshchenko <doshchenko.victoria@gmail.com>"
   ],
   "license": "MIT",
   "devDependencies": {
-    "@types/cors": "^2.8.18",
+    "@types/cors": "^2.8.19",
     "@types/gl": "^6.0.5",
     "@types/jest": "^29.5.14",
     "@types/pngjs": "^6.0.5",
-    "@types/react": "^18.3.21",
+    "@types/react": "^18.3.23",
     "@types/react-dom": "^18.3.7",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
+    "@typescript-eslint/eslint-plugin": "^8.34.0",
+    "@typescript-eslint/parser": "^8.34.0",
     "benchmark": "^2.1.4",
     "concurrently": "^9.1.2",
     "cpx2": "^8.0.0",
-    "crypto-browserify": "^3.12.1",
     "css-loader": "^7.1.2",
-    "esbuild": "^0.25.4",
+    "esbuild": "^0.25.5",
     "esbuild-sass-plugin": "^3.3.1",
-    "eslint": "^8.57.1",
-    "extra-watch-webpack-plugin": "^1.0.3",
-    "file-loader": "^6.2.0",
+    "eslint": "^9.29.0",
     "fs-extra": "^11.3.0",
     "http-server": "^14.1.1",
     "jest": "^29.7.0",
     "jpeg-js": "^0.4.4",
-    "mini-css-extract-plugin": "^2.9.2",
-    "path-browserify": "^1.0.1",
-    "raw-loader": "^4.0.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "sass": "^1.89.0",
-    "sass-loader": "^16.0.5",
-    "simple-git": "^3.27.0",
-    "stream-browserify": "^3.0.0",
-    "style-loader": "^4.0.0",
+    "sass": "^1.89.1",
+    "simple-git": "^3.28.0",
     "ts-jest": "^29.3.4",
-    "typescript": "^5.8.3",
-    "webpack": "^5.99.8",
-    "webpack-cli": "^6.0.1"
+    "tsc-alias": "^1.8.16",
+    "typescript": "^5.8.3"
   },
   "dependencies": {
     "@types/argparse": "^2.0.17",
     "@types/benchmark": "^2.1.5",
-    "@types/compression": "1.7.5",
-    "@types/express": "^5.0.2",
-    "@types/node": "^18.19.101",
+    "@types/compression": "1.8.1",
+    "@types/express": "^5.0.3",
+    "@types/node": "^18.19.111",
     "@types/node-fetch": "^2.6.12",
     "@types/swagger-ui-dist": "3.30.5",
     "argparse": "^2.0.1",
@@ -181,13 +167,14 @@
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "h264-mp4-encoder": "^1.0.12",
-    "immer": "^10.1.1",
     "immutable": "^5.1.2",
     "io-ts": "^2.2.22",
+    "mutative": "^1.2.0",
     "node-fetch": "^2.7.0",
     "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
     "rxjs": "^7.8.2",
-    "swagger-ui-dist": "^5.21.0",
+    "swagger-ui-dist": "^5.24.0",
     "tslib": "^2.8.1",
     "util.promisify": "^1.1.3"
   },
@@ -217,4 +204,4 @@
       "optional": true
     }
   }
-}
+}

scripts/build.mjs

@@ -97,31 +97,52 @@ function examplesCssRenamePlugin({ root }) {
     };
 }
 
-async function watch(app) {
+function resolveEntryPath(path) {
+    if (!fs.existsSync(path)) {
+        return path + 'x'; // fallback to .tsx
+    }
+    return path;
+}
+
+function getPaths(app) {
+    if (app.kind === 'app') {
+        return {
+            prefix: `./build/${app.name}`,
+            entry: resolveEntryPath(`./src/apps/${app.name}/index.ts`),
+            outfile: `./build/${app.name}/${app.filename || 'molstar.js'}`,
+        };
+    }
+    if (app.kind === 'example') {
+        return {
+            prefix: `./build/examples/${app.name}`,
+            entry: resolveEntryPath(`./src/examples/${app.name}/index.ts`),
+            outfile: `./build/examples/${app.name}/${app.filename || 'index.js'}`,
+        };
+    }
+    if (app.kind === 'browser-test') {
+        return {
+            prefix: `./build/tests/browser`,
+            entry: resolveEntryPath(`./src/tests/browser/${app.name}.ts`),
+            outfile: `./build/tests/browser/${app.name}.js`,
+        };
+    }
+    throw new Error(`Unknown app kind: ${app.kind}`);
+}
+
+async function createBundle(app) {
     const { name, kind } = app;
 
-    const prefix = kind === 'app'
-        ? `./build/${name}`
-        : `./build/examples/${name}`;
-
-    let entry = `./src/${kind}s/${name}/index.ts`;
-    if (!fs.existsSync(entry)) {
-        entry = `./src/${kind}s/${name}/index.tsx`;
-    }
-
-    let filename = app.filename;
-    if (!filename) {
-        filename = kind === 'app' ? 'molstar.js' : 'index.js';
-    }
+    const { prefix, entry, outfile } = getPaths(app);
 
     const ctx = await esbuild.context({
         entryPoints: [entry],
         tsconfig: './tsconfig.json',
         bundle: true,
+        minify: isProduction,
+        minifyIdentifiers: false,
+        sourcemap: includeSourceMap,
         globalName: app.globalName || 'molstar',
-        outfile: kind === 'app'
-            ? `./build/${name}/${filename}`
-            : `./build/examples/${name}/${filename}`,
+        outfile,
         plugins: [
             fileLoaderPlugin({ out: prefix }),
             sassPlugin({
@@ -139,15 +160,40 @@ async function watch(app) {
         },
         color: true,
         logLevel: 'info',
+        define: {
+            'process.env.DEBUG': JSON.stringify(process.env.DEBUG || false),
+            __MOLSTAR_PLUGIN_VERSION__: JSON.stringify(VERSION),
+            __MOLSTAR_BUILD_TIMESTAMP__: `${TIMESTAMP}`,
+        },
     });
 
     await ctx.rebuild();
-    await ctx.watch();
+
+    if (!isProduction) await ctx.watch();
+}
+
+function findBrowserTests(names) {
+    const dir = path.resolve('./src', 'tests', 'browser');
+    let files = fs.readdirSync(dir).filter(file => file.endsWith('.ts')).map(file => file.replace('.ts', ''));
+    if (names.length) {
+        files = files.filter(file => names.includes(file));
+    }
+    return files.map(name => ({ kind: 'browser-test', name }));
 }
 
 const argParser = new argparse.ArgumentParser({
     add_help: true,
-    description: 'Mol* development build'
+    description: 'Mol* Build'
+});
+argParser.add_argument('--prd', {
+    help: 'Create a production build.',
+    required: false,
+    action: 'store_true',
+});
+argParser.add_argument('--no-src-map', {
+    help: 'Do not include source map.',
+    required: false,
+    action: 'store_true',
 });
 argParser.add_argument('--apps', '-a', {
     help: 'Apps to build.',
@@ -159,6 +205,11 @@ argParser.add_argument('--examples', '-e', {
     required: false,
     nargs: '*',
 });
+argParser.add_argument('--browser-tests', '-bt', {
+    help: 'Browser Tests to build.',
+    required: false,
+    nargs: '*',
+});
 argParser.add_argument('--port', '-p', {
     help: 'Port.',
     required: false,
@@ -174,11 +225,20 @@ argParser.add_argument('--host', {
 
 const args = argParser.parse_args();
 
+
+const isProduction = !!args.prd;
+const includeSourceMap = !args.no_src_map;
+
+const VERSION = isProduction ? JSON.parse(fs.readFileSync('./package.json', 'utf8')).version : '(dev build)';
+const TIMESTAMP = Date.now();
+
 const apps = (!args.apps ? [] : (args.apps.length ? args.apps.map(a => findApp(a, 'app')).filter(a => a) : Apps.filter(a => a.kind === 'app')));
 const examples = (!args.examples ? [] : (args.examples.length ? args.examples.map(e => findApp(e, 'example')).filter(a => a) : Apps.filter(a => a.kind === 'example')));
+const browserTests = (!args.browser_tests ? [] : findBrowserTests(args.browser_tests));
 
 console.log('Apps:', apps.map(a => a.name));
 console.log('Examples:', examples.map(e => e.name));
+console.log('Browser Tests', browserTests.map(e => e.name));
 console.log('');
 
 function getLocalIPs() {
@@ -198,27 +258,42 @@ function getLocalIPs() {
 
 async function main() {
     const promises = [];
-    for (const app of apps) promises.push(watch(app));
-    for (const example of examples) promises.push(watch(example));
+    console.log(isProduction ? 'Building apps...' : 'Initial build...');
 
-    console.log('Initial build...');
+    for (const app of apps) promises.push(createBundle(app));
+    for (const example of examples) promises.push(createBundle(example));
+    for (const browserTest of browserTests) promises.push(createBundle(browserTest));
 
     await Promise.all(promises);
-    console.log('Done.');
+
+    if (isProduction) {
+        console.log('Done.');
+        process.exit(0);
+    }
+
+    console.log('Initial build complete.');
+
+    const certfile = './dev.pem';
+    const keyfile = './dev-key.pem';
+
+    const sslEnabled = fs.existsSync(certfile) && fs.existsSync(keyfile);
+    const protocol = sslEnabled ? 'https' : 'http';
 
     const ctx = await esbuild.context({});
     ctx.serve({
         servedir: './',
         port: args.port,
         host: '0.0.0.0', // Always listen on all interfaces
+        certfile: sslEnabled ? certfile : undefined,
+        keyfile: sslEnabled ? keyfile : undefined,
     });
 
     console.log('');
-    console.log(`Server URL: http://localhost:${args.port}`);
+    console.log(`Server URL: ${protocol}://localhost:${args.port}`);
     if (args.host) {
         console.log('Available host addresses:');
         const ips = getLocalIPs();
-        ips.forEach(ip => console.log(`  http://${ip}:${args.port}`));
+        ips.forEach(ip => console.log(`  ${protocol}://${ip}:${args.port}`));
     }
     console.log('');
     console.log('Watching for changes...');
@@ -226,4 +301,7 @@ async function main() {
     console.log('Press Ctrl+C to stop.');
 }
 
-main().catch(console.error);
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

scripts/clean.js

@@ -6,6 +6,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const argparse = require('argparse');
 
 function removeDir(dirPath) {
     for (const ent of fs.readdirSync(dirPath)) {
@@ -24,11 +25,29 @@ function remove(entryPath) {
         fs.unlinkSync(entryPath);
 }
 
-const toClean = [
-    path.resolve(__dirname, '../build'),
-    path.resolve(__dirname, '../lib'),
-    path.resolve(__dirname, '../tsconfig.tsbuildinfo'),
-];
+const argParser = new argparse.ArgumentParser({
+    add_help: true,
+    description: 'Clean Script'
+});
+argParser.add_argument('--build', { required: false, action: 'store_true' });
+argParser.add_argument('--lib', { required: false, action: 'store_true' });
+argParser.add_argument('--all', { required: false, action: 'store_true' });
+const args = argParser.parse_args();
+
+const toClean = [];
+
+if (args.build || args.all) {
+    toClean.push(path.resolve(__dirname, '../build'));
+    toClean.push(path.resolve(__dirname, '../deploy/data'));
+}
+if (args.lib || args.all) {
+    toClean.push(
+        path.resolve(__dirname, '../lib'),
+        path.resolve(__dirname, '../tsconfig.tsbuildinfo'),
+    );
+}
+
+console.log('\n###', 'cleaning', toClean.join(', '));
 
 toClean.forEach(ph => {
     if (fs.existsSync(ph)) {

scripts/deploy.js

@@ -2,20 +2,24 @@
  * Copyright (c) 2019-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author David Sehnal <david.sehnal@gmail.com>
  */
 
 const git = require('simple-git');
 const path = require('path');
-const fs = require("fs");
-const fse = require("fs-extra");
+const fs = require('fs');
+const fse = require('fs-extra');
+const argparse = require('argparse');
 
 const VERSION = require(path.resolve(__dirname, '../package.json')).version;
+const MVS_STORIES_VERSION = require(path.resolve(__dirname, '../src/apps/mvs-stories/version.ts')).VERSION;
 
-const remoteUrl = "https://github.com/molstar/molstar.github.io.git";
+const remoteUrl = 'https://github.com/molstar/molstar.github.io.git';
 const dataDir = path.resolve(__dirname, '../data/');
 const buildDir = path.resolve(__dirname, '../build/');
-const deployDir = path.resolve(buildDir, 'deploy/');
-const localPath = path.resolve(deployDir, 'molstar.github.io/');
+const deployDir = path.resolve(__dirname, '../deploy/');
+const localPath = path.resolve(deployDir, 'data/');
+const repositoryPath = path.resolve(deployDir, 'molstar.github.io/');
 
 const analyticsTag = /<!-- __MOLSTAR_ANALYTICS__ -->/g;
 const analyticsCode = `<!-- Cloudflare Web Analytics --><script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "c414cbae2d284ea995171a81e4a3e721"}'></script><!-- End Cloudflare Web Analytics --><iframe src="https://web3dsurvey.com/collector-iframe.html" style="width: 1px; height: 1px;"></iframe>`;
@@ -80,54 +84,106 @@ function copyMe() {
     addAnalytics(path.resolve(meDeployPath, 'index.html'));
 }
 
+function copyMVSStories() {
+    console.log('\n###', 'copy MVS stories files');
+    const mvsStoriesBuildPath = path.resolve(buildDir, 'mvs-stories/');
+    const mvsStoriesDeployPath = path.resolve(localPath, `stories-viewer/v${MVS_STORIES_VERSION}/`);
+    fse.copySync(mvsStoriesBuildPath, mvsStoriesDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(mvsStoriesDeployPath, 'index.html'));
+
+    // TODO: add PWA
+    // addManifest(path.resolve(mvsStoriesDeployPath, 'index.html'));
+    // addPwa(path.resolve(mvsStoriesDeployPath, 'index.html'));
+}
+
+function copyDemo(name) {
+    console.log('\n###', `copy demo files for ${name}`);
+    const demoBuildPath = path.resolve(buildDir, `examples/${name}/`);
+    const demoDeployPath = path.resolve(localPath, `demos/${name}/`);
+    fse.copySync(demoBuildPath, demoDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(demoDeployPath, 'index.html'));
+}
+
 function copyDemos() {
     console.log('\n###', 'copy demos files');
-    const lightingBuildPath = path.resolve(buildDir, 'examples/lighting/');
-    const lightingDeployPath = path.resolve(localPath, 'demos/lighting/');
-    fse.copySync(lightingBuildPath, lightingDeployPath, { overwrite: true });
-    addAnalytics(path.resolve(lightingDeployPath, 'index.html'));
-
-    const orbitalsBuildPath = path.resolve(buildDir, 'examples/alpha-orbitals/');
-    const orbitalsDeployPath = path.resolve(localPath, 'demos/alpha-orbitals/');
-    fse.copySync(orbitalsBuildPath, orbitalsDeployPath, { overwrite: true });
-    addAnalytics(path.resolve(orbitalsDeployPath, 'index.html'));
+    copyDemo('lighting');
+    copyDemo('alpha-orbitals');
+    copyDemo('mvs-stories');
 }
 
 function copyFiles() {
     try {
         copyViewer();
         copyMe();
+        copyMVSStories();
         copyDemos();
     } catch (e) {
         console.error(e);
     }
 }
 
+function copyToRepository() {
+    console.log('\n###', 'copy repository files');
+    fse.copySync(localPath, repositoryPath, { overwrite: true });
+}
+
+function syncRepository() {
+    console.log('\n###', 'sync repository');
+    if (!fs.existsSync(path.resolve(repositoryPath, '.git/'))) {
+        console.log('\n###', 'clone repository');
+        git()
+            .outputHandler(log)
+            .clone(remoteUrl, repositoryPath)
+            .fetch(['--all'])
+            .exec(copyToRepository);
+    } else {
+        console.log('\n###', 'update repository');
+        git()
+            .outputHandler(log)
+            .fetch(['--all'])
+            .reset(['--hard', 'origin/master'])
+            .exec(copyToRepository);
+    }
+}
+
+function commit() {
+    console.log('\n###', 'commit changes');
+    git()
+        .outputHandler(log)
+        .add(['-A'])
+        .commit(`Updated Apps and Demos
+- Mol* version: ${VERSION}
+- MVS Stories version: ${MVS_STORIES_VERSION}`)
+        .push();
+}
+
 if (!fs.existsSync(localPath)) {
     console.log('\n###', 'create localPath');
     fs.mkdirSync(localPath, { recursive: true });
 }
 
-process.chdir(localPath);
+const argParser = new argparse.ArgumentParser({
+    add_help: true,
+    description: 'Mol* Deploy'
+});
+argParser.add_argument('--local',{
+    help: 'Do not commit to remote repository.',
+    required: false,
+    action: 'store_true',
+});
+const args = argParser.parse_args();
 
-if (!fs.existsSync(path.resolve(localPath, '.git/'))) {
-    console.log('\n###', 'clone repository');
-    git()
-        .outputHandler(log)
-        .clone(remoteUrl, localPath)
-        .fetch(['--all'])
-        .exec(copyFiles)
-        .add(['-A'])
-        .commit('updated viewer & demos')
-        .push();
-} else {
-    console.log('\n###', 'update repository');
-    git()
-        .outputHandler(log)
-        .fetch(['--all'])
-        .reset(['--hard', 'origin/master'])
-        .exec(copyFiles)
-        .add(['-A'])
-        .commit('updated viewer & demos')
-        .push();
-}
+copyFiles();
+
+if (args.local) {
+    process.exit(0);
+}
+
+if (!fs.existsSync(repositoryPath)) {
+    console.log('\n###', 'create repositoryPath');
+    fs.mkdirSync(repositoryPath, { recursive: true });
+}
+
+process.chdir(repositoryPath);
+syncRepository();
+commit();

scripts/write-version.mjs

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import * as fs from 'fs';
+
+const VERSION = JSON.parse(fs.readFileSync('./package.json', 'utf8')).version;
+const TIMESTAMP = Date.now();
+const file = `export var PLUGIN_VERSION = '${VERSION}';\nexport var PLUGIN_VERSION_DATE = new Date(${TIMESTAMP})`;
+const files = ['./lib/mol-plugin/version.js', './lib/commonjs/mol-plugin/version.js'];
+for (const f of files) {
+    if (!fs.existsSync(f)) continue;
+    fs.writeFileSync(f, file);
+}

src/apps/mesoscale-explorer/app.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -147,6 +147,7 @@ export class MesoscaleExplorer {
             behaviors: [
                 PluginSpec.Behavior(PluginBehaviors.Camera.CameraAxisHelper),
                 PluginSpec.Behavior(PluginBehaviors.Camera.CameraControls),
+                PluginSpec.Behavior(PluginBehaviors.State.SnapshotControls),
 
                 PluginSpec.Behavior(MesoFocusLoci),
                 PluginSpec.Behavior(MesoSelectLoci),
@@ -261,7 +262,6 @@ export class MesoscaleExplorer {
             image: true,
             componentManager: false,
             structureSelection: true,
-            behavior: true,
         });
 
         plugin.managers.lociLabels.clearProviders();

src/apps/mesoscale-explorer/style.scss

@@ -1,32 +1,28 @@
 @use "sass:color";
 
-$default-background:         #2D3E50;
-$font-color:                 #EDF1F2;
-$hover-font-color:           #3B9AD9;
-$entity-current-font-color:  #FFFFFF;
-$msp-btn-remove-background:      #BF3A31;
-$msp-btn-remove-hover-font-color:#ffffff;
-$msp-btn-commit-on-font-color:   #ffffff;
-$entity-badge-font-color:    #ccd4e0;
+@use '../../mol-plugin-ui/skin/base/colors' with (
+    $default-background:         #2D3E50,
+    $font-color:                 #EDF1F2,
+    $hover-font-color:           #3B9AD9,
+    $entity-current-font-color:  #FFFFFF,
+    $msp-btn-remove-background:      #BF3A31,
+    $msp-btn-remove-hover-font-color:#ffffff,
+    $msp-btn-commit-on-font-color:   #ffffff,
+    $entity-badge-font-color:    #ccd4e0,
 
-// used in LOG
-$log-message:          #0CCA5D;
-$log-info:             #5E3673;
-$log-warning:          #FCC937;
-$log-error:            #FD354B;
+    // used in LOG
+    $log-message:          #0CCA5D,
+    $log-info:             #5E3673,
+    $log-warning:          #FCC937,
+    $log-error:            #FD354B,
 
-$logo-background: rgba(0,0,0,0.75);
+    $logo-background: rgba(0,0,0,0.75),
 
-@function color-lower-contrast($color, $amount) {
-    @return color.adjust($color, $lightness: -$amount, $space: hsl);
-}
+    $color-adjust-sign: -1,
+);
 
-@function color-increase-contrast($color, $amount) {
-    @return color.adjust($color, $lightness: $amount, $space: hsl);
-}
-
-@import '../../mol-plugin-ui/skin/base/base';
-@import '../../mol-plugin-ui/skin/base/variables';
+@use '../../mol-plugin-ui/skin/base/base';
+@use '../../mol-plugin-ui/skin/base/vars' as *;
 
 a {
     color: $font-color;

src/apps/mvs-stories/context.ts

@@ -16,6 +16,7 @@ export class MVSStoriesContext {
     commands = new BehaviorSubject<MVSStoriesCommand | undefined>(undefined);
     state = {
         viewers: new BehaviorSubject<{ name?: string, model: MVSStoriesViewerModel }[]>([]),
+        currentStoryData: new BehaviorSubject<string | Uint8Array | undefined>(undefined),
         isLoading: new BehaviorSubject(false),
     };
 
@@ -27,7 +28,7 @@ export class MVSStoriesContext {
     }
 }
 
-export function getMVSStoriesContext(options?: { name?: string, container?: object }) {
+export function getMVSStoriesContext(options?: { name?: string, container?: object }): MVSStoriesContext {
     const container: any = options?.container ?? window;
     container.componentContexts ??= {};
     const name = options?.name ?? '<default>';

src/apps/mvs-stories/elements/snapshot-markdown.tsx

@@ -8,13 +8,12 @@ import { BehaviorSubject, distinctUntilChanged, map } from 'rxjs';
 import { PluginComponent } from '../../../mol-plugin-state/component';
 import { getMVSStoriesContext, MVSStoriesContext } from '../context';
 import { MVSStoriesViewerModel } from './viewer';
-import Markdown from 'react-markdown';
 import { useBehavior } from '../../../mol-plugin-ui/hooks/use-behavior';
 import { createRoot } from 'react-dom/client';
 import { PluginStateSnapshotManager } from '../../../mol-plugin-state/manager/snapshots';
-import { MarkdownAnchor } from '../../../mol-plugin-ui/controls';
 import { PluginReactContext } from '../../../mol-plugin-ui/base';
 import { CSSProperties } from 'react';
+import { Markdown } from '../../../mol-plugin-ui/controls/markdown';
 
 export class MVSStoriesSnapshotMarkdownModel extends PluginComponent {
     readonly context: MVSStoriesContext;
@@ -99,7 +98,7 @@ export function MVSStoriesSnapshotMarkdownUI({ model }: { model: MVSStoriesSnaps
         <div style={{ flexGrow: 1, overflow: 'hidden', overflowY: 'auto', position: 'relative' }}>
             <div style={{ position: 'absolute', inset: 0 }}>
                 <PluginReactContext.Provider value={model.viewer?.model.plugin as any}>
-                    <Markdown skipHtml components={{ a: MarkdownAnchor }}>{state.entry?.description ?? 'Description not available'}</Markdown>
+                    <Markdown>{state.entry?.description ?? 'Description not available'}</Markdown>
                 </PluginReactContext.Provider>
             </div>
         </div>

src/apps/mvs-stories/elements/viewer.tsx

@@ -6,6 +6,8 @@
 
 import { MolViewSpec } from '../../../extensions/mvs/behavior';
 import { loadMVSData } from '../../../extensions/mvs/components/formats';
+import { MVSData } from '../../../extensions/mvs/mvs-data';
+import { StringLike } from '../../../mol-io/common/string-like';
 import { PluginComponent } from '../../../mol-plugin-state/component';
 import { createPluginUI } from '../../../mol-plugin-ui';
 import { renderReact18 } from '../../../mol-plugin-ui/react18';
@@ -56,11 +58,17 @@ export class MVSStoriesViewerModel extends PluginComponent {
             try {
                 this.context.state.isLoading.next(true);
                 if (cmd.kind === 'load-mvs') {
+                    let loadedData: MVSData | StringLike | Uint8Array | undefined;
                     if (cmd.url) {
                         const data = await this.plugin.runTask(this.plugin.fetch({ url: cmd.url, type: cmd.format === 'mvsx' ? 'binary' : 'string' }));
-                        await loadMVSData(this.plugin, data, cmd.format ?? 'mvsj', { sourceUrl: cmd.url });
+                        loadedData = await loadMVSData(this.plugin, data, cmd.format ?? 'mvsj', { sourceUrl: cmd.url });
                     } else if (cmd.data) {
-                        await loadMVSData(this.plugin, cmd.data, cmd.format ?? 'mvsj');
+                        loadedData = await loadMVSData(this.plugin, cmd.data, cmd.format ?? 'mvsj');
+                    }
+                    if (StringLike.is(loadedData) || loadedData instanceof Uint8Array) {
+                        this.context.state.currentStoryData.next(loadedData as string | Uint8Array);
+                    } else if (loadedData) {
+                        this.context.state.currentStoryData.next(JSON.stringify(loadedData));
                     }
                 }
             } catch (e) {

src/apps/mvs-stories/index.html

@@ -38,6 +38,25 @@
             gap: 16px;
         }
 
+        #links {
+            position: absolute;
+            bottom: 4px;
+            right: 8px;
+            font-family: "Raleway", "HelveticaNeue", "Helvetica Neue", Helvetica, Arial, sans-serif;
+            font-size: 0.6rem;
+            z-index: -1;
+            color: #666;
+        }
+
+        #links a {
+            color: #666;
+            text-decoration: none;
+        }
+
+        #links .sep {
+            color: #aaa;
+        }
+
         @media (orientation:portrait) {
             #viewer {
                 position: absolute;
@@ -68,15 +87,23 @@
 <body>
     <!-- the context-name parameter is optional and useful when embedding multiple stories in a single page -->
     <div id="viewer">
-        <mvs-stories-viewer context-name="story1" />
+        <mvs-stories-viewer context-name="story1" ></mvs-stories-viewer>
     </div>
     <div id="controls">
-        <mvs-stories-snapshot-markdown context-name="story1" style="flex-grow: 1;" />
+        <mvs-stories-snapshot-markdown context-name="story1" style="flex-grow: 1;" ></mvs-stories-snapshot-markdown>
+    </div>
+
+    <div id="links">
+        <span id="open-in-stories"><a href="#" id="open-in-stories-link" target="_blank" rel="noopener noreferrer" title="Open and edit the story in the MolViewStories app">Edit in MolViewStories</a>&nbsp;<span class="sep">•</span></span>
+        <span id="open-in-molstar"><a href="#" id="open-in-molstar-link" target="_blank" rel="noopener noreferrer" title="Open the story in the Mol* Viewer app. Enables exporting an animation.">Open in Mol* Viewer</a>&nbsp;<span class="sep">•</span></span>
+        <a href="#" id="mvs-data" title="MolViewSpec State for this story. Can be opened in the Mol* app.">Download MVS</a> <span class="sep">•</span> <a href="https://github.com/molstar/molstar/tree/master/src/apps/mvs-stories" id="mvs-data" target="_blank" rel="noopener noreferrer">Source Code</a>
     </div>
 
     <script>
         var urlParams = new URLSearchParams(window.location.search);
+        var storyId = urlParams.get('story-id');
         var storyUrl = urlParams.get('story-url');
+        var storySessionUrl = urlParams.get('story-session-url');
         var format = urlParams.get('data-format');
 
         // For testing purposes:
@@ -84,11 +111,38 @@
         //     storyUrl = 'https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/kinase-story.mvsj';
         // }
 
-        mvsStories.loadFromURL(
-            storyUrl,
-            { format: format || 'mvsj', contextName: 'story1' },
-        );
+        var molstarDataLink = storyUrl;
+        var editInStoriesUrl = undefined;
+
+        if (storyId) {
+            mvsStories.loadFromID(storyId, { format: format || 'mvsj', contextName: 'story1' });
+            editInStoriesUrl = 'https://molstar.org/mol-view-stories/builder?published-session-id=' + storyId;
+            molstarDataLink = 'https://stories.molstar.org/api/story/' + storyId + '/data';
+        } else if (storyUrl) {
+            mvsStories.loadFromURL(storyUrl, { format: format || 'mvsj', contextName: 'story1' });
+        }
+
+        if (!editInStoriesUrl && storySessionUrl) {
+            editInStoriesUrl = 'https://molstar.org/mol-view-stories/builder?session-url=' + encodeURIComponent(storySessionUrl);
+        }
+        
+        if (molstarDataLink) {
+            var molstarLink = 'https://molstar.org/viewer?mvs-url=' + encodeURIComponent(molstarDataLink) + '&mvs-format=' + encodeURIComponent(format || 'mvsj'); 
+            document.getElementById('open-in-molstar-link').setAttribute('href', molstarLink);
+            document.getElementById('open-in-molstar').style.display = 'inline';
+        }
+        
+        if (editInStoriesUrl) {
+            document.getElementById('open-in-stories-link').setAttribute('href', editInStoriesUrl);
+            document.getElementById('open-in-stories').style.display = 'inline';
+        }
+
+        document.getElementById('mvs-data').addEventListener('click', (e) => {
+            e.preventDefault();
+            mvsStories.downloadCurrentStory({ contextName: 'story1' });
+        });
     </script>
+    <!-- __MOLSTAR_ANALYTICS__ -->
 </body>
 
 </html>

src/apps/mvs-stories/index.tsx

@@ -7,6 +7,7 @@
 import { getMVSStoriesContext } from './context';
 import './elements';
 import { MVSData } from '../../extensions/mvs/mvs-data';
+import { download } from '../../mol-util/download';
 
 import './favicon.ico';
 import '../../mol-plugin-ui/skin/light.scss';
@@ -37,4 +38,27 @@ export function loadFromData(data: MVSData | string | Uint8Array, options?: { fo
     }, 0);
 }
 
+function getStoryUrlFromId(id: string, format: 'mvsx' | 'mvsj' = 'mvsj') {
+    return `https://stories.molstar.org/api/story/${id}/data`;
+}
+
+export function loadFromID(id: string, options?: { format?: 'mvsx' | 'mvsj', contextName?: string }) {
+    loadFromURL(
+        getStoryUrlFromId(id, options?.format),
+        { format: options?.format ?? 'mvsj', contextName: options?.contextName },
+    );
+}
+
+export function downloadCurrentStory(options?: { contextName?: string, filename?: string }) {
+    const story = getContext(options?.contextName).state.currentStoryData.value;
+    if (!story) return;
+
+    const isMVSJ = typeof story === 'string';
+    const filename = `${options?.filename ?? 'story'}.${isMVSJ ? 'mvsj' : 'mvsx'}`;
+    download(
+        new Blob([typeof story === 'string' ? story : story.buffer], { type: isMVSJ ? 'application/json' : 'application/octet-stream' }),
+        filename
+    );
+};
+
 export { MVSData };

src/apps/mvs-stories/styles.scss

@@ -1,3 +1,5 @@
+@use '../../mol-plugin-ui/skin/base/components/markdown.scss';
+
 .mvs-stories-markdown-explanation {
     // Adapted from skeleton.css, The MIT License (MIT), Copyright (c) 2011-2014 Dave Gamache 
     line-height: 1.4;
@@ -161,6 +163,34 @@
         border-width: 0;
         border-top: 1px solid #E1E1E1;
     }
+
+    table {
+        border: 1px solid #E1E1E1;
+        border-collapse: collapse;
+    }
+
+    th {
+        text-align: left;
+    }
+
+    th, td {
+        border: 1px solid #E1E1E1;
+        padding: 4px 8px;
+    }
+
+    img {
+        max-width: 100%;
+        height: auto;
+    }
+
+    a {
+        text-decoration: none;
+        color: #1d4ed7;
+
+        &:hover {
+            text-decoration: underline;
+        }
+    }
 }
 
 @media (orientation:portrait) {

src/apps/mvs-stories/version.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+export const VERSION = 1;

src/apps/viewer/app.ts

@@ -109,8 +109,10 @@ const DefaultViewerOptions = {
     resolutionMode: PluginConfig.General.ResolutionMode.defaultValue,
     illumination: false,
 
-    viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
+    viewportShowReset: PluginConfig.Viewport.ShowReset.defaultValue,
+    viewportShowScreenshotControls: PluginConfig.Viewport.ShowScreenshotControls.defaultValue,
     viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
+    viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
     viewportShowSettings: PluginConfig.Viewport.ShowSettings.defaultValue,
     viewportShowSelectionMode: PluginConfig.Viewport.ShowSelectionMode.defaultValue,
     viewportShowAnimation: PluginConfig.Viewport.ShowAnimation.defaultValue,
@@ -187,8 +189,10 @@ export class Viewer {
                 [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
                 [PluginConfig.General.PowerPreference, o.powerPreference],
                 [PluginConfig.General.ResolutionMode, o.resolutionMode],
-                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
+                [PluginConfig.Viewport.ShowReset, o.viewportShowReset],
+                [PluginConfig.Viewport.ShowScreenshotControls, o.viewportShowScreenshotControls],
                 [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
+                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
                 [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
                 [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
                 [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],

src/cli/state-docs/pd-to-md.ts

@@ -43,7 +43,7 @@ function paramInfo(param: PD.Any, offset: number): string {
     }
 }
 
-function oToS(options: readonly (readonly [string, string] | readonly [string, string, string | undefined])[]) {
+function oToS(options: readonly PD.SelectOption<any>[]) {
     return options.map(o => `'${o[0]}'`).join(', ');
 }
 

src/examples/ligand-editor/index.tsx

@@ -30,8 +30,8 @@ import { ExampleMol } from './example-data';
 import './index.html';
 import { jsonCifToMolfile } from './molfile';
 import { RGroupName } from './r-groups';
-import { SingleTaskQueue } from './utils';
 import { molfileToJSONCif } from '../../extensions/json-cif/utils';
+import { SingleTaskQueue } from '../../mol-util/single-task-queue';
 
 async function init(target: HTMLElement | string, molfile: string = ExampleMol) {
     const root = typeof target === 'string' ? document.getElementById(target)! : target;

src/examples/mvs-stories/index.html

@@ -98,14 +98,14 @@
 
 <body>
     <div id="viewer">
-        <mvs-stories-viewer />
+        <mvs-stories-viewer></mvs-stories-viewer>
     </div>
     <div id="controls">
         <div id="select-story" class="select-story"></div>
-        <mvs-stories-snapshot-markdown style="flex-grow: 1;" />
+        <mvs-stories-snapshot-markdown style="flex-grow: 1;"></mvs-stories-snapshot-markdown>
     </div>
     <div id="links">
-        <a href="#" id="mvs-data" filename="kinase-story.mvsj">Download MVS State</a> | <a href="https://github.com/molstar/molstar/tree/master/src/examples/mvs-stories" id="mvs-data" target="_blank" rel="noopener noreferrer">Source Code</a>
+        <a href="#" id="mvs-data">Download MVS State</a> | <a href="https://github.com/molstar/molstar/tree/master/src/examples/mvs-stories" id="mvs-data" target="_blank" rel="noopener noreferrer">Source Code</a>
     </div>
 
     <script>
@@ -118,6 +118,7 @@
             window.initStories();
         }, 0);
     </script>
+    <!-- __MOLSTAR_ANALYTICS__ -->
 </body>
 
 </html>

src/examples/mvs-stories/stories/animation.ts

@@ -0,0 +1,360 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { MVSData_States } from '../../../extensions/mvs/mvs-data';
+import { createMVSBuilder, Structure as MVSStructure, Root } from '../../../extensions/mvs/tree/mvs/mvs-builder';
+import { MVSNodeParams } from '../../../extensions/mvs/tree/mvs/mvs-tree';
+import { ColorT } from '../../../extensions/mvs/tree/mvs/param-types';
+import { Mat4 } from '../../../mol-math/linear-algebra';
+
+const Colors = {
+    '1cbs': '#4577B2' as ColorT,
+
+    'ligand-away': '#F3794C' as ColorT,
+    'ligand-docked': '#B9E3A0' as ColorT,
+};
+
+const Steps = [
+    {
+        header: 'Animation Demo',
+        key: 'intro',
+        description: `### Molecular Animation
+A story showcasing MolViewSpec animation capabilities.
+
+[\[**🔄 Replay Intro**\]](!play-transition)
+[\[**⏵ Play Snapshots**\]](!play-snapshots)
+[\[**⏹ Stop Animation**\]](!stop-animation)
+
+[\[**➡️ Next Snapshot**\]](!next-snapshot)
+
+`,
+        linger_duration_ms: 2000,
+        transition_duration_ms: 500,
+        state: (): Root => {
+            const builder = createMVSBuilder();
+
+            const _1cbs = structure(builder, '1cbs');
+            polymer(_1cbs, { color: Colors['1cbs'] });
+
+            const prims = _1cbs.primitives({
+                ref: 'prims',
+                label_opacity: 0,
+            });
+            prims.label({ text: 'Animation Demo', position: { label_asym_id: 'A' }, label_size: 10 });
+
+            const anim = builder.animation({
+                custom: {
+                    molstar_trackball: {
+                        name: 'rock',
+                        params: { speed: 0.5 },
+                    }
+                }
+            });
+            anim.interpolate({
+                kind: 'scalar',
+                ref: 'prims-opacity',
+                target_ref: 'prims',
+                start_ms: 500,
+                duration_ms: 500,
+                property: 'label_opacity',
+                end: 1,
+            });
+
+            anim.interpolate({
+                kind: 'scalar',
+                ref: 'prims-opacity',
+                target_ref: 'prims',
+                start_ms: 1500,
+                duration_ms: 500,
+                property: 'label_opacity',
+                start: 1,
+                end: 0.66,
+            });
+
+
+            // Uncomment this to make 2nd frame render much faster
+            // It will cause shader compilation to happen during the 1st snapshot
+
+            // const surface = poly.representation({
+            //     type: 'surface',
+            //     surface_type: 'gaussian',
+            // }).opacity({ opacity: 0 });
+
+            // _1cbs.component({ selector: 'ligand' })
+            //     .representation({ type: 'ball_and_stick' })
+            //     .opacity({ opacity: 0 });
+
+            // surface.clip({
+            //     ref: 'clip',
+            //     type: 'plane',
+            //     point: [22.0, 15, 0],
+            //     normal: [0, 0, 1],
+            // });
+
+            return builder;
+        },
+        camera: {
+            position: [-11.49, -37.05, 15.78],
+            target: [15.85, 17.26, 24.32],
+            up: [-0.88, 0.4, 0.26],
+        } satisfies MVSNodeParams<'camera'>,
+    },
+    {
+        header: 'Ligand Docking',
+        description: `Animate ligand moving to the binding site`,
+        linger_duration_ms: 2500,
+        transition_duration_ms: 500,
+        state: (): Root => {
+            const builder = createMVSBuilder();
+
+            const _1cbs = structure(builder, '1cbs');
+            const [poly,] = polymer(_1cbs, { color: Colors['1cbs'] });
+
+            const surface = poly.representation({
+                type: 'surface',
+                surface_type: 'gaussian',
+            });
+
+            _1cbs.component({ selector: 'ligand' })
+                .transform({
+                    ref: 'xform',
+                    translation: [5, 20, -20],
+                    rotation: [1, 0, 0, 0, 1, 0, 0, 0, 1],
+                    rotation_center: 'centroid',
+                })
+                .representation({ type: 'ball_and_stick' })
+                .color({ ref: 'ligand-color', color: 'red' });
+
+            surface.clip({
+                ref: 'clip',
+                type: 'plane',
+                point: [22.0, 15, 0],
+                normal: [0, 0, 1],
+            });
+
+            const anim = builder.animation();
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'clip',
+                duration_ms: 500,
+                property: ['point', 2],
+                end: 55,
+                easing: 'sin-in',
+            });
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'clip',
+                start_ms: 600,
+                duration_ms: 800,
+                property: ['point', 2],
+                end: 0,
+                easing: 'sin-out',
+            });
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'clip',
+                start_ms: 1500,
+                duration_ms: 500,
+                property: ['point', 2],
+                end: 55,
+            });
+
+            anim.interpolate({
+                kind: 'vec3',
+                target_ref: 'xform',
+                duration_ms: 2000,
+                property: 'translation',
+                end: [0, 0, 0],
+                noise_magnitude: 1,
+            });
+
+            anim.interpolate({
+                kind: 'rotation_matrix',
+                target_ref: 'xform',
+                duration_ms: 2000,
+                property: 'rotation',
+                noise_magnitude: 0.2,
+            });
+
+            anim.interpolate({
+                kind: 'color',
+                target_ref: 'ligand-color',
+                duration_ms: 2000,
+                property: 'color',
+                end: Colors['ligand-docked'],
+            });
+
+            return builder;
+        },
+        camera: {
+            position: [-30.63, 77.29, 2.28],
+            target: [19.16, 26.15, 22.82],
+            up: [0.69, 0.71, 0.09],
+        } satisfies MVSNodeParams<'camera'>,
+    },
+    {
+        header: 'Highlight & Opacity',
+        description: `Animate emissive, opacity and transform properties`,
+        linger_duration_ms: 2000,
+        transition_duration_ms: 0,
+        state: (): Root => {
+            const builder = createMVSBuilder();
+
+            const _1cbs = structure(builder, '1cbs');
+            const [poly,] = polymer(_1cbs, { color: Colors['1cbs'] });
+
+            poly.representation({
+                type: 'surface',
+                surface_type: 'gaussian'
+            }).opacity({ ref: 'opacity', opacity: 1 }).color({ ref: 'surface-color', color: 'white' });
+
+            _1cbs.component({ selector: 'ligand' })
+                .transform({ ref: 'xform', translation: [0, 0, 0] })
+                .representation({
+                    ref: 'repr',
+                    type: 'ball_and_stick',
+                    custom: {
+                        molstar_representation_params: {
+                            emissive: 0,
+                        }
+                    }
+                })
+                .color({ color: Colors['ligand-docked'] });
+
+            const primitives = builder.primitives({
+                ref: 'primitives',
+                instances: [
+                    Mat4.identity()
+                ],
+                opacity: 0,
+            });
+
+            primitives.ellipsoid({
+                center: [0, 0, 0],
+                radius: [2, 3, 2.5],
+                color: 'red'
+            });
+
+            const anim = builder.animation();
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'repr',
+                duration_ms: 1000,
+                property: ['custom', 'molstar_representation_params', 'emissive'],
+                end: 0.2,
+            });
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'opacity',
+                duration_ms: 1000,
+                frequency: 2,
+                alternate_direction: true,
+                property: 'opacity',
+                end: 0,
+            });
+
+            anim.interpolate({
+                kind: 'transform_matrix',
+                target_ref: 'primitives',
+                property: ['instances', 0],
+                translation_start: [20.24, 29.64, 14.85],
+                translation_end: [21.84, 21.71, 27.04],
+                translation_frequency: 4,
+                pivot: [0, 0, 0],
+                rotation_noise_magnitude: 0.2,
+                scale_end: [0.01, 0.01, 0.01],
+                duration_ms: 1000,
+            });
+
+            anim.interpolate({
+                kind: 'scalar',
+                target_ref: 'primitives',
+                duration_ms: 1000,
+                property: 'opacity',
+                end: 1,
+            });
+
+
+            anim.interpolate({
+                kind: 'color',
+                target_ref: 'surface-color',
+                duration_ms: 2000,
+                property: 'color',
+                palette: {
+                    kind: 'continuous',
+                    colors: ['white', Colors['1cbs'], 'white'],
+                }
+            });
+
+            return builder;
+        },
+        camera: {
+            position: [6.92, 47.17, 10.68],
+            target: [21.79, 22.2, 23.43],
+            up: [0.8, 0.57, 0.2],
+        } satisfies MVSNodeParams<'camera'>,
+    }
+];
+
+function structure(builder: Root, id: string): MVSStructure {
+    return builder
+        .download({ url: pdbUrl(id) })
+        .parse({ format: 'bcif' })
+        .modelStructure();
+}
+
+function polymer(structure: MVSStructure, options: { color: ColorT }) {
+    const component = structure.component({ selector: { label_asym_id: 'A' } });
+    const reprensentation = component.representation({ type: 'cartoon' });
+    reprensentation.color({ color: options.color });
+    return [component, reprensentation] as const;
+}
+
+function pdbUrl(id: string) {
+    return `https://www.ebi.ac.uk/pdbe/entry-files/download/${id.toLowerCase()}.bcif`;
+}
+
+export function buildStory(): MVSData_States {
+    const snapshots = Steps.map((s, i) => {
+        const builder = s.state();
+        if (s.camera) builder.camera(s.camera);
+
+        builder.canvas({
+            custom: {
+                molstar_postprocessing: {
+                    enable_outline: true,
+                    enable_ssao: true,
+                }
+            }
+        });
+
+        const description = i > 0 ? `${s.description}\n\n[Go to start](#intro)` : s.description;
+
+        return builder.getSnapshot({
+            title: s.header,
+            key: s.key,
+            description,
+            description_format: 'markdown',
+            linger_duration_ms: s.linger_duration_ms ?? 500,
+            transition_duration_ms: s.transition_duration_ms ?? 1000,
+        });
+    });
+
+    return {
+        kind: 'multiple',
+        snapshots,
+        metadata: {
+            title: 'Animation Showcase',
+            version: '1.0',
+            timestamp: new Date().toISOString(),
+        }
+    };
+}

src/examples/mvs-stories/stories/index.ts

@@ -6,8 +6,14 @@
 
 import { buildStory as kinase } from './kinase';
 import { buildStory as tbp } from './tbp';
+import { buildStory as animation } from './animation';
+import { buildStory as audio } from './audio';
+import { buildStory as motm1 } from './motm1';
 
 export const Stories = [
     { id: 'kinase', name: 'BCR-ABL: A Kinase Out of Control', buildStory: kinase },
     { id: 'tata', name: 'TATA-Binding Protein and its Role in Transcription Initiation ', buildStory: tbp },
+    { id: 'motm1', name: 'RCSB Molecule of the Month #1', buildStory: motm1 },
+    { id: 'animation-example', name: 'Molecular Animation Example', buildStory: animation },
+    { id: 'audio-example', name: 'Audio Playback Example', buildStory: audio },
 ] as const;

src/extensions/alpha-orbitals/data-model.ts

@@ -62,7 +62,6 @@ export interface CubeGrid {
 
 export type CubeGridFormat = ModelFormat<CubeGrid>;
 
-// eslint-disable-next-line
 export function CubeGridFormat(grid: CubeGrid): CubeGridFormat {
     return { name: 'custom grid', kind: 'cube-grid', data: grid };
 }

src/extensions/alpha-orbitals/transforms.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
@@ -18,7 +18,7 @@ import { StateTransformer } from '../../mol-state';
 import { VolumeRepresentation3DHelpers } from '../../mol-plugin-state/transforms/representation';
 import { AlphaOrbital, Basis, CubeGrid, CubeGridFormat, isCubeGridData } from './data-model';
 import { createSphericalCollocationDensityGrid } from './density';
-import { Tensor } from '../../mol-math/linear-algebra';
+import { Mat4, Tensor } from '../../mol-math/linear-algebra';
 import { Theme } from '../../mol-theme/theme';
 
 export class BasisAndOrbitals extends PluginStateObject.Create<{ basis: Basis, order: SphericalBasisOrder, orbitals: AlphaOrbital[] }>({ name: 'Basis', typeClass: 'Object' }) { }
@@ -114,6 +114,7 @@ export const CreateOrbitalVolume = PluginStateTransform.BuiltIn({
             }, a.data.orbitals[params.index], plugin.canvas3d?.webgl).runInContext(ctx);
             const volume: Volume = {
                 grid: data.grid,
+                instances: [{ transform: Mat4.identity() }],
                 sourceData: CubeGridFormat(data),
                 customProperties: new CustomProperties(),
                 _propertyData: Object.create(null),
@@ -146,6 +147,7 @@ export const CreateOrbitalDensityVolume = PluginStateTransform.BuiltIn({
             }, a.data.orbitals, plugin.canvas3d?.webgl).runInContext(ctx);
             const volume: Volume = {
                 grid: data.grid,
+                instances: [{ transform: Mat4.identity() }],
                 sourceData: CubeGridFormat(data),
                 customProperties: new CustomProperties(),
                 _propertyData: Object.create(null),

src/extensions/dnatco/confal-pyramids/behavior.ts

@@ -47,11 +47,12 @@ export const ConfalPyramidsPreset = StructureRepresentationPresetProvider({
     }
 });
 
+const RemoveNewline = /\r?\n/g;
 export function confalPyramidLabel(step: DnatcoTypes.Step) {
     return `
         <b>${step.auth_asym_id_1}</b> |
         <b>${step.label_comp_id_1} ${step.auth_seq_id_1}${step.PDB_ins_code_1}${step.label_alt_id_1.length > 0 ? ` (alt ${step.label_alt_id_1})` : ''}
            ${step.label_comp_id_2} ${step.auth_seq_id_2}${step.PDB_ins_code_2}${step.label_alt_id_2.length > 0 ? ` (alt ${step.label_alt_id_2})` : ''} </b><br />
         <i>NtC:</i> ${step.NtC} | <i>Confal score:</i> ${step.confal_score} | <i>RMSD:</i> ${step.rmsd.toFixed(2)}
-    `;
+    `.replace(RemoveNewline, '');
 }

src/extensions/dnatco/ntc-tube/behavior.ts

@@ -47,11 +47,12 @@ export const NtCTubePreset = StructureRepresentationPresetProvider({
     }
 });
 
+const RemoveNewline = /\r?\n/g;
 export function NtCTubeSegmentLabel(step: DnatcoTypes.Step) {
     return `
         <b>${step.auth_asym_id_1}</b> |
         <b>${step.label_comp_id_1} ${step.auth_seq_id_1}${step.PDB_ins_code_1}${step.label_alt_id_1.length > 0 ? ` (alt ${step.label_alt_id_1})` : ''}
            ${step.label_comp_id_2} ${step.auth_seq_id_2}${step.PDB_ins_code_2}${step.label_alt_id_2.length > 0 ? ` (alt ${step.label_alt_id_2})` : ''} </b><br />
         <i>NtC:</i> ${step.NtC} | <i>Confal score:</i> ${step.confal_score} | <i>RMSD:</i> ${step.rmsd.toFixed(2)}
-    `;
+    `.replace(RemoveNewline, '');
 }

src/extensions/mvs/behavior.ts

@@ -12,9 +12,10 @@ import { LociLabelProvider } from '../../mol-plugin-state/manager/loci-label';
 import { PluginBehavior } from '../../mol-plugin/behavior/behavior';
 import { PluginContext } from '../../mol-plugin/context';
 import { StructureRepresentationProvider } from '../../mol-repr/structure/representation';
-import { StateAction } from '../../mol-state';
+import { StateAction, StateObjectCell, StateTree } from '../../mol-state';
 import { Task } from '../../mol-task';
 import { ColorTheme } from '../../mol-theme/color';
+import { fileToDataUri } from '../../mol-util/file';
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
 import { MVSAnnotationColorThemeProvider } from './components/annotation-color-theme';
 import { MVSAnnotationLabelRepresentationProvider } from './components/annotation-label/representation';
@@ -109,6 +110,39 @@ export const MolViewSpec = PluginBehavior.create<{ autoAttach: boolean }>({
             for (const action of this.registrables.actions ?? []) {
                 this.ctx.state.data.actions.add(action);
             }
+
+            this.ctx.managers.markdownExtensions.registerRefResolver('mvs', (plugin, refs) => {
+                const mvsRefs = new Set(refs.map(ref => `mvs-ref:${ref}`));
+                return StateTree.doPreOrder(
+                    plugin.state.data.tree,
+                    plugin.state.data.tree.root,
+                    { mvsRefs, plugin, cells: [] as StateObjectCell[] },
+                    (n, _, s) => {
+                    if (!n.tags) return;
+                    for (const tag of n.tags) {
+                        if (!s.mvsRefs.has(tag)) continue;
+                        const cell = s.plugin.state.data.cells.get(n.ref);
+                        if (cell) {
+                            s.cells.push(cell);
+                            break;
+                        }
+                    }
+                }).cells;
+            });
+
+            this.ctx.managers.markdownExtensions.registerUriResolver('mvs', (plugin, uri) => {
+                const { assets } = plugin.managers.asset;
+                const asset = assets.find(a => a.file.name === uri);
+                if (!asset) {
+                    return undefined;
+                }
+                try {
+                    return fileToDataUri(asset.file);
+                } catch (e) {
+                    console.error(`MVS: Failed to convert asset file to data URI for '${uri}'`, e);
+                    return undefined;
+                }
+            });
         }
         update(p: { autoAttach: boolean }) {
             const updated = this.params.autoAttach !== p.autoAttach;
@@ -146,6 +180,7 @@ export const MolViewSpec = PluginBehavior.create<{ autoAttach: boolean }>({
             for (const action of this.registrables.actions ?? []) {
                 this.ctx.state.data.actions.remove(action);
             }
+            this.ctx.managers.markdownExtensions.removeRefResolver('mvs');
         }
     },
     params: () => ({

src/extensions/mvs/camera.ts

@@ -6,18 +6,27 @@
  */
 
 import { Camera } from '../../mol-canvas3d/camera';
-import { Canvas3DParams, Canvas3DProps } from '../../mol-canvas3d/canvas3d';
+import { CameraFogParams, Canvas3DParams, Canvas3DProps, DefaultCanvas3DParams } from '../../mol-canvas3d/canvas3d';
+import { TrackballControlsParams } from '../../mol-canvas3d/controls/trackball';
+import { BloomParams } from '../../mol-canvas3d/passes/bloom';
+import { DofParams } from '../../mol-canvas3d/passes/dof';
+import { OutlineParams } from '../../mol-canvas3d/passes/outline';
+import { ShadowParams } from '../../mol-canvas3d/passes/shadow';
+import { SsaoParams } from '../../mol-canvas3d/passes/ssao';
 import { Vec3 } from '../../mol-math/linear-algebra';
 import { getFocusSnapshot, getPluginBoundingSphere } from '../../mol-plugin-state/manager/focus-camera/focus-object';
 import { PluginCommands } from '../../mol-plugin/commands';
 import { PluginContext } from '../../mol-plugin/context';
 import { PluginState } from '../../mol-plugin/state';
 import { StateObjectSelector } from '../../mol-state';
+import { fovAdjustedPosition } from '../../mol-util/camera';
 import { ColorNames } from '../../mol-util/color/names';
+import { ParamDefinition } from '../../mol-util/param-definition';
 import { decodeColor } from './helpers/utils';
 import { MolstarLoadingContext } from './load';
 import { SnapshotMetadata } from './mvs-data';
-import { MolstarNodeParams } from './tree/molstar/molstar-tree';
+import { MVSAnimationNode } from './tree/animation/animation-tree';
+import { MolstarNode, MolstarNodeParams } from './tree/molstar/molstar-tree';
 import { MVSTreeSchema } from './tree/mvs/mvs-tree';
 
 
@@ -98,24 +107,6 @@ function resetSceneRadiusFactor(plugin: PluginContext) {
     plugin.canvas3d?.setProps({ sceneRadiusFactor });
 }
 
-/** Return the distance adjustment ratio for conversion from the "reference camera"
- * to a camera with an arbitrary field of view `fov`. */
-function distanceAdjustment(mode: Camera.Mode, fov: number) {
-    if (mode === 'orthographic') return 1 / (2 * Math.tan(fov / 2));
-    else return 1 / (2 * Math.sin(fov / 2));
-}
-
-/** Return the position for a camera with an arbitrary field of view `fov`
- * necessary to just fit into view the same sphere (with center at `target`)
- * as the "reference camera" placed at `refPosition` would fit, while keeping the camera orientation.
- * The "reference camera" is a camera which can just fit into view a sphere of radius R with center at distance 2R
- * (this corresponds to FOV = 2 * asin(1/2) in perspective mode or FOV = 2 * atan(1/2) in orthographic mode). */
-function fovAdjustedPosition(target: Vec3, refPosition: Vec3, mode: Camera.Mode, fov: number) {
-    const delta = Vec3.sub(Vec3(), refPosition, target);
-    const adjustment = distanceAdjustment(mode, fov);
-    return Vec3.scaleAndAdd(delta, target, delta, adjustment); // return target + delta * adjustment
-}
-
 /** Create object for PluginState.Snapshot.camera based on tree loading context and MVS snapshot metadata */
 export function createPluginStateSnapshotCamera(plugin: PluginContext, context: MolstarLoadingContext, metadata: SnapshotMetadata & { previousTransitionDurationMs?: number }): PluginState.Snapshot['camera'] {
     const camera: PluginState.Snapshot['camera'] = {
@@ -132,19 +123,93 @@ export function createPluginStateSnapshotCamera(plugin: PluginContext, context:
     return camera;
 }
 
-/** Set canvas properties based on a canvas node params. */
-export function setCanvas(plugin: PluginContext, params: MolstarNodeParams<'canvas'> | undefined) {
-    plugin.canvas3d?.setProps(old => modifyCanvasProps(old, params));
+function optionalParams(enable: boolean | undefined, values: any, params: ParamDefinition.Params, fallback: any) {
+    if (typeof enable === 'boolean') {
+        return enable
+            ? { name: 'on', params: { ...ParamDefinition.getDefaultValues(params), ...values } }
+            : { name: 'off', params: {} };
+    }
+    return fallback;
 }
 
 /** Create a deep copy of `oldCanvasProps` with values modified according to a canvas node params. */
-export function modifyCanvasProps(oldCanvasProps: Canvas3DProps, params: MolstarNodeParams<'canvas'> | undefined): Canvas3DProps {
+export function modifyCanvasProps(oldCanvasProps: Canvas3DProps, canvasNode: MolstarNode<'canvas'> | undefined, animationNode: MVSAnimationNode<'animation'> | undefined): Canvas3DProps {
+    const params = canvasNode?.params;
     const backgroundColor = decodeColor(params?.background_color) ?? DefaultCanvasBackgroundColor;
+
+    const molstar_postprocessing = canvasNode?.custom?.molstar_postprocessing;
+
+    const outline = molstar_postprocessing?.enable_outline;
+    const outlineParams = molstar_postprocessing?.outline_params;
+
+    const shadow = molstar_postprocessing?.enable_shadow;
+    const shadowParams = molstar_postprocessing?.shadow_params;
+
+    const occlusion = molstar_postprocessing?.enable_ssao;
+    const occlusionParams = molstar_postprocessing?.ssao_params;
+
+    const fog = molstar_postprocessing?.enable_fog;
+    const fogParams = molstar_postprocessing?.fog_params;
+
+    const dof = molstar_postprocessing?.enable_depth_of_field;
+    const dofParams = molstar_postprocessing?.depth_of_field_params;
+
+    const bloom = molstar_postprocessing?.enable_bloom;
+    const bloomParams = molstar_postprocessing?.bloom_params;
+
+    const trackballAnimation = animationNode?.custom?.molstar_trackball;
+    const trackballAnimationName = trackballAnimation?.name;
+    const trackballAnimationParams = trackballAnimation?.params ?? {};
+
     return {
         ...oldCanvasProps,
+        postprocessing: {
+            ...oldCanvasProps.postprocessing,
+            outline: optionalParams(outline, outlineParams, OutlineParams, oldCanvasProps.postprocessing.outline),
+            shadow: optionalParams(shadow, shadowParams, ShadowParams, oldCanvasProps.postprocessing.shadow),
+            occlusion: optionalParams(occlusion, occlusionParams, SsaoParams, oldCanvasProps.postprocessing.occlusion),
+            dof: optionalParams(dof, dofParams, DofParams, oldCanvasProps.postprocessing.dof),
+            bloom: optionalParams(bloom, bloomParams, BloomParams, oldCanvasProps.postprocessing.bloom),
+        },
+        cameraFog: optionalParams(fog, fogParams, CameraFogParams, oldCanvasProps.cameraFog),
         renderer: {
             ...oldCanvasProps.renderer,
             backgroundColor: backgroundColor,
         },
+        trackball: {
+            ...oldCanvasProps?.trackball,
+            ...(trackballAnimationName
+                ? {
+                    animate: {
+                        name: trackballAnimationName,
+                        params: {
+                            ...TrackballControlsParams.animate.map(trackballAnimationName)?.defaultValue,
+                            ...trackballAnimationParams
+                        }
+                    }
+                }
+                : {}
+            ),
+        }
     };
 }
+
+export function resetCanvasProps(plugin: PluginContext) {
+    const old = plugin.canvas3d?.props;
+    plugin.canvas3d?.setProps({
+        ...old,
+        postprocessing: {
+            ...old,
+            outline: DefaultCanvas3DParams.postprocessing.outline,
+            shadow: DefaultCanvas3DParams.postprocessing.shadow,
+            occlusion: DefaultCanvas3DParams.postprocessing.occlusion,
+            dof: DefaultCanvas3DParams.postprocessing.dof,
+            bloom: DefaultCanvas3DParams.postprocessing.bloom,
+        },
+        cameraFog: DefaultCanvas3DParams.cameraFog,
+        trackball: {
+            ...old?.trackball,
+            animate: { name: 'off', params: {} },
+        }
+    });
+}

src/extensions/mvs/components/annotation-color-theme.ts

@@ -1,32 +1,85 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
 
+import { SortedArray } from '../../../mol-data/int';
 import { Location } from '../../../mol-model/location';
 import { Bond, StructureElement } from '../../../mol-model/structure';
 import type { ColorTheme, LocationColor } from '../../../mol-theme/color';
 import type { ThemeDataContext } from '../../../mol-theme/theme';
+import { Color } from '../../../mol-util/color';
 import { ColorNames } from '../../../mol-util/color/names';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { MaybeFloatParamDefinition } from '../helpers/param-definition';
 import { decodeColor } from '../helpers/utils';
-import { getMVSAnnotationForStructure } from './annotation-prop';
+import { getMVSAnnotationForStructure, MVSAnnotation } from './annotation-prop';
 import { isMVSStructure } from './is-mvs-model-prop';
 
 
+export const MVSCategoricalPaletteParams = {
+    colors: PD.MappedStatic('list', {
+        list: PD.ColorList('category-10', { description: 'List of colors.', presetKind: 'set' }),
+        dictionary: PD.ObjectList({
+            value: PD.Text(),
+            color: PD.Color(ColorNames.white),
+        }, e => `${e.value}: ${Color.toHexStyle(e.color)}`, { description: 'Mapping of annotation values to colors.' }),
+    }),
+    repeatColorList: PD.Boolean(false, { hideIf: g => g.colors.name !== 'list', description: 'Repeat color list once all colors are depleted (only applies if `colors` is a list).' }),
+    sort: PD.Select('none', [['none', 'None'], ['lexical', 'Lexical'], ['numeric', 'Numeric']] as const, { hideIf: g => g.colors.name !== 'list', description: 'Sort actual annotation values before assigning colors from a list (none = take values in order of their first occurrence).' }),
+    sortDirection: PD.Select('ascending', [['ascending', 'Ascending'], ['descending', 'Descending']] as const, { hideIf: g => g.colors.name !== 'list', description: 'Sort direction.' }),
+    caseInsensitive: PD.Boolean(false, { description: 'Treat annotation values as case-insensitive strings.' }),
+    setMissingColor: PD.Boolean(false, { description: 'Allow setting a color for missing values.' }),
+    missingColor: PD.Color(ColorNames.white, { hideIf: g => !g.setMissingColor, description: 'Color to use when (a) `colors` is a dictionary and given key is not present, or (b) `color` is a list and there are more actual annotation values than listed colors and `repeat_color_list` is not true.' }),
+};
+export type MVSCategoricalPaletteParams = typeof MVSCategoricalPaletteParams
+export type MVSCategoricalPaletteProps = PD.Values<MVSCategoricalPaletteParams>
+
+export const MVSDiscretePaletteParams = {
+    colors: PD.ObjectList({
+        color: PD.Color(ColorNames.white),
+        fromValue: PD.Numeric(-Infinity),
+        toValue: PD.Numeric(Infinity),
+    }, e => `${Color.toHexStyle(e.color)} [${e.fromValue}, ${e.toValue}]`, { description: 'Mapping of annotation value ranges to colors.' }),
+    mode: PD.Select('normalized', [['normalized', 'Normalized'], ['absolute', 'Absolute']] as const, { description: 'Defines whether the annotation values should be normalized before assigning color based on checkpoints in `colors` (`x_normalized = (x - x_min) / (x_max - x_min)`, where `[x_min, x_max]` are either `value_domain` if provided, or the lowest and the highest value encountered in the annotation).' }),
+    xMin: MaybeFloatParamDefinition({ hideIf: g => g.mode !== 'normalized', placeholder: 'auto', description: 'Defines `x_min` for normalization of annotation values. If not provided, minimum of the actual values will be used. Only used when `mode` is `"normalized"' }),
+    xMax: MaybeFloatParamDefinition({ hideIf: g => g.mode !== 'normalized', placeholder: 'auto', description: 'Defines `x_max` for normalization of annotation values. If not provided, maximum of the actual values will be used. Only used when `mode` is `"normalized"' }),
+};
+export type MVSDiscretePaletteParams = typeof MVSDiscretePaletteParams
+export type MVSDiscretePaletteProps = PD.Values<MVSDiscretePaletteParams>
+
+export const MVSContinuousPaletteParams = {
+    colors: PD.ColorList('yellow-green', { description: 'List of colors, with optional checkpoints.', presetKind: 'scale', offsets: true }),
+    mode: PD.Select('normalized', [['normalized', 'Normalized'], ['absolute', 'Absolute']] as const, { description: 'Defines whether the annotation values should be normalized before assigning color based on checkpoints in `colors` (`x_normalized = (x - x_min) / (x_max - x_min)`, where `[x_min, x_max]` are either `value_domain` if provided, or the lowest and the highest value encountered in the annotation).' }),
+    xMin: MaybeFloatParamDefinition({ hideIf: g => g.mode !== 'normalized', placeholder: 'auto', description: 'Defines `x_min` for normalization of annotation values. If not provided, minimum of the actual values will be used. Only used when `mode` is `"normalized"' }),
+    xMax: MaybeFloatParamDefinition({ hideIf: g => g.mode !== 'normalized', placeholder: 'auto', description: 'Defines `x_max` for normalization of annotation values. If not provided, maximum of the actual values will be used. Only used when `mode` is `"normalized"' }),
+    setUnderflowColor: PD.Boolean(false, { description: 'Allow setting a color for values below the lowest checkpoint.' }),
+    underflowColor: PD.Color(ColorNames.white, { hideIf: g => !g.setUnderflowColor, description: 'Color for values below the lowest checkpoint.' }),
+    setOverflowColor: PD.Boolean(false, { description: 'Allow setting a color for values above the highest checkpoint.' }),
+    overflowColor: PD.Color(ColorNames.white, { hideIf: g => !g.setOverflowColor, description: 'Color for values above the highest checkpoint.' }),
+};
+export type MVSContinuousPaletteParams = typeof MVSContinuousPaletteParams
+export type MVSContinuousPaletteProps = PD.Values<MVSContinuousPaletteParams>
+
+
 /** Parameter definition for color theme "MVS Annotation" */
 export const MVSAnnotationColorThemeParams = {
     annotationId: PD.Text('', { description: 'Reference to "Annotation" custom model property' }),
     fieldName: PD.Text('color', { description: 'Annotation field (column) from which to take color values' }),
     background: PD.Color(ColorNames.gainsboro, { description: 'Color for elements without annotation' }),
+    palette: PD.MappedStatic('direct', {
+        'direct': PD.EmptyGroup(),
+        'categorical': PD.Group(MVSCategoricalPaletteParams),
+        'discrete': PD.Group(MVSDiscretePaletteParams),
+        'continuous': PD.Group(MVSContinuousPaletteParams),
+    }),
 };
 export type MVSAnnotationColorThemeParams = typeof MVSAnnotationColorThemeParams
 
 /** Parameter values for color theme "MVS Annotation" */
 export type MVSAnnotationColorThemeProps = PD.Values<MVSAnnotationColorThemeParams>
 
-
 /** Return color theme that assigns colors based on an annotation file.
  * The annotation file itself is handled by a custom model property (`MVSAnnotationsProvider`),
  * the color theme then just uses this property. */
@@ -36,9 +89,12 @@ export function MVSAnnotationColorTheme(ctx: ThemeDataContext, props: MVSAnnotat
     if (ctx.structure && !ctx.structure.isEmpty) {
         const { annotation } = getMVSAnnotationForStructure(ctx.structure, props.annotationId);
         if (annotation) {
+            const paletteFunction = makePaletteFunction(props.palette, annotation, props.fieldName);
+
             const colorForStructureElementLocation = (location: StructureElement.Location) => {
-                // if (annot.getAnnotationForLocation(location)?.color !== annot.getAnnotationForLocation_Reference(location)?.color) throw new Error('AssertionError');
-                return decodeColor(annotation?.getValueForLocation(location, props.fieldName)) ?? props.background;
+                const annotValue = annotation?.getValueForLocation(location, props.fieldName);
+                const color = annotValue !== undefined ? paletteFunction(annotValue) : undefined;
+                return color ?? props.background;
             };
             const auxLocation = StructureElement.Location.create(ctx.structure);
 
@@ -60,7 +116,7 @@ export function MVSAnnotationColorTheme(ctx: ThemeDataContext, props: MVSAnnotat
 
     return {
         factory: MVSAnnotationColorTheme,
-        granularity: 'group',
+        granularity: 'groupInstance',
         preferSmoothing: true,
         color: color,
         props: props,
@@ -79,3 +135,124 @@ export const MVSAnnotationColorThemeProvider: ColorTheme.Provider<MVSAnnotationC
     defaultValues: PD.getDefaultValues(MVSAnnotationColorThemeParams),
     isApplicable: (ctx: ThemeDataContext) => !!ctx.structure && isMVSStructure(ctx.structure),
 };
+
+
+function makePaletteFunction(props: MVSAnnotationColorThemeProps['palette'], annotation: MVSAnnotation, fieldName: string): (value: string) => Color | undefined {
+    if (props.name === 'direct') return decodeColor;
+    if (props.name === 'categorical') return makePaletteFunctionCategorical(props.params, annotation, fieldName);
+    if (props.name === 'discrete') return makePaletteFunctionDiscrete(props.params as MVSDiscretePaletteProps, annotation, fieldName);
+    if (props.name === 'continuous') return makePaletteFunctionContinuous(props.params as MVSContinuousPaletteProps, annotation, fieldName);
+    throw new Error(`NotImplementedError: makePaletteFunction for ${(props as any).name}`);
+}
+
+function makePaletteFunctionCategorical(props: MVSCategoricalPaletteProps, annotation: MVSAnnotation, fieldName: string): (value: string) => Color | undefined {
+    const colorMap: { [value: string]: Color } = {};
+    if (props.colors.name === 'dictionary') {
+        for (const { value, color } of props.colors.params) {
+            const key = props.caseInsensitive ? value.toUpperCase() : value;
+            colorMap[key] = color;
+        }
+    } else if (props.colors.name === 'list') {
+        const values = annotation.getDistinctValuesInField(fieldName, props.caseInsensitive);
+        if (props.sort === 'lexical') values.sort();
+        else if (props.sort === 'numeric') values.sort((a, b) => Number.parseFloat(a) - Number.parseFloat(b));
+        if (props.sortDirection === 'descending') values.reverse();
+
+        const colorList = props.colors.params.colors.map(Color.fromColorListEntry);
+        let next = 0;
+        for (const value of values) {
+            colorMap[value] = colorList[next++];
+            if (next >= colorList.length && props.repeatColorList) next = 0; // else will get index-out-of-range and assign undefined
+        }
+    }
+    const missingColor = props.setMissingColor ? props.missingColor : undefined;
+    if (props.caseInsensitive) {
+        return (value: string) => colorMap[value.toUpperCase()] ?? missingColor;
+    } else {
+        return (value: string) => colorMap[value] ?? missingColor;
+    }
+}
+
+function makePaletteFunctionDiscrete(props: MVSDiscretePaletteProps, annotation: MVSAnnotation, fieldName: string): (value: string) => Color | undefined {
+    if (props.colors.length === 0) return () => undefined;
+
+    const scale = makeNumericPaletteScale(props, annotation, fieldName);
+
+    return (value: string) => {
+        const xAbs = parseFloat(value);
+        if (isNaN(xAbs)) return undefined;
+        const x = scale(xAbs);
+
+        for (let i = props.colors.length - 1; i >= 0; i--) {
+            const { color, fromValue, toValue } = props.colors[i];
+            if (fromValue <= x && x <= toValue) return color;
+        }
+    };
+}
+
+function makePaletteFunctionContinuous(props: MVSContinuousPaletteProps, annotation: MVSAnnotation, fieldName: string): (value: string) => Color | undefined {
+    const { colors, checkpoints } = makeContinuousPaletteCheckpoints(props);
+    if (colors.length === 0) return () => undefined;
+
+    const scale = makeNumericPaletteScale(props, annotation, fieldName);
+    const underflowColor = props.setUnderflowColor ? props.underflowColor : undefined;
+    const overflowColor = props.setOverflowColor ? props.overflowColor : undefined;
+
+    return (value: string) => {
+        const xAbs = parseFloat(value);
+        if (isNaN(xAbs)) return undefined;
+        const x = scale(xAbs);
+        const gteIdx = SortedArray.findPredecessorIndex(checkpoints, x); // Index of the first greater or equal checkpoint
+        if (gteIdx === 0) {
+            if (x === checkpoints[0]) return colors[0];
+            else return underflowColor;
+        }
+        if (gteIdx === checkpoints.length) {
+            return overflowColor;
+        }
+        const q = (x - checkpoints[gteIdx - 1]) / (checkpoints[gteIdx] - checkpoints[gteIdx - 1]);
+        return Color.interpolate(colors[gteIdx - 1], colors[gteIdx], q);
+    };
+}
+
+function makeNumericPaletteScale(props: MVSContinuousPaletteProps | MVSDiscretePaletteProps, annotation: MVSAnnotation, fieldName: string): (x: number) => number {
+    if (props.mode === 'normalized') {
+        // Mode normalized
+        let xMin = props.xMin;
+        let xMax = props.xMax;
+        if (xMin === null || xMax === null) {
+            const values = annotation.getDistinctValuesInField(fieldName, false).map(parseFloat).filter(x => !isNaN(x));
+            if (values.length > 0) {
+                xMin ??= values.reduce((a, b) => a < b ? a : b); // xMin ??= min(values)
+                xMax ??= values.reduce((a, b) => a > b ? a : b); // xMax ??= max(values)
+            } else {
+                xMin ??= 0;
+                xMax ??= 1;
+            }
+        }
+        if (xMin === xMax) {
+            return x => (x < xMin ? -0.5 : x === xMin ? 0.5 : 1.5);
+        } else {
+            return x => (x - xMin) / (xMax - xMin);
+        }
+    } else {
+        // Mode absolute
+        return x => x;
+    }
+}
+
+export function makeContinuousPaletteCheckpoints(props: MVSContinuousPaletteProps) {
+    if (props.colors.colors.every(x => Array.isArray(x))) {
+        // Explicit checkpoints
+        const sorted = props.colors.colors.sort((a, b) => a[1] - b[1]);
+        const colors = sorted.map(Color.fromColorListEntry);
+        const checkpoints = SortedArray.ofSortedArray(sorted.map(t => t[1]));
+        return { colors, checkpoints };
+    } else {
+        // Auto checkpoints (linspace 0 to 1)
+        const colors = props.colors.colors.map(Color.fromColorListEntry);
+        const n = colors.length - 1;
+        const checkpoints = SortedArray.ofSortedArray(colors.map((_, i) => i / n));
+        return { colors, checkpoints };
+    }
+}

src/extensions/mvs/components/annotation-prop.ts

@@ -1,10 +1,10 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
 
-import { Column, Table } from '../../../mol-data/db';
+import { Column } from '../../../mol-data/db';
 import { CIF, CifBlock, CifCategory, CifFile } from '../../../mol-io/reader/cif';
 import { toTable } from '../../../mol-io/reader/cif/schema';
 import { MmcifFormat } from '../../../mol-model-formats/structure/mmcif';
@@ -13,19 +13,17 @@ import { CustomProperty } from '../../../mol-model-props/common/custom-property'
 import { CustomPropertyDescriptor } from '../../../mol-model/custom-property';
 import { Model } from '../../../mol-model/structure';
 import { Structure, StructureElement } from '../../../mol-model/structure/structure';
-import { UUID } from '../../../mol-util';
-import { arrayExtend } from '../../../mol-util/array';
 import { Asset } from '../../../mol-util/assets';
 import { Jsonable, canonicalJsonString } from '../../../mol-util/json';
-import { pickObjectKeys, promiseAllObj } from '../../../mol-util/object';
+import { objectOfArraysToArrayOfObjects, pickObjectKeysWithRemapping, promiseAllObj } from '../../../mol-util/object';
 import { Choice } from '../../../mol-util/param-choice';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 import { AtomRanges } from '../helpers/atom-ranges';
 import { IndicesAndSortings } from '../helpers/indexing';
 import { MaybeStringParamDefinition } from '../helpers/param-definition';
 import { MVSAnnotationRow, MVSAnnotationSchema, getCifAnnotationSchema } from '../helpers/schemas';
-import { atomQualifies, getAtomRangesForRow } from '../helpers/selections';
-import { Maybe, safePromise } from '../helpers/utils';
+import { getAtomRangesForRow } from '../helpers/selections';
+import { Maybe, isDefined, safePromise } from '../helpers/utils';
 
 
 /** Allowed values for the annotation format parameter */
@@ -50,7 +48,11 @@ export const MVSAnnotationsParams = {
                 index: PD.Group({ index: PD.Numeric(0, { min: 0, step: 1 }, { description: '0-based index of the block' }) }),
                 header: PD.Group({ header: PD.Text(undefined, { description: 'Block header' }) }),
             }, { description: 'Specify which CIF block contains annotation data (only relevant when format=cif or format=bcif)' }),
-            cifCategory: MaybeStringParamDefinition(undefined, { description: 'Specify which CIF category contains annotation data (only relevant when format=cif or format=bcif)' }),
+            cifCategory: MaybeStringParamDefinition({ placeholder: 'Take first category', description: 'Specify which CIF category contains annotation data (only relevant when format=cif or format=bcif)' }),
+            fieldRemapping: PD.ObjectList({
+                standardName: PD.Text('', { placeholder: ' ', description: 'Standard name of the selector field (e.g. label_asym_id)' }),
+                actualName: MaybeStringParamDefinition({ placeholder: 'Ignore field', description: 'Actual name of the field in the annotation data (e.g. spam_chain_id), null to ignore the field with standard name' }),
+            }, e => `"${e.standardName}": ${e.actualName === null ? 'null' : `"${e.actualName}"`}`, { description: 'Optional remapping of annotation field names { standardName1: actualName1, ... }. Use { "label_asym_id": "X" } to load actual field "X" as "label_asym_id". Use { "label_asym_id": null } to ignore actual field "label_asym_id". Fields not mentioned here are mapped implicitely (i.e. actual name = standard name).' }),
             id: PD.Text('', { description: 'Arbitrary identifier that can be referenced by MVSAnnotationColorTheme' }),
         },
         obj => obj.id
@@ -137,16 +139,26 @@ export function getMVSAnnotationForStructure(structure: Structure, annotationId:
     return { annotation: undefined, model: undefined };
 }
 
+type FieldRemapping = Record<string, string | null>;
+
+/** Mapping `ElementIndex` -> annotation row index for all elements in a `Model`.
+ * `-1` means no row applies to the element.
+ * `null` means no row applies to any element. */
+type IndexedModel = number[] | null;
+
 /** Main class for processing MVS annotation */
 export class MVSAnnotation {
-    /** Store mapping `ElementIndex` -> annotation row index for each `Model`, -1 means no row applies */
-    private indexedModels = new Map<UUID, number[]>();
-    private rows: MVSAnnotationRow[] | undefined = undefined;
+
+    /** Number of annotation rows. */
+    public nRows: number;
 
     constructor(
         public data: MVSAnnotationData,
         public schema: MVSAnnotationSchema,
-    ) { }
+        public fieldRemapping: FieldRemapping,
+    ) {
+        this.nRows = getRowCount(data);
+    }
 
     /** Create a new `MVSAnnotation` based on specification `spec`. Use `file` if provided, otherwise download the file.
      * Throw error if download fails or problem with data. */
@@ -165,7 +177,7 @@ export class MVSAnnotation {
                 switch (blockSpec.name) {
                     case 'header':
                         const foundBlock = file.data.blocks.find(b => b.header === blockSpec.params.header);
-                        if (!foundBlock) throw new Error(`CIF block with header ${blockSpec.params.header} not found`);
+                        if (!foundBlock) throw new Error(`CIF block with header "${blockSpec.params.header}" not found`);
                         block = foundBlock;
                         break;
                     case 'index':
@@ -176,32 +188,21 @@ export class MVSAnnotation {
                 const categoryName = spec.cifCategory ?? Object.keys(block.categories)[0];
                 if (!categoryName) throw new Error('There are no categories in CIF block');
                 const category = block.categories[categoryName];
-                if (!category) throw new Error(`CIF category ${categoryName} not found`);
+                if (!category) throw new Error(`CIF category "${categoryName}" not found`);
                 data = { format: 'cif', data: category };
                 break;
         }
-        return new MVSAnnotation(data, spec.schema);
+        return new MVSAnnotation(data, spec.schema, Object.fromEntries(spec.fieldRemapping.map(e => [e.standardName, e.actualName])));
     }
 
     static createEmpty(schema: MVSAnnotationSchema): MVSAnnotation {
-        return new MVSAnnotation({ format: 'json', data: [] }, schema);
-    }
-
-    /** Reference implementation of `getAnnotationForLocation`, just for checking, DO NOT USE DIRECTLY */
-    getAnnotationForLocation_Reference(loc: StructureElement.Location): MVSAnnotationRow | undefined {
-        const model = loc.unit.model;
-        const iAtom = loc.element;
-        let result: MVSAnnotationRow | undefined = undefined;
-        for (const row of this.getRows()) {
-            if (atomQualifies(model, iAtom, row)) result = row;
-        }
-        return result;
+        return new MVSAnnotation({ format: 'json', data: [] }, schema, {});
     }
 
     /** Return value of field `fieldName` assigned to location `loc`, if any */
     getValueForLocation(loc: StructureElement.Location, fieldName: string): string | undefined {
-        const indexedModel = this.getIndexedModel(loc.unit.model);
-        const iRow = indexedModel[loc.element];
+        const indexedModel = this.getIndexedModel(loc.unit.model, loc.unit.conformation.operator.instanceId);
+        const iRow = (indexedModel !== null) ? indexedModel[loc.element] : -1;
         return this.getValueForRow(iRow, fieldName);
     }
     /** Return value of field `fieldName` assigned to `i`-th annotation row, if any */
@@ -218,40 +219,69 @@ export class MVSAnnotation {
     }
 
     /** Return cached `ElementIndex` -> `MVSAnnotationRow` mapping for `Model` (or create it if not cached yet) */
-    private getIndexedModel(model: Model): number[] {
-        const key = model.id;
-        if (!this.indexedModels.has(key)) {
-            const result = this.getRowForEachAtom(model);
-            this.indexedModels.set(key, result);
+    private getIndexedModel(model: Model, instanceId: string): IndexedModel {
+        const key = this.hasInstanceIds() ? `${model.id}:${instanceId}` : model.id;
+        if (!this._indexedModels.has(key)) {
+            const result = this.getRowForEachAtom(model, instanceId);
+            this._indexedModels.set(key, result);
         }
-        return this.indexedModels.get(key)!;
+        return this._indexedModels.get(key)!;
     }
+    /** Cached `IndexedModel` per `Model.id` (if annotation contains no instanceIds)
+     * or per `Model.id:instanceId` combination (if at least one row contains instanceId). */
+    private _indexedModels = new Map<string, IndexedModel>();
 
     /** Create `ElementIndex` -> `MVSAnnotationRow` mapping for `Model` */
-    private getRowForEachAtom(model: Model): number[] {
+    private getRowForEachAtom(model: Model, instanceId: string): IndexedModel {
         const indices = IndicesAndSortings.get(model);
         const nAtoms = model.atomicHierarchy.atoms._rowCount;
-        const result: number[] = Array(nAtoms).fill(-1);
+        let result: IndexedModel = null;
         const rows = this.getRows();
         for (let i = 0, nRows = rows.length; i < nRows; i++) {
-            const atomRanges = getAtomRangesForRow(model, rows[i], indices);
-            AtomRanges.foreach(atomRanges, (from, to) => result.fill(i, from, to));
+            const row = rows[i];
+            const atomRanges = getAtomRangesForRow(row, model, instanceId, indices);
+            if (AtomRanges.count(atomRanges) === 0) continue;
+            result ??= Array(nAtoms).fill(-1);
+            AtomRanges.foreach(atomRanges, (from, to) => result!.fill(i, from, to));
         }
         return result;
     }
 
+    /** Parse and return all annotation rows in this annotation, or return cached result if available */
+    getRows(): readonly MVSAnnotationRow[] {
+        return this._rows ??= this._getRows();
+    }
+    /** Cached annotation rows. Do not use directly, use `getRows` instead. */
+    private _rows: MVSAnnotationRow[] | undefined = undefined;
     /** Parse and return all annotation rows in this annotation */
     private _getRows(): MVSAnnotationRow[] {
         switch (this.data.format) {
             case 'json':
-                return getRowsFromJson(this.data.data, this.schema);
+                return getRowsFromJson(this.data.data, this.schema, this.fieldRemapping);
             case 'cif':
-                return getRowsFromCif(this.data.data, this.schema);
+                return getRowsFromCif(this.data.data, this.schema, this.fieldRemapping);
         }
     }
-    /** Parse and return all annotation rows in this annotation, or return cached result if available */
-    getRows(): readonly MVSAnnotationRow[] {
-        return this.rows ??= this._getRows();
+
+    /** Return `true` if some rows in the annotation contain `instance_id` field. */
+    private hasInstanceIds(): boolean {
+        return this._hasInstanceIds ??= this.getRows().some(row => isDefined(row.instance_id));
+    }
+    private _hasInstanceIds?: boolean = undefined;
+
+    /** Return list of all distinct values appearing in field `fieldName`, in order of first occurrence. Ignores special values `.` and `?`. If `caseInsensitive`, make all values uppercase. */
+    getDistinctValuesInField(fieldName: string, caseInsensitive: boolean): string[] {
+        const seen = new Set<string | undefined>();
+        const out = [];
+        for (let i = 0; i < this.nRows; i++) {
+            let value = this.getValueForRow(i, fieldName);
+            if (caseInsensitive) value = value?.toUpperCase();
+            if (value !== undefined && !seen.has(value)) {
+                seen.add(value);
+                out.push(value);
+            }
+        }
+        return out;
     }
 }
 
@@ -272,55 +302,80 @@ function getValueFromCif(rowIndex: number, fieldName: string, data: CifCategory)
     return column.str(rowIndex);
 }
 
-function getRowsFromJson(data: Jsonable, schema: MVSAnnotationSchema): MVSAnnotationRow[] {
+/** Return number of rows in this annotation (without parsing all the data) */
+function getRowCount(data: MVSAnnotationData): number {
+    switch (data.format) {
+        case 'json':
+            return getRowCountFromJson(data.data);
+        case 'cif':
+            return getRowCountFromCif(data.data);
+    }
+}
+function getRowCountFromJson(data: Jsonable): number {
     const js = data as any;
-    const cifSchema = getCifAnnotationSchema(schema);
     if (Array.isArray(js)) {
         // array of objects
-        return js.map(row => pickObjectKeys(row, Object.keys(cifSchema)));
+        return js.length;
     } else {
         // object of arrays
-        const rows: MVSAnnotationRow[] = [];
-        const keys = Object.keys(js).filter(key => Object.hasOwn(cifSchema, key as any));
+        const keys = Object.keys(js);
         if (keys.length > 0) {
-            const n = js[keys[0]].length;
-            if (keys.some(key => js[key].length !== n)) throw new Error('FormatError: arrays must have the same length.');
-            for (let i = 0; i < n; i++) {
-                const item: { [key: string]: any } = {};
-                for (const key of keys) {
-                    item[key] = js[key][i];
-                }
-                rows.push(item);
-            }
+            return js[keys[0]].length;
+        } else {
+            return 0;
         }
-        return rows;
     }
 }
+function getRowCountFromCif(data: CifCategory): number {
+    return data.rowCount;
+}
 
-function getRowsFromCif(data: CifCategory, schema: MVSAnnotationSchema): MVSAnnotationRow[] {
-    const rows: MVSAnnotationRow[] = [];
+function getRowsFromJson(data: Jsonable, schema: MVSAnnotationSchema, fieldRemapping: FieldRemapping): MVSAnnotationRow[] {
+    const js = data as any;
     const cifSchema = getCifAnnotationSchema(schema);
-    const table = toTable(cifSchema, data);
-    arrayExtend(rows, getRowsFromTable(table)); // Avoiding Table.getRows(table) as it replaces . and ? fields by 0 or ''
-    return rows;
+    const cifSchemaKeys = Object.keys(cifSchema);
+    if (Array.isArray(js)) {
+        // array of objects
+        return js.map(row => pickObjectKeysWithRemapping(row, cifSchemaKeys, fieldRemapping));
+    } else {
+        // object of arrays
+        const selectedFields: Record<string, any[]> = pickObjectKeysWithRemapping(js, cifSchemaKeys, fieldRemapping);
+        return objectOfArraysToArrayOfObjects(selectedFields);
+    }
 }
 
-/** Same as `Table.getRows` but omits `.` and `?` fields (instead of using type defaults) */
-function getRowsFromTable<S extends Table.Schema>(table: Table<S>): Partial<Table.Row<S>>[] {
-    const rows: Partial<Table.Row<S>>[] = [];
-    const columns = table._columns;
-    const nRows = table._rowCount;
-    const Present = Column.ValueKind.Present;
-    for (let iRow = 0; iRow < nRows; iRow++) {
-        const row: Partial<Table.Row<S>> = {};
-        for (const col of columns) {
-            if (table[col].valueKind(iRow) === Present) {
-                row[col as keyof S] = table[col].value(iRow);
-            }
-        }
-        rows[iRow] = row;
+function getRowsFromCif(data: CifCategory, schema: MVSAnnotationSchema, fieldRemapping: FieldRemapping): MVSAnnotationRow[] {
+    const cifSchema = getCifAnnotationSchema(schema);
+    const cifSchemaKeys = Object.keys(cifSchema) as (keyof typeof cifSchema)[];
+    const columns: Partial<Record<keyof typeof cifSchema, any[]>> = {};
+    for (const key of cifSchemaKeys) {
+        let srcKey = fieldRemapping[key];
+        if (srcKey === null) continue; // Ignore key
+        if (srcKey === undefined) srcKey = key; // Implicit key mapping
+        const columnArray = getArrayFromCifCategory(data, srcKey, cifSchema[key]); // Avoiding `column.toArray` as it replaces . and ? fields by 0 or ''
+        if (columnArray) columns[key] = columnArray;
     }
-    return rows;
+    return objectOfArraysToArrayOfObjects(columns);
+}
+
+/** Load data from a specific column in a CIF category into an array. Load `.` and `?` as undefined. */
+function getArrayFromCifCategory<T>(data: CifCategory, columnName: string, columnSchema: Column.Schema): (T | undefined)[] | undefined {
+    if (data.getField(columnName) === undefined) return undefined;
+
+    const table = toTable({ [columnName]: columnSchema }, data); // a bit dumb, I don't know how to make column directly
+    const column = table[columnName];
+    return getArrayFromCifColumn(column); // Avoiding `column.toArray` as it replaces . and ? fields by 0 or ''
+}
+
+/** Same as `column.toArray` but reads `.` and `?` as undefined (instead of using type defaults) */
+function getArrayFromCifColumn<T>(column: Column<T>): (T | undefined)[] {
+    const nRows = column.rowCount;
+    const Present = Column.ValueKind.Present;
+    const out: (T | undefined)[] = new Array(nRows);
+    for (let iRow = 0; iRow < nRows; iRow++) {
+        out[iRow] = column.valueKind(iRow) === Present ? column.value(iRow) : undefined;
+    }
+    return out;
 }
 
 async function getFileFromSource(ctx: CustomProperty.Context, source: MVSAnnotationSource, model?: Model): Promise<MVSAnnotationFile> {

src/extensions/mvs/components/custom-label/visual.ts

@@ -75,7 +75,7 @@ function createLabelText(ctx: VisualContext, structure: Structure, theme: Theme,
                 break;
             case 'selection':
                 const substructure = substructureFromSelector(structure, item.position.params.selector);
-                const p = textPropsForSelection(substructure, theme.size.size, {});
+                const p = textPropsForSelection(substructure, theme.size.size, [{}]);
                 const group = serialIndexOfSubstructure(structure, substructure) ?? 0;
                 if (p) builder.add(item.text, p.center[0], p.center[1], p.center[2], p.depth, p.scale, group);
                 break;

src/extensions/mvs/components/formats.ts

@@ -1,10 +1,11 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
+ * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import { hashFnv32a } from '../../../mol-data/util';
+import { murmurHash3_128_fromBytes } from '../../../mol-data/util';
 import { StringLike } from '../../../mol-io/common/string-like';
 import { DataFormatProvider } from '../../../mol-plugin-state/formats/provider';
 import { PluginStateObject as SO } from '../../../mol-plugin-state/objects';
@@ -112,7 +113,12 @@ export const MVSXFormatProvider: DataFormatProvider<{}, StateObjectRef<Mvs>, any
  * and parse the main file in the archive as MVSJ.
  * Return parsed MVS data and `sourceUrl` for resolution of relative URIs.  */
 export async function loadMVSX(plugin: PluginContext, runtimeCtx: RuntimeContext, data: Uint8Array, mainFilePath: string = 'index.mvsj'): Promise<{ mvsData: MVSData, sourceUrl: string }> {
-    const archiveId = `ni,fnv1a;${hashFnv32a(data)}`;
+    // Ensure at most one generation of MVSX file assets exists in the asset manager.
+    // Hopefully, this is a reasonable compromise to ensure MVSX files work in multi-snapshot
+    // states.
+    clearMVSXFileAssets(plugin);
+
+    const archiveId = `ni,MurmurHash3_128;${murmurHash3_128_fromBytes(data, 42)}`;
     let files: { [path: string]: Uint8Array };
     try {
         files = await unzip(runtimeCtx, data) as typeof files;
@@ -122,7 +128,8 @@ export async function loadMVSX(plugin: PluginContext, runtimeCtx: RuntimeContext
     }
     for (const path in files) {
         const url = arcpUri(archiveId, path);
-        ensureUrlAsset(plugin.managers.asset, url, files[path]);
+        // Need to use static assets so they persist accross snapsho
+        ensureUrlAsset(plugin.managers.asset, url, files[path], { isFile: true });
     }
     const mainFile = files[mainFilePath];
     if (!mainFile) throw new Error(`File ${mainFilePath} not found in the MVSX archive`);
@@ -154,11 +161,17 @@ export async function loadMVSData(plugin: PluginContext, data: MVSData | StringL
         }
         await plugin.runTask(Task.create('Load MVSX file', async ctx => {
             const parsed = await loadMVSX(plugin, ctx, data as Uint8Array);
-            await loadMVS(plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+            await loadMVS(plugin, parsed.mvsData, { sanityChecks: true, ...options, sourceUrl: parsed.sourceUrl });
         }));
     } else {
         throw new Error(`Unknown MolViewSpec format: ${format}`);
     }
+
+    return data;
+}
+
+function clearMVSXFileAssets(plugin: PluginContext) {
+    plugin.managers.asset.clearTag('mvsx-file');
 }
 
 /** If the PluginStateObject `pso` comes from a Download transform, try to get its `url` parameter. */
@@ -169,7 +182,7 @@ function tryGetDownloadUrl(pso: SO.Data.String, plugin: PluginContext): string |
 }
 
 /** Return a URI referencing a file within an archive, using ARCP scheme (https://arxiv.org/pdf/1809.06935.pdf).
- * `archiveId` corresponds to the `authority` part of URI (e.g. 'uuid,EYVwjDiZhM20PWbF1OWWvQ' or 'ni,fnv1a;938511930')
+ * `archiveId` corresponds to the `authority` part of URI (e.g. 'uuid,EYVwjDiZhM20PWbF1OWWvQ' or 'ni,MurmurHash3_128;e6494f6be71f34c556f3de73d306780c')
  * `path` corresponds to the path to a file within the archive */
 function arcpUri(archiveId: string, path: string): string {
     return new URL(path, `arcp://${archiveId}/`).href;
@@ -177,11 +190,13 @@ function arcpUri(archiveId: string, path: string): string {
 
 /** Add a URL asset to asset manager.
  * Skip if an asset with the same URL already exists. */
-function ensureUrlAsset(manager: AssetManager, url: string, data: Uint8Array) {
+function ensureUrlAsset(manager: AssetManager, url: string, data: Uint8Array, options?: { isFile?: boolean }) {
     const asset = Asset.getUrlAsset(manager, url);
     if (!manager.has(asset)) {
         const filename = url.split('/').pop() ?? 'file';
-        manager.set(asset, new File([data], filename));
+        // We need to mark files as static resources to prevent deleting them
+        // when changing state snapshots.
+        manager.set(asset, new File([data], filename), options?.isFile ? { isStatic: true, tag: 'mvsx-file' } : undefined);
     }
 }
 

src/extensions/mvs/components/multilayer-color-theme.ts

@@ -4,17 +4,19 @@
  * @author Adam Midlik <midlik@gmail.com>
  */
 
+import { ColorTypeLocation } from '../../../mol-geo/geometry/color-data';
 import { Location } from '../../../mol-model/location';
 import { Bond, Structure, StructureElement } from '../../../mol-model/structure';
 import { ColorTheme, LocationColor } from '../../../mol-theme/color';
 import { ColorThemeCategory } from '../../../mol-theme/color/categories';
 import { ThemeDataContext } from '../../../mol-theme/theme';
+import { deepEqual } from '../../../mol-util';
 import { Color } from '../../../mol-util/color';
 import { ColorNames } from '../../../mol-util/color/names';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 import { stringToWords } from '../../../mol-util/string';
 import { isMVSStructure } from './is-mvs-model-prop';
-import { ElementSet, SelectorParams, isSelectorAll } from './selector';
+import { ElementSet, SelectorParams, isSelectorAll, substructureFromSelector } from './selector';
 
 
 /** Special value that can be used as color with null-like semantic (i.e. "no color provided").
@@ -70,32 +72,7 @@ export const DefaultMultilayerColorThemeProps: MultilayerColorThemeProps = { lay
  * If a nested theme provider has `ensureCustomProperties` methods, these will not be called automatically
  * (the caller must ensure that any required custom properties be attached). */
 function makeMultilayerColorTheme(ctx: ThemeDataContext, props: MultilayerColorThemeProps, colorThemeRegistry: ColorTheme.Registry): ColorTheme<MultilayerColorThemeParams> {
-    const colorLayers: { color: LocationColor, elementSet: ElementSet | undefined }[] = []; // undefined elementSet means 'all'
-    for (let i = props.layers.length - 1; i >= 0; i--) { // iterate from end to get top layer first, bottom layer last
-        const layer = props.layers[i];
-        const themeProvider = colorThemeRegistry.get(layer.theme.name);
-        if (!themeProvider) {
-            console.warn(`Skipping color theme '${layer.theme.name}', cannot find it in registry.`);
-            continue;
-        }
-        if (themeProvider.ensureCustomProperties?.attach) {
-            console.warn(`Multilayer color theme: layer "${themeProvider.name}" has ensureCustomProperties.attach method, but Multilayer color theme does not call it. If the layer does not work, make sure you call ensureCustomProperties.attach somewhere.`);
-        }
-        const theme = themeProvider.factory(ctx, layer.theme.params);
-        switch (theme.granularity) {
-            case 'uniform':
-            case 'instance':
-            case 'group':
-            case 'groupInstance':
-            case 'vertex':
-            case 'vertexInstance':
-                const elementSet = isSelectorAll(layer.selection) ? undefined : ElementSet.fromSelector(ctx.structure, layer.selection); // treating 'all' specially for performance reasons (it's expected to be used most often)
-                colorLayers.push({ color: theme.color, elementSet });
-                break;
-            default:
-                console.warn(`Skipping color theme '${layer.theme.name}', cannot process granularity '${theme.granularity}'`);
-        }
-    };
+    const { colorLayers, granularity } = makeLayers(ctx, props, colorThemeRegistry);
 
     function structureElementColor(loc: StructureElement.Location, isSecondary: boolean): Color {
         for (const layer of colorLayers) {
@@ -123,7 +100,7 @@ function makeMultilayerColorTheme(ctx: ThemeDataContext, props: MultilayerColorT
 
     return {
         factory: (ctx_, props_) => makeMultilayerColorTheme(ctx_, props_, colorThemeRegistry),
-        granularity: 'group',
+        granularity,
         preferSmoothing: true,
         color: color,
         props: props,
@@ -132,6 +109,117 @@ function makeMultilayerColorTheme(ctx: ThemeDataContext, props: MultilayerColorT
 }
 
 
+const GRAN_INSTANCE = 1, GRAN_GROUP = 2, GRAN_VERTEX = 4;
+
+const granularityFlagsFromName = {
+    'uniform': 0,
+    'instance': GRAN_INSTANCE,
+    'group': GRAN_GROUP,
+    'groupInstance': GRAN_GROUP | GRAN_INSTANCE,
+    'vertex': GRAN_VERTEX,
+    'vertexInstance': GRAN_VERTEX | GRAN_INSTANCE,
+} satisfies { [name in ColorTypeLocation]: number };
+
+function granularityNameFromFlags(flags: number): ColorTypeLocation {
+    if (flags & GRAN_VERTEX) return flags & GRAN_INSTANCE ? 'vertexInstance' : 'vertex';
+    if (flags & GRAN_GROUP) return flags & GRAN_INSTANCE ? 'groupInstance' : 'group';
+    return flags & GRAN_INSTANCE ? 'instance' : 'uniform';
+}
+
+interface ColorLayer {
+    /** Substructure to which the layer is applied, undefined means 'all' */
+    elementSet: ElementSet | undefined,
+    /** Color theme for the layer */
+    color: LocationColor,
+}
+
+function makeLayers(ctx: ThemeDataContext, props: MultilayerColorThemeProps, colorThemeRegistry: ColorTheme.Registry) {
+    const colorLayers: ColorLayer[] = [];
+    let granularityFlags = 0;
+    for (let i = props.layers.length - 1; i >= 0; i--) { // iterate from the end to get top layer first, bottom layer last
+        const layer = props.layers[i];
+        const themeProvider = colorThemeRegistry.get(layer.theme.name);
+        if (!themeProvider) {
+            console.warn(`Skipping color theme '${layer.theme.name}', cannot find it in registry.`);
+            continue;
+        }
+        if (themeProvider.ensureCustomProperties?.attach) {
+            console.warn(`Multilayer color theme: layer "${themeProvider.name}" has ensureCustomProperties.attach method, but Multilayer color theme does not call it. If the layer does not work, make sure you call ensureCustomProperties.attach somewhere.`);
+        }
+        const theme = themeProvider.factory(ctx, layer.theme.params);
+        switch (theme.granularity) {
+            case 'uniform':
+            case 'instance':
+            case 'group':
+            case 'groupInstance':
+            case 'vertex':
+            case 'vertexInstance':
+                let elementSet: ElementSet | undefined;
+                let selectionGranularity: 'uniform' | 'instance' | 'group' | 'groupInstance';
+                if (!ctx.structure) {
+                    elementSet = {};
+                    selectionGranularity = 'uniform';
+                } else if (isSelectorAll(layer.selection)) {
+                    // Treating 'all' specially for performance reasons (it's expected to be used most often)
+                    elementSet = undefined;
+                    selectionGranularity = 'uniform';
+                } else {
+                    const substructure = substructureFromSelector(ctx.structure, layer.selection);
+                    elementSet = ElementSet.fromStructure(substructure);
+                    selectionGranularity = getSubstructureGranularity(ctx.structure, substructure);
+                }
+                colorLayers.push({ elementSet, color: theme.color });
+                granularityFlags |= granularityFlagsFromName[selectionGranularity];
+                granularityFlags |= granularityFlagsFromName[theme.granularity];
+                break;
+            default:
+                console.warn(`Skipping color theme '${layer.theme.name}', cannot process granularity '${theme.granularity}'`);
+        }
+    }
+    return { colorLayers, granularity: granularityNameFromFlags(granularityFlags) };
+}
+
+
+function getSubstructureGranularity(parent: Structure, substructure: Structure) {
+    const parentCounts: { [instance: string]: number } = {};
+    for (const unit of parent.units) {
+        const instance = unit.conformation.operator.instanceId;
+        parentCounts[instance] ??= 0;
+        parentCounts[instance] += unit.elements.length;
+    }
+
+    const childCounts: { [instance: string]: number } = {};
+    const elementsPerInstance: { [instance: string]: { [invariantId: number]: StructureElement.Set } } = {};
+    for (const unit of substructure.units) {
+        const instance = unit.conformation.operator.instanceId;
+        childCounts[instance] ??= 0;
+        childCounts[instance] += unit.elements.length;
+        (elementsPerInstance[instance] ??= {})[unit.invariantId] = unit.elements;
+    }
+
+    const parentInstances = Object.keys(parentCounts);
+    const childInstances = Object.keys(childCounts);
+    const groupGranularity = !childInstances.every(inst => childCounts[inst] === parentCounts[inst]);
+    let instanceGranularity: boolean;
+
+    if (childInstances.length === 0) {
+        instanceGranularity = false;
+    } else if (childInstances.length < parentInstances.length) {
+        instanceGranularity = true;
+    } else {
+        instanceGranularity = false;
+        for (let i = 1; i < childInstances.length; i++) {
+            if (!deepEqual(elementsPerInstance[childInstances[0]], elementsPerInstance[childInstances[i]])) {
+                instanceGranularity = true;
+                break;
+            }
+        }
+    }
+    if (groupGranularity) return instanceGranularity ? 'groupInstance' : 'group';
+    else return instanceGranularity ? 'instance' : 'uniform';
+}
+
+
 /** Unique name for "Multilayer" color theme */
 export const MultilayerColorThemeName = 'mvs-multilayer';
 

src/extensions/mvs/components/primitives.ts

@@ -5,6 +5,7 @@
  * @author Adam Midlik <midlik@gmail.com>
  */
 
+import { BaseGeometry } from '../../../mol-geo/geometry/base';
 import { Lines } from '../../../mol-geo/geometry/lines/lines';
 import { LinesBuilder } from '../../../mol-geo/geometry/lines/lines-builder';
 import { addFixedCountDashedCylinder, addSimpleCylinder, BasicCylinderProps } from '../../../mol-geo/geometry/mesh/builder/cylinder';
@@ -25,19 +26,22 @@ import { Structure, StructureElement, StructureSelection } from '../../../mol-mo
 import { StructureQueryHelper } from '../../../mol-plugin-state/helpers/structure-query';
 import { PluginStateObject as SO } from '../../../mol-plugin-state/objects';
 import { PluginContext } from '../../../mol-plugin/context';
+import { ShapeRepresentation } from '../../../mol-repr/shape/representation';
 import { Expression } from '../../../mol-script/language/expression';
-import { StateObject } from '../../../mol-state';
+import { StateObject, StateTransformer } from '../../../mol-state';
 import { Task } from '../../../mol-task';
 import { round } from '../../../mol-util';
 import { range } from '../../../mol-util/array';
 import { Asset } from '../../../mol-util/assets';
 import { Color } from '../../../mol-util/color';
+import { MarkerActions } from '../../../mol-util/marker-action';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 import { capitalize } from '../../../mol-util/string';
 import { rowsToExpression, rowToExpression } from '../helpers/selections';
-import { collectMVSReferences, decodeColor } from '../helpers/utils';
-import { MolstarNode, MolstarSubtree } from '../tree/molstar/molstar-tree';
-import { MVSNode } from '../tree/mvs/mvs-tree';
+import { collectMVSReferences, decodeColor, isDefined } from '../helpers/utils';
+import { addParamDefaults } from '../tree/generic/params-schema';
+import { MolstarNode, MolstarNodeParams, MolstarSubtree } from '../tree/molstar/molstar-tree';
+import { MVSNode, MVSTreeSchema } from '../tree/mvs/mvs-tree';
 import { isComponentExpression, isPrimitiveComponentExpressions, isVector3, PrimitivePositionT } from '../tree/mvs/param-types';
 import { MVSTransform } from './annotation-structure-component';
 
@@ -94,6 +98,16 @@ export const MVSDownloadPrimitiveData = MVSTransform({
     },
 });
 
+/* Cannot use MolstarSubtree<'primitives'>> because information about type of children would be lost and cause TypeScript errors in dependent code */
+interface PrimitivesSubtree {
+    kind: 'primitives',
+    params: MolstarNodeParams<'primitives'>,
+    children?: {
+        kind: 'primitive',
+        params: MolstarNodeParams<'primitive'>,
+    }[],
+}
+
 export type MVSInlinePrimitiveData = typeof MVSInlinePrimitiveData
 export const MVSInlinePrimitiveData = MVSTransform({
     name: 'mvs-inline-primitive-data',
@@ -101,7 +115,10 @@ export const MVSInlinePrimitiveData = MVSTransform({
     from: [SO.Root, SO.Molecule.Structure],
     to: MVSPrimitivesData,
     params: {
-        node: PD.Value<MolstarSubtree<'primitives'>>(undefined as any, { isHidden: true }),
+        node: PD.Value<PrimitivesSubtree>({
+            kind: 'primitives',
+            params: addParamDefaults(MVSTreeSchema.nodes.primitives.params, {}),
+        }, { isHidden: true }),
     },
 })({
     apply({ a, params }) {
@@ -131,34 +148,62 @@ export const MVSBuildPrimitiveShape = MVSTransform({
         const structureRefs = dependencies ? collectMVSReferences([SO.Molecule.Structure], dependencies) : {};
         const context: PrimitiveBuilderContext = { ...a.data, structureRefs };
 
+        const snapshotKey = { snapshotKey: { ...SnapshotKey, defaultValue: a.data.options?.snapshot_key ?? '' } };
+        const markdownCommands = { markdownCommands: { ...MarkdownCommands, defaultValue: a.data.node?.custom?.molstar_markdown_commands } };
+
         const label = capitalize(params.kind);
         if (params.kind === 'mesh') {
             if (!hasPrimitiveKind(a.data, 'mesh')) return StateObject.Null;
 
+            const customMeshParams = a.data.node.custom?.molstar_mesh_params;
             return new SO.Shape.Provider({
                 label,
                 data: context,
-                params: PD.withDefaults(Mesh.Params, { alpha: a.data.options?.opacity ?? 1 }),
+                params: {
+                    ...PD.withDefaults(Mesh.Params, { alpha: a.data.options?.opacity ?? 1, ...customMeshParams }),
+                    ...snapshotKey,
+                    ...markdownCommands,
+                },
                 getShape: (_, data, __, prev: any) => buildPrimitiveMesh(data, prev?.geometry),
                 geometryUtils: Mesh.Utils,
             }, { label });
         } else if (params.kind === 'labels') {
             if (!hasPrimitiveKind(a.data, 'label')) return StateObject.Null;
 
+            const options = a.data.options;
+            const bgColor = options?.label_background_color;
+            const customLabelParams = a.data.node.custom?.molstar_label_params;
             return new SO.Shape.Provider({
                 label,
                 data: context,
-                params: PD.withDefaults(DefaultLabelParams, { alpha: a.data.options?.label_opacity ?? 1 }),
-                getShape: (_, data, __, prev: any) => buildPrimitiveLabels(data, prev?.geometry),
+                params: {
+                    ...PD.withDefaults(DefaultLabelParams, {
+                        alpha: a.data.options?.label_opacity ?? 1,
+                        attachment: options?.label_attachment ?? 'middle-center',
+                        tether: options?.label_show_tether ?? false,
+                        tetherLength: options?.label_tether_length ?? 1,
+                        background: isDefined(bgColor),
+                        backgroundColor: isDefined(bgColor) ? decodeColor(bgColor) : undefined,
+                        ...customLabelParams,
+                    }),
+                    ...snapshotKey,
+                    ...markdownCommands,
+                },
+                getShape: (_, data, props, prev: any) => buildPrimitiveLabels(data, prev?.geometry, props),
                 geometryUtils: Text.Utils,
             }, { label });
         } else if (params.kind === 'lines') {
             if (!hasPrimitiveKind(a.data, 'line')) return StateObject.Null;
 
+            const customLineParams = a.data.node.custom?.molstar_line_params;
             return new SO.Shape.Provider({
                 label,
                 data: context,
-                params: PD.withDefaults(Lines.Params, { alpha: a.data.options?.opacity ?? 1 }),
+                params: {
+                    ...PD.withDefaults(Lines.Params, { alpha: a.data.options?.opacity ?? 1, ...customLineParams }),
+                    ...snapshotKey,
+                    ...markdownCommands,
+                },
                 getShape: (_, data, __, prev: any) => buildPrimitiveLines(data, prev?.geometry),
                 geometryUtils: Lines.Utils,
             }, { label });
@@ -168,6 +213,51 @@ export const MVSBuildPrimitiveShape = MVSTransform({
     }
 });
 
+export const MVSShapeRepresentation3D = MVSTransform({
+    name: 'shape-representation-3d',
+    display: '3D Representation',
+    from: SO.Shape.Provider,
+    to: SO.Shape.Representation3D,
+    params: (a, ctx: PluginContext) => {
+        return a ? a.data.params : BaseGeometry.Params;
+    }
+})({
+    canAutoUpdate() {
+        return true;
+    },
+    apply({ a, params }) {
+        return Task.create('Shape Representation', async ctx => {
+            const props = { ...PD.getDefaultValues(a.data.params), ...params };
+            const repr = ShapeRepresentation(a.data.getShape, a.data.geometryUtils);
+            await repr.createOrUpdate(props, a.data.data).runInContext(ctx);
+
+            const pickable = !!(params as any).snapshotKey?.trim() || !!(params as any).markdownCommands;
+            if (pickable) {
+                repr.setState({ pickable, markerActions: MarkerActions.Highlighting });
+            }
+
+            return new SO.Shape.Representation3D({ repr, sourceData: a.data }, { label: a.data.label });
+        });
+    },
+    update({ a, b, newParams }) {
+        return Task.create('Shape Representation', async ctx => {
+            const props = { ...b.data.repr.props, ...newParams };
+            await b.data.repr.createOrUpdate(props, a.data.data).runInContext(ctx);
+            b.data.sourceData = a.data;
+
+            const pickable = !!(newParams as any).snapshotKey?.trim() || !!(newParams as any).markdownCommands;
+            if (pickable) {
+                b.data.repr.setState({ pickable, markerActions: MarkerActions.Highlighting });
+            }
+
+            return StateTransformer.UpdateResult.Updated;
+        });
+    }
+});
+
+const SnapshotKey = PD.Text('', { isEssential: true, disableInteractiveUpdates: true, description: 'Activate the snapshot with the provided key when clicking on the label' });
+const MarkdownCommands = PD.Value<any>(undefined, { isHidden: true });
+
 /* **************************************************** */
 
 class GroupManager {
@@ -216,8 +306,16 @@ interface PrimitiveBuilderContext {
     structureRefs: Record<string, Structure | undefined>;
     primitives: MolstarNode<'primitive'>[];
     options: PrimitivesParams;
-    positionCache: Map<string, [Sphere3D, Box3D]>;
+    positionCache: Map<string, [isDefined: boolean, Sphere3D, Box3D]>;
     instances: Mat4[] | undefined;
+    emptySelectionWarningPrinted?: boolean;
+}
+
+function printEmptySelectionWarning(ctx: PrimitiveBuilderContext, position: PrimitivePositionT): void {
+    if (!ctx.emptySelectionWarningPrinted) {
+        console.warn('Some primitives use positions which refer to empty substructure, not showing these primitives.', position, '(There may be more)');
+        ctx.emptySelectionWarningPrinted = true;
+    }
 }
 
 interface MeshBuilderState {
@@ -373,14 +471,20 @@ function hasPrimitiveKind(context: PrimitiveBuilderContext, kind: 'mesh' | 'line
     return false;
 }
 
-function resolveBasePosition(context: PrimitiveBuilderContext, position: PrimitivePositionT, targetPosition: Vec3) {
+/** Save resolved position into `targetPosition`.
+ * Return `true` if the resolved position is defined (i.e. vector or non-empty selection);
+ * return `false` if the resolved position is not defined (i.e. empty selection). */
+function resolveBasePosition(context: PrimitiveBuilderContext, position: PrimitivePositionT, targetPosition: Vec3): boolean {
     return resolvePosition(context, position, targetPosition, undefined, undefined);
 }
 
 const _EmptySphere = Sphere3D.zero();
 const _EmptyBox = Box3D.zero();
 
-function resolvePosition(context: PrimitiveBuilderContext, position: PrimitivePositionT, targetPosition: Vec3 | undefined, targetSphere: Sphere3D | undefined, targetBox: Box3D | undefined) {
+/** Save resolved position into `targetPosition`, `targetSphere`, `targetBox`.
+ * Return `true` if the resolved position is defined (i.e. vector or non-empty selection);
+ * return `false` if the resolved position is not defined (i.e. empty selection). */
+function resolvePosition(context: PrimitiveBuilderContext, position: PrimitivePositionT, targetPosition: Vec3 | undefined, targetSphere: Sphere3D | undefined, targetBox: Box3D | undefined): boolean {
     let expr: Expression | undefined;
     let pivotRef: string | undefined;
 
@@ -388,7 +492,7 @@ function resolvePosition(context: PrimitiveBuilderContext, position: PrimitivePo
         if (targetPosition) Vec3.copy(targetPosition, position as any);
         if (targetSphere) Sphere3D.set(targetSphere, position as any, 0);
         if (targetBox) Box3D.set(targetBox, position as any, position as any);
-        return;
+        return true;
     }
 
     if (isPrimitiveComponentExpressions(position)) {
@@ -409,36 +513,41 @@ function resolvePosition(context: PrimitiveBuilderContext, position: PrimitivePo
         throw new Error(`Structure with ref '${pivotRef ?? '<default>'}' not found.`);
     }
 
-    const cackeKey = JSON.stringify(position);
-    if (context.positionCache.has(cackeKey)) {
-        const cached = context.positionCache.get(cackeKey)!;
-        if (targetPosition) Vec3.copy(targetPosition, cached[0].center);
-        if (targetSphere) Sphere3D.copy(targetSphere, cached[0]);
-        if (targetBox) Box3D.copy(targetBox, cached[1]);
-        return;
+    const cacheKey = JSON.stringify(position);
+    if (context.positionCache.has(cacheKey)) {
+        const [isDefined, sphere, box] = context.positionCache.get(cacheKey)!;
+        if (targetPosition) Vec3.copy(targetPosition, sphere.center);
+        if (targetSphere) Sphere3D.copy(targetSphere, sphere);
+        if (targetBox) Box3D.copy(targetBox, box);
+        return isDefined;
     }
 
     const { selection } = StructureQueryHelper.createAndRun(pivot, expr);
 
     let box: Box3D;
     let sphere: Sphere3D;
+    let isDefined: boolean;
 
     if (StructureSelection.isEmpty(selection)) {
         if (targetPosition) Vec3.set(targetPosition, 0, 0, 0);
         box = _EmptyBox;
         sphere = _EmptySphere;
+        isDefined = false;
+        printEmptySelectionWarning(context, position);
     } else {
         const loci = StructureSelection.toLociWithSourceUnits(selection);
         const boundary = StructureElement.Loci.getBoundary(loci);
         if (targetPosition) Vec3.copy(targetPosition, boundary.sphere.center);
         box = boundary.box;
         sphere = boundary.sphere;
+        isDefined = true;
     }
 
     if (targetSphere) Sphere3D.copy(targetSphere, sphere);
     if (targetBox) Box3D.copy(targetBox, box);
 
-    context.positionCache.set(cackeKey, [sphere, box]);
+    context.positionCache.set(cacheKey, [isDefined, sphere, box]);
+    return isDefined;
 }
 
 function getInstances(options: PrimitivesParams | undefined): Mat4[] | undefined {
@@ -514,8 +623,11 @@ function buildPrimitiveLines(context: PrimitiveBuilderContext, prev?: Lines): Sh
     );
 }
 
-function buildPrimitiveLabels(context: PrimitiveBuilderContext, prev?: Text): Shape<Text> {
-    const labelsBuilder = TextBuilder.create(BaseLabelProps, 1024, 1024, prev);
+function buildPrimitiveLabels(context: PrimitiveBuilderContext, prev: Text | undefined, props: PD.Values<Text.Params>): Shape<Text> {
+    const labelsBuilder = TextBuilder.create({
+        ...BaseLabelProps,
+        ...props,
+    }, 1024, 1024, prev);
     const state: LabelBuilderState = { groups: new GroupManager(), labels: labelsBuilder };
 
     for (const c of context.primitives) {
@@ -631,8 +743,9 @@ const lEnd = Vec3.zero();
 
 function addTubeMesh(context: PrimitiveBuilderContext, { groups, mesh }: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'tube'>, options?: { skipResolvePosition?: boolean }) {
     if (!options?.skipResolvePosition) {
-        resolveBasePosition(context, params.start, lStart);
-        resolveBasePosition(context, params.end, lEnd);
+        const startDefined = resolveBasePosition(context, params.start, lStart);
+        const endDefined = resolveBasePosition(context, params.end, lEnd);
+        if (!startDefined || !endDefined) return;
     }
     const radius = params.radius;
 
@@ -665,13 +778,17 @@ const ArrowState = {
 };
 
 function addArrowMesh(context: PrimitiveBuilderContext, { groups, mesh }: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'arrow'>) {
-    resolveBasePosition(context, params.start, ArrowState.start);
-    if (params.end) {
-        resolveBasePosition(context, params.end, ArrowState.end);
-    }
+    const startDefined = resolveBasePosition(context, params.start, ArrowState.start);
+    if (!startDefined) return;
 
-    if (params.direction) {
+    if (params.end) {
+        const endDefined = resolveBasePosition(context, params.end, ArrowState.end);
+        if (!endDefined) return;
+    } else if (params.direction) {
         Vec3.add(ArrowState.end, ArrowState.start, params.direction as any as Vec3);
+    } else {
+        console.warn(`Primitive arrow does not contain "end" nor "distance". Not showing.`);
+        return;
     }
 
     Vec3.sub(ArrowState.dir, ArrowState.end, ArrowState.start);
@@ -696,9 +813,10 @@ function addArrowMesh(context: PrimitiveBuilderContext, { groups, mesh }: MeshBu
     groups.updateColor(mesh.currentGroup, params.color);
     groups.updateTooltip(mesh.currentGroup, params.tooltip);
 
-    const startRadius = params.start_cap_radius ?? tubeRadius;
     if (params.show_start_cap) {
-        Vec3.scaleAndAdd(ArrowState.startCap, ArrowState.start, ArrowState.dir, startRadius);
+        const startRadius = params.start_cap_radius ?? 2 * tubeRadius;
+        const startCapLength = params.start_cap_length ?? 2 * startRadius;
+        Vec3.scaleAndAdd(ArrowState.startCap, ArrowState.start, ArrowState.dir, startCapLength);
         addSimpleCylinder(mesh, ArrowState.startCap, ArrowState.start, {
             radiusBottom: startRadius,
             radiusTop: 0,
@@ -710,9 +828,10 @@ function addArrowMesh(context: PrimitiveBuilderContext, { groups, mesh }: MeshBu
         Vec3.copy(ArrowState.startCap, ArrowState.start);
     }
 
-    const endRadius = params.end_cap_radius ?? tubeRadius;
     if (params.show_end_cap) {
-        Vec3.scaleAndAdd(ArrowState.endCap, ArrowState.end, ArrowState.dir, -endRadius);
+        const endRadius = params.end_cap_radius ?? 2 * tubeRadius;
+        const endCapLength = params.end_cap_length ?? 2 * endRadius;
+        Vec3.scaleAndAdd(ArrowState.endCap, ArrowState.end, ArrowState.dir, -endCapLength);
         addSimpleCylinder(mesh, ArrowState.endCap, ArrowState.end, {
             radiusBottom: endRadius,
             radiusTop: 0,
@@ -736,19 +855,26 @@ function addArrowMesh(context: PrimitiveBuilderContext, { groups, mesh }: MeshBu
 }
 
 
-function getDistanceLabel(context: PrimitiveBuilderContext, params: PrimitiveParams<'distance_measurement'>) {
-    resolveBasePosition(context, params.start, lStart);
-    resolveBasePosition(context, params.end, lEnd);
+/** Return distance in angstroms, or `undefined` if any of the endpoints corresponds to empty substructure.
+ * This function also sets `lStart`, `lEnd` globals. */
+function computeDistance(context: PrimitiveBuilderContext, start: PrimitivePositionT, end: PrimitivePositionT): number | undefined {
+    const startDefined = resolveBasePosition(context, start, lStart);
+    const endDefined = resolveBasePosition(context, end, lEnd);
+    if (startDefined && endDefined) return Vec3.distance(lStart, lEnd);
+    else return undefined;
+}
 
-    const dist = Vec3.distance(lStart, lEnd);
-    const distance = `${round(dist, 2)} Å`;
-    const label = typeof params.label_template === 'string' ? params.label_template.replace('{{distance}}', distance) : distance;
-
-    return label;
+// /** Return text for distance measurement label/tooltip. */
+function distanceLabel(distance: number, params: PrimitiveParams<'distance_measurement'>): string {
+    const distStr = `${round(distance, 2)} Å`;
+    if (typeof params.label_template === 'string') return params.label_template.replace('{{distance}}', distStr);
+    else return distStr;
 }
 
 function addDistanceMesh(context: PrimitiveBuilderContext, state: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'distance_measurement'>) {
-    const tooltip = getDistanceLabel(context, params);
+    const distance = computeDistance(context, params.start, params.end); // sets lStart, lEnd
+    if (distance === undefined) return; // empty substructure in measurement
+    const tooltip = distanceLabel(distance, params);
     addTubeMesh(context, state, node, { ...params, tooltip } as any, { skipResolvePosition: true });
 }
 
@@ -756,12 +882,8 @@ const labelPos = Vec3.zero();
 
 function addDistanceLabel(context: PrimitiveBuilderContext, state: LabelBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'distance_measurement'>) {
     const { labels, groups } = state;
-    resolveBasePosition(context, params.start, lStart);
-    resolveBasePosition(context, params.end, lEnd);
-
-    const dist = Vec3.distance(lStart, lEnd);
-    const distance = `${round(dist, 2)} Å`;
-    const label = typeof params.label_template === 'string' ? params.label_template.replace('{{distance}}', distance) : distance;
+    const dist = computeDistance(context, params.start, params.end); // sets lStart, lEnd
+    if (dist === undefined) return; // empty substructure in measurement
 
     let size: number | undefined;
     if (typeof params.label_size === 'number') {
@@ -777,30 +899,36 @@ function addDistanceLabel(context: PrimitiveBuilderContext, state: LabelBuilderS
     groups.updateColor(group, params.label_color);
     groups.updateSize(group, size);
 
-    labels.add(label, labelPos[0], labelPos[1], labelPos[2], 1.05 * (params.radius), 1, group);
+    labels.add(distanceLabel(dist, params), labelPos[0], labelPos[1], labelPos[2], 1.05 * (params.radius), 1, group);
 }
 
 
 const AngleState = {
+    isDefined: false,
     a: Vec3(),
     b: Vec3(),
     c: Vec3(),
     ba: Vec3(),
     bc: Vec3(),
     labelPos: Vec3(),
+    /** Sector radius */
     radius: 0,
+    label: '',
 };
 
-function syncAngleState(context: PrimitiveBuilderContext, params: PrimitiveParams<'angle_measurement'>) {
-    resolveBasePosition(context, params.a, AngleState.a);
-    resolveBasePosition(context, params.b, AngleState.b);
-    resolveBasePosition(context, params.c, AngleState.c);
+function syncAngleState(context: PrimitiveBuilderContext, params: PrimitiveParams<'angle_measurement'>): void {
+    const aDefined = resolveBasePosition(context, params.a, AngleState.a);
+    const bDefined = resolveBasePosition(context, params.b, AngleState.b);
+    const cDefined = resolveBasePosition(context, params.c, AngleState.c);
+    AngleState.isDefined = aDefined && bDefined && cDefined;
+    if (!AngleState.isDefined) return;
+
     Vec3.sub(AngleState.ba, AngleState.a, AngleState.b);
     Vec3.sub(AngleState.bc, AngleState.c, AngleState.b);
     const value = radToDeg(Vec3.angle(AngleState.ba, AngleState.bc));
 
     const angle = `${round(value, 2)}\u00B0`;
-    const label = typeof params.label_template === 'string' ? params.label_template.replace('{{angle}}', angle) : angle;
+    AngleState.label = typeof params.label_template === 'string' ? params.label_template.replace('{{angle}}', angle) : angle;
 
     if (typeof params.section_radius === 'number') {
         AngleState.radius = params.section_radius;
@@ -810,16 +938,16 @@ function syncAngleState(context: PrimitiveBuilderContext, params: PrimitiveParam
             AngleState.radius *= params.section_radius_scale;
         }
     }
-
-    return label;
 }
 
 function addAngleMesh(context: PrimitiveBuilderContext, state: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'angle_measurement'>) {
-    const label = syncAngleState(context, params);
+    syncAngleState(context, params);
+    if (!AngleState.isDefined) return; // empty substructure in measurement
+
     const { groups, mesh } = state;
 
     if (params.show_vector) {
-        const radius = 0.01;
+        const radius = params.vector_radius ?? 0.05;
         const cylinderProps: BasicCylinderProps = {
             radiusBottom: radius,
             radiusTop: radius,
@@ -829,7 +957,7 @@ function addAngleMesh(context: PrimitiveBuilderContext, state: MeshBuilderState,
 
         mesh.currentGroup = groups.allocateSingle(node);
         groups.updateColor(mesh.currentGroup, params.vector_color);
-        groups.updateTooltip(mesh.currentGroup, label);
+        groups.updateTooltip(mesh.currentGroup, AngleState.label);
 
         let count = Math.ceil(Vec3.magnitude(AngleState.ba) / (2 * radius));
         addFixedCountDashedCylinder(mesh, AngleState.a, AngleState.b, 1.0, count, true, cylinderProps);
@@ -857,14 +985,15 @@ function addAngleMesh(context: PrimitiveBuilderContext, state: MeshBuilderState,
             theta_start: 0,
             theta_end: angle,
             color: params.section_color,
-            tooltip: label,
+            tooltip: AngleState.label,
         });
     }
 }
 
 function addAngleLabel(context: PrimitiveBuilderContext, state: LabelBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'angle_measurement'>) {
     const { labels, groups } = state;
-    const label = syncAngleState(context, params);
+    syncAngleState(context, params);
+    if (!AngleState.isDefined) return; // empty substructure in measurement
 
     Vec3.normalize(AngleState.ba, AngleState.ba);
     Vec3.normalize(AngleState.bc, AngleState.bc);
@@ -887,7 +1016,7 @@ function addAngleLabel(context: PrimitiveBuilderContext, state: LabelBuilderStat
     groups.updateColor(group, params.label_color);
     groups.updateSize(group, size);
 
-    labels.add(label, AngleState.labelPos[0], AngleState.labelPos[1], AngleState.labelPos[2], 1, 1, group);
+    labels.add(AngleState.label, AngleState.labelPos[0], AngleState.labelPos[1], AngleState.labelPos[2], 1, 1, group);
 }
 
 function resolveLabelRefs(params: PrimitiveParams<'label'>, refs: Set<string>) {
@@ -901,7 +1030,8 @@ const PrimitiveLabelState = {
 
 function addPrimitiveLabel(context: PrimitiveBuilderContext, state: LabelBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'label'>) {
     const { labels, groups } = state;
-    resolvePosition(context, params.position, PrimitiveLabelState.position, PrimitiveLabelState.sphere, undefined);
+    const positionDefined = resolvePosition(context, params.position, PrimitiveLabelState.position, PrimitiveLabelState.sphere, undefined);
+    if (!positionDefined) return;
 
     const group = groups.allocateSingle(node);
     groups.updateColor(group, params.label_color);
@@ -951,17 +1081,20 @@ function addEllipseMesh(context: PrimitiveBuilderContext, state: MeshBuilderStat
     const circle = getCircle({ thetaStart: params.theta_start, thetaEnd: params.theta_end });
     if (!circle) return;
 
-    resolvePosition(context, params.center, EllipseState.centerPos, undefined, undefined);
+    const centerDefined = resolvePosition(context, params.center, EllipseState.centerPos, undefined, undefined);
+    if (!centerDefined) return;
 
     if (params.major_axis_endpoint) {
-        resolvePosition(context, params.major_axis_endpoint, EllipseState.majorPos, undefined, undefined);
+        const endpointDefined = resolvePosition(context, params.major_axis_endpoint, EllipseState.majorPos, undefined, undefined);
+        if (!endpointDefined) return;
         Vec3.sub(EllipseState.majorAxis, EllipseState.majorPos, EllipseState.centerPos);
     } else {
         Vec3.copy(EllipseState.majorAxis, params.major_axis as any as Vec3);
     }
 
     if (params.minor_axis_endpoint) {
-        resolvePosition(context, params.minor_axis_endpoint, EllipseState.minorPos, undefined, undefined);
+        const endpointDefined = resolvePosition(context, params.minor_axis_endpoint, EllipseState.minorPos, undefined, undefined);
+        if (!endpointDefined) return;
         Vec3.sub(EllipseState.minorAxis, EllipseState.minorPos, EllipseState.centerPos);
     } else {
         Vec3.copy(EllipseState.minorAxis, params.minor_axis as any as Vec3);
@@ -1016,10 +1149,12 @@ const EllipsoidState = {
 
 
 function addEllipsoidMesh(context: PrimitiveBuilderContext, state: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'ellipsoid'>) {
-    resolvePosition(context, params.center, EllipsoidState.centerPos, EllipsoidState.sphere, undefined);
+    const centerDefined = resolvePosition(context, params.center, EllipsoidState.centerPos, EllipsoidState.sphere, undefined);
+    if (!centerDefined) return;
 
     if (params.major_axis_endpoint) {
-        resolvePosition(context, params.major_axis_endpoint, EllipsoidState.majorPos, undefined, undefined);
+        const endpointDefined = resolvePosition(context, params.major_axis_endpoint, EllipsoidState.majorPos, undefined, undefined);
+        if (!endpointDefined) return;
         Vec3.sub(EllipsoidState.majorAxis, EllipsoidState.majorPos, EllipsoidState.centerPos);
     } else if (params.major_axis) {
         Vec3.copy(EllipsoidState.majorAxis, params.major_axis as any as Vec3);
@@ -1028,7 +1163,8 @@ function addEllipsoidMesh(context: PrimitiveBuilderContext, state: MeshBuilderSt
     }
 
     if (params.minor_axis_endpoint) {
-        resolvePosition(context, params.minor_axis_endpoint, EllipsoidState.minorPos, undefined, undefined);
+        const endpointDefined = resolvePosition(context, params.minor_axis_endpoint, EllipsoidState.minorPos, undefined, undefined);
+        if (!endpointDefined) return;
         Vec3.sub(EllipsoidState.minorAxis, EllipsoidState.minorPos, EllipsoidState.centerPos);
     } else if (params.minor_axis) {
         Vec3.copy(EllipsoidState.minorAxis, params.minor_axis as any as Vec3);
@@ -1082,7 +1218,8 @@ const BoxState = {
 function addBoxMesh(context: PrimitiveBuilderContext, state: MeshBuilderState, node: MVSNode<'primitive'>, params: PrimitiveParams<'box'>) {
     if (!params.show_edges && !params.show_faces) return;
 
-    resolvePosition(context, params.center, BoxState.center, undefined, BoxState.boundary);
+    const positionDefined = resolvePosition(context, params.center, BoxState.center, undefined, BoxState.boundary);
+    if (!positionDefined) return;
     if (params.extent) {
         Box3D.expand(BoxState.boundary, BoxState.boundary, params.extent as unknown as Vec3);
     }

src/extensions/mvs/components/selector.ts

@@ -10,8 +10,6 @@ import { StaticStructureComponentTypes, createStructureComponent } from '../../.
 import { PluginStateObject } from '../../../mol-plugin-state/objects';
 import { MolScriptBuilder } from '../../../mol-script/language/builder';
 import { Expression } from '../../../mol-script/language/expression';
-import { UUID } from '../../../mol-util';
-import { arrayExtend, sortIfNeeded } from '../../../mol-util/array';
 import { mapArrayToObject, pickObjectKeys } from '../../../mol-util/object';
 import { Choice } from '../../../mol-util/param-choice';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
@@ -47,28 +45,27 @@ export function isSelectorAll(props: Selector): props is typeof SelectorAll {
 
 
 /** Data structure for fast lookup of a structure element location in a substructure */
-export type ElementSet = { [modelId: UUID]: SortedArray<ElementIndex> }
+export type ElementSet = { [unitId: number]: SortedArray<ElementIndex> }
 
 export const ElementSet = {
+    /** Create an `ElementSet` from a structure */
+    fromStructure(structure: Structure | undefined): ElementSet {
+        if (!structure) return {};
+        const out: ElementSet = {};
+        for (const unit of structure.units) {
+            out[unit.id] = unit.elements;
+        }
+        return out;
+    },
     /** Create an `ElementSet` from the substructure of `structure` defined by `selector` */
     fromSelector(structure: Structure | undefined, selector: Selector): ElementSet {
         if (!structure) return {};
-        const arrays: { [modelId: UUID]: ElementIndex[] } = {};
         const selection = substructureFromSelector(structure, selector); // using `getAtomRangesForRow` might (might not) be faster here
-        for (const unit of selection.units) {
-            arrayExtend(arrays[unit.model.id] ??= [], unit.elements);
-        }
-        const result: { [modelId: UUID]: SortedArray<ElementIndex> } = {};
-        for (const modelId in arrays) {
-            const array = arrays[modelId as UUID];
-            sortIfNeeded(array, (a, b) => a - b);
-            result[modelId as UUID] = SortedArray.ofSortedArray(array);
-        }
-        return result;
+        return this.fromStructure(selection);
     },
     /** Decide if the element set `set` contains structure element location `location` */
     has(set: ElementSet, location: StructureElement.Location): boolean {
-        const array = set[location.unit.model.id];
+        const array = set[location.unit.id];
         return array ? SortedArray.has(array, location.element) : false;
     },
 };

src/extensions/mvs/components/trajectory.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { PluginStateObject } from '../../../mol-plugin-state/objects';
+import { getTrajectory } from '../../../mol-plugin-state/transforms/model';
+import { Task } from '../../../mol-task';
+import { ParamDefinition } from '../../../mol-util/param-definition';
+import { getMVSReferenceObject } from '../helpers/utils';
+import { MVSTransform } from './annotation-structure-component';
+
+export const MVSTrajectoryWithCoordinates = MVSTransform({
+    name: 'trajectory-with-coordinates',
+    display: { name: 'Trajectory with Coordinates', description: 'Create a trajectory from existing model and the provided coordinates.' },
+    from: PluginStateObject.Molecule.Model,
+    to: PluginStateObject.Molecule.Trajectory,
+    params: {
+        coordinatesRef: ParamDefinition.Text('', { isHidden: true }),
+    }
+})({
+    apply({ a, params, dependencies }) {
+        return Task.create('Create trajectory from model/topology and coordinates', async ctx => {
+            const coordinates = getMVSReferenceObject([PluginStateObject.Molecule.Coordinates], dependencies, params.coordinatesRef);
+
+            if (!coordinates) {
+                throw new Error('Coordinates not found.');
+            }
+
+            const trajectory = await getTrajectory(ctx, a, coordinates.data);
+            const props = { label: 'Trajectory', description: `${trajectory.frameCount} model${trajectory.frameCount === 1 ? '' : 's'}` };
+            return new PluginStateObject.Molecule.Trajectory(trajectory, props);
+        });
+    }
+});

src/extensions/mvs/export.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { Zip } from '../../mol-util/zip/zip';
+import { MVSData } from './mvs-data';
+
+/**
+ * Creates an MVSX zip file with from the provided data and assets
+ */
+export async function createMVSX(data: MVSData, assets: { name: string, content: string | Uint8Array }[]) {
+    const encoder = new TextEncoder();
+    const files: Record<string, Uint8Array> = {
+        'index.mvsj': encoder.encode(JSON.stringify(data)),
+    };
+    for (const asset of assets) {
+        files[asset.name] = typeof asset.content === 'string'
+            ? encoder.encode(asset.content)
+            : asset.content;
+    }
+
+    const zip = await Zip(files).run();
+    return new Uint8Array(zip);
+}

src/extensions/mvs/helpers/animation.ts

@@ -0,0 +1,605 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ * @author Ludovic Autin <ludovic.autin@gmail.com>
+ */
+
+import { SortedArray } from '../../../mol-data/int';
+import * as EasingFns from '../../../mol-math/easing';
+import { clamp, lerp } from '../../../mol-math/interpolate';
+import { EPSILON, Mat3, Mat4, Quat, Vec3 } from '../../../mol-math/linear-algebra';
+import { RuntimeContext } from '../../../mol-task';
+import { deepEqual } from '../../../mol-util';
+import { Color } from '../../../mol-util/color';
+import { produce } from '../../../mol-util/produce';
+import { makeContinuousPaletteCheckpoints, MVSContinuousPaletteProps, MVSDiscretePaletteProps } from '../components/annotation-color-theme';
+import { palettePropsFromMVSPalette } from '../load-helpers';
+import { Snapshot } from '../mvs-data';
+import { MVSAnimationEasing, MVSAnimationNode, MVSAnimationSchema } from '../tree/animation/animation-tree';
+import { Tree } from '../tree/generic/tree-schema';
+import { addDefaults } from '../tree/generic/tree-utils';
+import { MVSTree } from '../tree/mvs/mvs-tree';
+import { ColorT } from '../tree/mvs/param-types';
+
+export async function generateStateTransition(ctx: RuntimeContext, snapshot: Snapshot, snapshotIndex: number, snapshotCount: number) {
+    if (!snapshot.animation) return undefined;
+
+    const tree = addDefaults(snapshot.animation, MVSAnimationSchema);
+    const transitions = tree.children?.filter(child => child.kind === 'interpolate');
+    if (!transitions?.length) return undefined;
+
+    const duration = Math.max(
+        snapshot.animation.params?.duration_ms ?? 0,
+        ...transitions.map(t => (t.params.start_ms ?? 0) + t.params.duration_ms)
+    );
+
+    const frames: [tree: MVSTree, time: number][] = [];
+    const dt = tree.params?.frame_time_ms ?? (1000 / 60);
+    const N = Math.ceil(duration / dt);
+
+    const nodeMap = makeNodeMap(snapshot.root, new Map(), []);
+    const cache = new Map<any, InterpolationCacheEntry>();
+
+    const transitionGroups = groupTranstions(transitions);
+
+    let prevRoot: MVSTree | undefined;
+    for (let i = 0; i <= N; i++) {
+        const t = i * dt;
+        const root = createSnapshot(snapshot.root, transitionGroups, t, cache, nodeMap);
+
+        if (root === prevRoot || (prevRoot && deepEqual(root, prevRoot))) {
+            frames[frames.length - 1][1] += dt;
+        } else {
+            frames.push([root, dt]);
+        }
+
+        prevRoot = root;
+
+        if (ctx.shouldUpdate) {
+            await ctx.update({ message: `Generating transition for snapshot ${snapshotIndex + 1}/${snapshotCount}`, current: i + 1, max: N });
+        }
+    }
+
+    return { tree, frametimeMs: dt, frames };
+}
+
+const EasingFnMap: Record<MVSAnimationEasing, (t: number) => number> = {
+    'linear': t => t,
+    'bounce-in': EasingFns.bounceIn,
+    'bounce-out': EasingFns.bounceOut,
+    'bounce-in-out': EasingFns.bounceInOut,
+    'circle-in': EasingFns.circleIn,
+    'circle-out': EasingFns.circleOut,
+    'circle-in-out': EasingFns.circleInOut,
+    'cubic-in': EasingFns.cubicIn,
+    'cubic-out': EasingFns.cubicOut,
+    'cubic-in-out': EasingFns.cubicInOut,
+    'exp-in': EasingFns.expIn,
+    'exp-out': EasingFns.expOut,
+    'exp-in-out': EasingFns.expInOut,
+    'quad-in': EasingFns.quadIn,
+    'quad-out': EasingFns.quadOut,
+    'quad-in-out': EasingFns.quadInOut,
+    'sin-in': EasingFns.sinIn,
+    'sin-out': EasingFns.sinOut,
+    'sin-in-out': EasingFns.sinInOut,
+};
+
+interface InterpolationCacheEntry {
+    paletteFn?: (value: number) => Color,
+    rotation?: { axis: Vec3, angle: number, start: Quat, end: Quat },
+}
+
+function getTransitionKey(transition: MVSAnimationNode<'interpolate'>) {
+    const prop = transition.params.property;
+    if (Array.isArray(prop)) {
+        return `${transition.params.target_ref}:${prop.join('.')}`;
+    }
+    return `${transition.params.target_ref}:${prop}`;
+}
+
+function groupTranstions(transitions: MVSAnimationNode<'interpolate'>[]) {
+    const map = new Map<string, MVSAnimationNode<'interpolate'>[]>();
+    const groups: MVSAnimationNode<'interpolate'>[][] = [];
+    for (const t of transitions) {
+        const key = getTransitionKey(t);
+        if (!map.has(key)) {
+            const group: MVSAnimationNode<'interpolate'>[] = [];
+            map.set(key, group);
+            groups.push(group);
+        }
+        map.get(key)!.push(t);
+    }
+    for (const group of groups) {
+        group.sort((a, b) => {
+            const s = (a.params.start_ms ?? 0) - (b.params.start_ms ?? 0);
+            if (s !== 0) return s;
+            return a.params.duration_ms - b.params.duration_ms;
+        });
+    }
+    return groups;
+}
+
+function createSnapshot(tree: MVSTree, transitionGroups: MVSAnimationNode<'interpolate'>[][], time: number, cache: Map<any, InterpolationCacheEntry>, nodeMap: Map<string, (string | number)[]>) {
+    let modified = false;
+    const ret = produce(tree, (draft) => {
+        for (const transitionGroup of transitionGroups) {
+
+            const pivot = transitionGroup[0];
+            const nodePath = nodeMap.get(pivot.params.target_ref);
+            if (!nodePath) continue;
+
+            const node = select(draft, nodePath, 0);
+            const target = pivot.params.property[0] === 'custom' ? node?.custom : node?.params;
+            if (!target) continue;
+
+
+            const offset = pivot.params.property[0] === 'custom' ? 1 : 0;
+
+            let transition: MVSAnimationNode<'interpolate'> = pivot;
+            let previous: MVSAnimationNode<'interpolate'> | undefined;
+
+            for (let i = transitionGroup.length - 1; i > 0; i--) {
+                const current = transitionGroup[i];
+                const currentStart = current.params.start_ms ?? 0;
+                if (time >= currentStart) {
+                    transition = current;
+                    previous = i > 0 ? transitionGroup[i - 1] : undefined;
+                    break;
+                }
+            }
+
+            if (!cache.has(transition)) {
+                cache.set(transition, {});
+            }
+
+            const cacheEntry: InterpolationCacheEntry = cache.get(transition)!;
+
+            const startTime: number = transition.params.start_ms ?? 0;
+            const durationMs: number = transition.params.duration_ms ?? 0;
+            const t = (time - startTime) / durationMs;
+
+            let next: any;
+            if (transition.params.kind === 'transform_matrix') {
+                next = processTransformMatrix(transition, target, clamp(t, 0, 1), cacheEntry, offset, previous);
+            } else {
+                next = processScalarLike(transition, target, t, cacheEntry, offset, previous);
+            }
+
+            if (next === undefined) {
+                continue;
+            }
+
+            modified = true;
+            assign(target, transition.params.property, next, offset);
+        }
+    });
+    return modified ? ret : tree;
+}
+
+function applyFrequency(t: number, frequency: number, alternate: boolean) {
+    let v = (t * (frequency || 1));
+    if (v < 1) return v;
+
+    if (!alternate) {
+        v = (v % 1);
+        if (v === 0) return 1;
+        return v;
+    }
+
+    if (Math.abs(v - 1) < EPSILON) return 1;
+    v = v % 2;
+    if (v > 1) return 2 - v;
+    return v;
+}
+
+function getPreviousScalarEnd(previous: MVSAnimationNode<'interpolate'> | undefined) {
+    if (!previous || previous.params.kind === 'transform_matrix') return undefined;
+    return previous.params.end;
+}
+
+function processScalarLike(transition: MVSAnimationNode<'interpolate'>, target: any, time: number, cacheEntry: InterpolationCacheEntry, offset: number, previous: MVSAnimationNode<'interpolate'> | undefined) {
+    if (transition.params.kind === 'transform_matrix') return;
+    if (previous && previous.params.kind === 'transform_matrix') return;
+
+    const startBase = transition.params.start ?? getPreviousScalarEnd(previous) ?? select(target, transition.params.property, offset);
+    if (transition.params.kind === 'color' && !cacheEntry.paletteFn) {
+        cacheEntry.paletteFn = makePaletteFunction(transition, startBase, transition.params.end as ColorT | undefined);
+    }
+
+    const paletteFn = cacheEntry.paletteFn!;
+
+    const startValue: any = transition.params.kind === 'color'
+        ? Color.toHexStyle(paletteFn(0))
+        : startBase;
+    const endValue: any = transition.params.kind === 'color'
+        ? Color.toHexStyle(paletteFn(1))
+        : transition.params.end;
+
+    if (time <= 0) return startValue;
+    else if (time >= 1 - EPSILON && !transition.params.alternate_direction) return endValue;
+
+    let t = clamp(time, 0, 1);
+    t = applyFrequency(t, transition.params.frequency ?? 1, !!transition.params.alternate_direction);
+
+    const easing = EasingFnMap[transition.params.easing ?? 'linear'] ?? EasingFnMap['linear'];
+    t = easing(t);
+
+    if (transition.params.kind === 'scalar') {
+        return interpolateScalars(startValue, endValue, t, transition.params.noise_magnitude ?? 0, !!transition.params.discrete);
+    } else if (transition.params.kind === 'vec3') {
+        return interpolateVectors(startValue, endValue, t, transition.params.noise_magnitude ?? 0, !!transition.params.spherical);
+    } else if (transition.params.kind === 'rotation_matrix') {
+        return interpolateRotation(startValue, endValue, t, transition.params.noise_magnitude ?? 0, cacheEntry);
+    } else if (transition.params.kind === 'color') {
+        const color = paletteFn(t);
+        return Color.toHexStyle(color);
+    }
+}
+
+function getPreviousMatrixEnd(previous: MVSAnimationNode<'interpolate'> | undefined, prop: 'rotation_start' | 'translation_start' | 'scale_start') {
+    if (!previous || previous.params.kind !== 'transform_matrix') return undefined;
+    return previous.params[prop];
+}
+
+const TransformState = {
+    pivotTranslation: Mat4(),
+    pivotTranslationInv: Mat4(),
+    rotation: Mat4(),
+    scale: Mat4(),
+    translation: Mat4(),
+    pivotNeg: Vec3(),
+    temp: Mat4(),
+};
+function processTransformMatrix(transition: MVSAnimationNode<'interpolate'>, target: any, time: number, cache: InterpolationCacheEntry, offset: number, previous: MVSAnimationNode<'interpolate'> | undefined) {
+    if (transition.params.kind !== 'transform_matrix') return;
+    if (previous && previous.params.kind !== 'transform_matrix') return;
+
+    const transform = select(target, transition.params.property, offset) ?? Mat4.identity();
+
+    const startRotation = transition.params.rotation_start ?? getPreviousMatrixEnd(previous, 'rotation_start') ?? Mat3.fromMat4(Mat3(), transform);
+    const startTranslation = transition.params.translation_start ?? getPreviousMatrixEnd(previous, 'translation_start') ?? Mat4.getTranslation(Vec3(), transform);
+    const startScale = transition.params.scale_start ?? getPreviousMatrixEnd(previous, 'scale_start') ?? Mat4.getScaling(Vec3(), transform);
+
+    const endRotation = transition.params.rotation_end;
+    const endTranslation = transition.params.translation_end;
+    const endScale = transition.params.scale_end;
+
+    let rotation, translation, scale;
+
+    if (time <= 0) {
+        rotation = startRotation as Mat3;
+        translation = startTranslation as Vec3;
+        scale = startScale as Vec3;
+    } else {
+        const clampedTime = clamp(time, 0, 1);
+
+        let t = applyFrequency(clampedTime, transition.params.rotation_frequency ?? 1, !!transition.params.rotation_alternate_direction);
+        let easing = EasingFnMap[transition.params.rotation_easing ?? 'linear'] ?? EasingFnMap['linear'];
+        rotation = interpolateRotation(startRotation as Mat3, endRotation as Mat3, easing(t), transition.params.rotation_noise_magnitude ?? 0, cache);
+
+        t = applyFrequency(clampedTime, transition.params.translation_frequency ?? 1, !!transition.params.translation_alternate_direction);
+        easing = EasingFnMap[transition.params.translation_easing ?? 'linear'] ?? EasingFnMap['linear'];
+        translation = interpolateVec3(startTranslation as Vec3, endTranslation as Vec3 | undefined, easing(t), transition.params.translation_noise_magnitude ?? 0, false);
+
+        t = applyFrequency(clampedTime, transition.params.scale_frequency ?? 1, !!transition.params.scale_alternate_direction);
+        easing = EasingFnMap[transition.params.scale_easing ?? 'linear'] ?? EasingFnMap['linear'];
+        scale = interpolateVec3(startScale as Vec3, endScale as Vec3 | undefined, easing(t), transition.params.scale_noise_magnitude ?? 0, false);
+    }
+
+    const pivot = transition.params.pivot ?? Vec3.zero();
+
+    Mat4.fromTranslation(TransformState.translation, translation);
+    Mat4.fromScaling(TransformState.scale, scale);
+    Mat4.setIdentity(TransformState.rotation);
+    Mat4.fromMat3(TransformState.rotation, rotation);
+    Mat4.fromTranslation(TransformState.pivotTranslation, pivot as Vec3);
+    Mat4.fromTranslation(TransformState.pivotTranslationInv, Vec3.negate(TransformState.pivotNeg, pivot as Vec3));
+
+    // translation . pivot . rotation . scale . pivotInv
+    const result = Mat4();
+    Mat4.mul(result, TransformState.scale, TransformState.pivotTranslationInv);
+    Mat4.mul(result, TransformState.rotation, result);
+    Mat4.mul(result, TransformState.translation, result);
+
+    return result;
+}
+
+function interpolateScalars(start: number | number[], end: number | number[] | undefined, t: number, noise: number, discrete: boolean) {
+    if (Array.isArray(start)) {
+        const ret = Array.from<number>({ length: start.length }).fill(0.1);
+        if (!end || !Array.isArray(end)) {
+            for (let i = 0; i < start.length; i++) {
+                ret[i] = interpolateScalar(start[i], end, t, noise, discrete);
+            }
+            return ret;
+        }
+
+        for (let i = 0; i < start.length; i++) {
+            ret[i] = interpolateScalar(start[i], end[i], t, noise, discrete);
+        }
+        return ret;
+    }
+
+    if (Array.isArray(end)) {
+        const ret = Array.from<number>({ length: end.length }).fill(0.1);
+        for (let i = 0; i < end.length; i++) {
+            ret[i] = interpolateScalar(start, end[i], t, noise, discrete);
+        }
+        return ret;
+    }
+
+    return interpolateScalar(start, end, t, noise, discrete);
+}
+
+function interpolateScalar(start: number, end: number | undefined, t: number, noise: number, discrete: boolean) {
+    let v = typeof end === 'number' ? lerp(start, end, t) : start;
+    if (noise) {
+        v += (Math.random() - 0.5) * noise;
+    }
+    if (discrete) {
+        v = Math.round(v);
+    }
+    return v;
+}
+
+const InterpolateVectorsState = {
+    start: Vec3(),
+    end: Vec3(),
+    v: Vec3(),
+};
+function interpolateVectors(start: number[], end: number[] | undefined, t: number, noise: number, isSpherical: boolean) {
+    if ((!end || start === end) && !noise) return start;
+
+    const ret: number[] = Array.from<number>({ length: start.length }).fill(0.1);
+
+    for (let i = 0; i < start.length; i += 3) {
+        const s = Vec3.fromArray(InterpolateVectorsState.start, start, i);
+
+        let v: Vec3;
+        if (end) {
+            const e = Vec3.fromArray(InterpolateVectorsState.end, end, i);
+            v = isSpherical
+                ? Vec3.slerp(InterpolateVectorsState.v, s, e, t)
+                : Vec3.lerp(InterpolateVectorsState.v, s, e, t);
+        } else {
+            v = Vec3.clone(s);
+        }
+
+        if (noise && t <= 1 - EPSILON) {
+            Vec3.random(Vec3Noise, noise);
+            Vec3.add(v, v, Vec3Noise);
+        }
+
+        Vec3.toArray(v, ret, i);
+    }
+
+    return ret;
+}
+
+const Vec3Noise = Vec3();
+function interpolateVec3(start: Vec3, end: Vec3 | undefined, t: number, noise: number, isSpherical: boolean) {
+    if ((!end || start === end) && !noise) return start;
+
+    let v: Vec3;
+
+    if (end) {
+        v = isSpherical
+            ? Vec3.slerp(Vec3(), start, end, t)
+            : Vec3.lerp(Vec3(), start, end, t);
+    } else {
+        v = Vec3.clone(start);
+    }
+
+    if (noise && t <= 1 - EPSILON) {
+        Vec3.random(Vec3Noise, noise);
+        Vec3.add(v, v, Vec3Noise);
+    }
+    return v;
+}
+
+const RotationState = {
+    start: Quat(),
+    end: Quat(),
+    v: Quat(),
+    noise: Quat(),
+    axis: Vec3(),
+    temp: Mat4(),
+};
+function interpolateRotation(start: Mat3, end: Mat3 | undefined, t: number, noise: number, cache: InterpolationCacheEntry) {
+    if ((!end || start === end) && !noise) return start;
+
+    if (end) {
+        if (!cache.rotation) {
+            cache.rotation = {
+                ...relativeAxisAngle(start, end),
+                start: Quat.fromMat3(Quat(), start),
+                end: Quat.fromMat3(Quat(), end),
+            };
+        }
+
+        const { axis, angle, start: startQ, end: endQ } = cache.rotation;
+
+        if (angle < 1e-6) {
+            // start ≈ end: make a clean spin about the detected (or default) axis
+            Quat.setAxisAngle(RotationState.v, axis, t * 2 * Math.PI); // Make a full turn
+        } else {
+            // Normal case: stick with your existing slerp between start/end
+            Quat.slerp(RotationState.v, startQ, endQ, t);
+        }
+    } else {
+        Quat.fromMat3(RotationState.v, start);
+    }
+
+    if (noise && t <= 1 - EPSILON) {
+        Vec3.random(RotationState.axis, 1);
+        Quat.setAxisAngle(RotationState.noise, RotationState.axis, 2 * Math.PI * noise * (Math.random() - 0.5));
+        Quat.multiply(RotationState.v, RotationState.noise, RotationState.v);
+    }
+    Mat4.fromQuat(RotationState.temp, RotationState.v);
+    return Mat3.fromMat4(Mat3(), RotationState.temp);
+}
+
+function select(params: any, path: string | (string | number)[], offset: number) {
+    if (typeof path === 'string') {
+        return params?.[path];
+    }
+
+    let f = params;
+    for (let i = offset; i < path.length; i++) {
+        if (!f) break;
+        f = f[path[i]];
+    }
+
+    return f;
+}
+
+function assign(params: any, path: string | (string | number)[], value: any, offset: number) {
+    if (!params) return;
+
+    if (typeof path === 'string') {
+        params[path] = value;
+        return;
+    }
+
+    let f = params;
+    for (let i = offset; i < path.length; i++) {
+        if (!f) break;
+        if (i === path.length - 1) {
+            f[path[i]] = value;
+        } else {
+            f = f[path[i]];
+        }
+    }
+}
+
+function makeNodeMap(tree: Tree, map: Map<string, (string | number)[]>, currentPath: (string | number)[]) {
+    if (tree.ref) {
+        map.set(tree.ref, [...currentPath]);
+    }
+
+    if (!tree.children) return map;
+
+    currentPath.push('children');
+    for (let i = 0; i < tree.children.length; i++) {
+        const child = tree.children[i];
+        currentPath.push(i);
+        makeNodeMap(child, map, currentPath);
+        currentPath.pop();
+    }
+    currentPath.pop();
+
+    return map;
+}
+
+function makePaletteFunction(props: MVSAnimationNode<'interpolate'>, start: ColorT | undefined | null, end: ColorT | undefined | null): ((value: number) => Color) | undefined {
+    if (props.params.kind !== 'color') return undefined;
+
+    const params = props.params.palette
+        ? palettePropsFromMVSPalette(props.params.palette)
+        : palettePropsFromMVSPalette({ kind: 'continuous', colors: [start ?? 'black', end ?? start ?? 'black'] });
+    if (params.name === 'discrete') return makePaletteFunctionDiscrete(params.params);
+    if (params.name === 'continuous') return makePaletteFunctionContinuous(params.params);
+    throw new Error(`NotImplementedError: makePaletteFunction for ${(props as any).name}`);
+}
+
+
+function makePaletteFunctionDiscrete(props: MVSDiscretePaletteProps): (value: number) => Color {
+    const defaultColor = Color(0x0);
+    if (props.colors.length === 0) return () => defaultColor;
+
+    return (value: number) => {
+        const x = clamp(value, 0, 1);
+        for (let i = props.colors.length - 1; i >= 0; i--) {
+            const { color, fromValue, toValue } = props.colors[i];
+            if (fromValue <= x && x <= toValue) return color;
+        }
+        return defaultColor;
+    };
+}
+
+function makePaletteFunctionContinuous(props: MVSContinuousPaletteProps): (value: number) => Color {
+    const defaultColor = Color(0x0);
+    const { colors, checkpoints } = makeContinuousPaletteCheckpoints(props);
+    if (colors.length === 0) return () => defaultColor;
+
+    const underflowColor = props.setUnderflowColor ? props.underflowColor : defaultColor;
+    const overflowColor = props.setOverflowColor ? props.overflowColor : defaultColor;
+
+    return (value: number) => {
+        const x = clamp(value, 0, 1);
+        const gteIdx = SortedArray.findPredecessorIndex(checkpoints, x); // Index of the first greater or equal checkpoint
+        if (gteIdx === 0) {
+            if (x === checkpoints[0]) return colors[0];
+            else return underflowColor;
+        }
+        if (gteIdx === checkpoints.length) {
+            return overflowColor;
+        }
+        const q = (x - checkpoints[gteIdx - 1]) / (checkpoints[gteIdx] - checkpoints[gteIdx - 1]);
+        return Color.interpolate(colors[gteIdx - 1], colors[gteIdx], q);
+    };
+}
+
+const RelativeAxisAngleState = {
+    Rt: Mat3(),
+    R: Mat3(),
+};
+function relativeAxisAngle(start: Mat3, end: Mat3): { axis: Vec3, angle: number } {
+    // R_rel = end * start^T
+    const R0 = start, R1 = end;
+    const Rt = Mat3.transpose(RelativeAxisAngleState.Rt, R0);
+    const R = Mat3.mul(RelativeAxisAngleState.R, R1, Rt);
+
+    const tr = R[0] + R[4] + R[8]; // trace
+    let angle = Math.acos(clamp((tr - 1) * 0.5, -1, 1)); // in [0, π]
+    const axis = Vec3();
+
+    const eps = 1e-6;
+    const sinA = Math.sin(angle);
+
+    if (angle < eps) {
+        // Near identity: axis undefined; return any unit axis (choose something stable)
+        Vec3.set(axis, 0, 0, 1);
+        angle = 0.0;
+        return { axis, angle };
+    }
+
+    if (Math.PI - angle > 1e-4) {
+        // General case
+        axis[0] = (R[5] - R[7]) / (2 * sinA); // (r32 - r23)
+        axis[1] = (R[6] - R[2]) / (2 * sinA); // (r13 - r31)
+        axis[2] = (R[1] - R[3]) / (2 * sinA); // (r21 - r12)
+        Vec3.normalize(axis, axis);
+        return { axis, angle };
+    }
+
+    // angle ~ π: use diagonal-based extraction for stability
+    // Compute squared components then pick the largest to avoid precision loss
+    const xx = Math.max(0, (R[0] + 1) * 0.5);
+    const yy = Math.max(0, (R[4] + 1) * 0.5);
+    const zz = Math.max(0, (R[8] + 1) * 0.5);
+
+    let x = Math.sqrt(xx), y = Math.sqrt(yy), z = Math.sqrt(zz);
+
+    if (x >= y && x >= z) {
+        x = Math.max(x, 1e-8);
+        y = (R[1] + R[3]) / (4 * x);
+        z = (R[2] + R[6]) / (4 * x);
+        Vec3.set(axis, x, y, z);
+    } else if (y >= x && y >= z) {
+        y = Math.max(y, 1e-8);
+        x = (R[1] + R[3]) / (4 * y);
+        z = (R[5] + R[7]) / (4 * y);
+        Vec3.set(axis, x, y, z);
+    } else {
+        z = Math.max(z, 1e-8);
+        x = (R[2] + R[6]) / (4 * z);
+        y = (R[5] + R[7]) / (4 * z);
+        Vec3.set(axis, x, y, z);
+    }
+
+    Vec3.normalize(axis, axis);
+    return { axis, angle: Math.PI };
+}

src/extensions/mvs/helpers/colors.ts

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Adam Midlik <midlik@gmail.com>
+ */
+
+import { ElementSymbolColors } from '../../../mol-theme/color/element-symbol';
+import { ResidueNameColors } from '../../../mol-theme/color/residue-name';
+import { SecondaryStructureColors as SecStrColors } from '../../../mol-theme/color/secondary-structure';
+import { Color } from '../../../mol-util/color';
+import { ColorList } from '../../../mol-util/color/color';
+import { ColorLists } from '../../../mol-util/color/lists';
+import { omitObjectKeys } from '../../../mol-util/object';
+import { ColorDictNameT, ColorListNameT } from '../tree/mvs/param-types';
+import { decodeColor } from './utils';
+
+
+/** Colors for amino acid groups, based on Clustal (https://www.jalview.org/help/html/colourSchemes/clustal.html) */
+const AminoGroupColors = {
+    aromatic: decodeColor('#15A4A4')!,
+    hydrophobic: decodeColor('#80A0F0')!,
+    polar: decodeColor('#15C015')!,
+    positive: decodeColor('#F01505')!,
+    negative: decodeColor('#C048C0')!,
+    proline: decodeColor('#C0C000')!,
+    cysteine: decodeColor('#F08080')!,
+    glycine: decodeColor('#F09048')!,
+};
+
+/** Colors for individual amino acids, based on Clustal (https://www.jalview.org/help/html/colourSchemes/clustal.html), plus Jmol colors for nucleotides (http://jmol.sourceforge.net/jscolors/) */
+const ResiduePropertyColors = {
+    ...ResidueNameColors,
+    HIS: AminoGroupColors.aromatic,
+    TYR: AminoGroupColors.aromatic,
+    ALA: AminoGroupColors.hydrophobic,
+    VAL: AminoGroupColors.hydrophobic,
+    LEU: AminoGroupColors.hydrophobic,
+    ILE: AminoGroupColors.hydrophobic,
+    MET: AminoGroupColors.hydrophobic,
+    PHE: AminoGroupColors.hydrophobic,
+    TRP: AminoGroupColors.hydrophobic,
+    SER: AminoGroupColors.polar,
+    THR: AminoGroupColors.polar,
+    ASN: AminoGroupColors.polar,
+    GLN: AminoGroupColors.polar,
+    LYS: AminoGroupColors.positive,
+    ARG: AminoGroupColors.positive,
+    ASP: AminoGroupColors.negative,
+    GLU: AminoGroupColors.negative,
+    PRO: AminoGroupColors.proline,
+    CYS: AminoGroupColors.cysteine,
+    GLY: AminoGroupColors.glycine,
+};
+
+/** Colors for secondary structure types, based on Jmol colors (http://jmol.sourceforge.net/jscolors/) */
+const SecondaryStructureColors = {
+    // Simple categories
+    helix: SecStrColors.alphaHelix,
+    strand: SecStrColors.betaStrand,
+    turn: SecStrColors.betaTurn,
+    bend: SecStrColors.bend,
+
+    // DSSP categories
+    H: SecStrColors.alphaHelix,
+    B: SecStrColors.betaStrand,
+    E: SecStrColors.betaStrand,
+    G: SecStrColors.threeTenHelix,
+    I: SecStrColors.piHelix,
+    P: Color(0xA00000), // Polyproline II helix, Jmol has no color for it
+    T: SecStrColors.betaTurn,
+    S: SecStrColors.bend,
+};
+
+export const MvsNamedColorDicts: Record<ColorDictNameT, Record<string, Color>> = {
+    ElementSymbol: omitObjectKeys(ElementSymbolColors, ['C']), // ommitting carbon color to allow easier combination of multiple color layers
+    ResidueName: ResidueNameColors,
+    ResidueProperties: ResiduePropertyColors,
+    SecondaryStructure: SecondaryStructureColors,
+};
+
+export const MvsNamedColorLists: Record<ColorListNameT, ColorList> = {
+    // Sequential single-hue
+    Reds: ColorLists['reds'],
+    Oranges: ColorLists['oranges'],
+    Greens: ColorLists['greens'],
+    Blues: ColorLists['blues'],
+    Purples: ColorLists['purples'],
+    Greys: ColorLists['greys'],
+
+    // Sequential multi-hue
+    OrRd: ColorLists['orange-red'],
+    BuGn: ColorLists['blue-green'],
+    PuBuGn: ColorLists['purple-blue-green'],
+    GnBu: ColorLists['green-blue'],
+    PuBu: ColorLists['purple-blue'],
+    BuPu: ColorLists['blue-purple'],
+    RdPu: ColorLists['red-purple'],
+    PuRd: ColorLists['purple-red'],
+    YlOrRd: ColorLists['yellow-orange-red'],
+    YlOrBr: ColorLists['yellow-orange-brown'],
+    YlGn: ColorLists['yellow-green'],
+    YlGnBu: ColorLists['yellow-green-blue'],
+
+    Magma: ColorLists['magma'],
+    Inferno: ColorLists['inferno'],
+    Plasma: ColorLists['plasma'],
+    Viridis: ColorLists['viridis'],
+    Cividis: ColorLists['cividis'],
+    Turbo: ColorLists['turbo'],
+    Warm: ColorLists['warm'],
+    Cool: ColorLists['cool'],
+    CubehelixDefault: ColorLists['cubehelix-default'],
+
+    // Cyclical
+    Rainbow: ColorLists['rainbow'],
+    Sinebow: ColorLists['sinebow'],
+
+    // Diverging
+    RdBu: ColorLists['red-blue'],
+    RdGy: ColorLists['red-grey'],
+    PiYG: ColorLists['pink-yellow-green'],
+    BrBG: ColorLists['brown-white-green'],
+    PRGn: ColorLists['purple-green'],
+    PuOr: ColorLists['purple-orange'],
+    RdYlGn: ColorLists['red-yellow-green'],
+    RdYlBu: ColorLists['red-yellow-blue'],
+    Spectral: ColorLists['spectral'],
+
+    // Categorical
+    Category10: ColorLists['category-10'],
+    Observable10: ColorLists['observable-10'],
+    Tableau10: ColorLists['tableau-10'],
+
+    Set1: ColorLists['set-1'],
+    Set2: ColorLists['set-2'],
+    Set3: ColorLists['set-3'],
+    Pastel1: ColorLists['pastel-1'],
+    Pastel2: ColorLists['pastel-2'],
+    Dark2: ColorLists['dark-2'],
+    Paired: ColorLists['paired'],
+    Accent: ColorLists['accent'],
+
+    // Additional lists, not standard for visualization in general, but commonly used for structures
+    Chainbow: ColorLists['turbo-no-black'],
+};

src/extensions/mvs/helpers/indexing.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -19,6 +19,12 @@ export interface IndicesAndSortings {
     residuesSortedByLabelSeqId: Mapping<ChainIndex, Sorting<ResidueIndex, number>>,
     residuesSortedByAuthSeqId: Mapping<ChainIndex, Sorting<ResidueIndex, number>>,
     residuesByInsCode: Mapping<ChainIndex, Mapping<string, readonly ResidueIndex[]>>,
+    residuesByLabelCompId: Mapping<ChainIndex, Mapping<string, readonly ResidueIndex[]>>,
+    /** Indicates if each residue is listed only once in `residuesByLabelCompId` (i.e. if each residue has only one label_comp_id) */
+    residuesByLabelCompIdIsPure: boolean,
+    residuesByAuthCompId: Mapping<ChainIndex, Mapping<string, readonly ResidueIndex[]>>,
+    /** Indicates if each residue is listed only once in `residuesByAuthCompId` (i.e. if each residue has only one auth_comp_id) */
+    residuesByAuthCompIdIsPure: boolean,
     atomsById: Mapping<number, ElementIndex>,
     atomsByIndex: Mapping<number, ElementIndex>,
 }
@@ -36,6 +42,7 @@ export const IndicesAndSortings = {
         const nChains = h.chains._rowCount;
         const { label_entity_id, label_asym_id, auth_asym_id } = h.chains;
         const { label_seq_id, auth_seq_id, pdbx_PDB_ins_code } = h.residues;
+        const { label_comp_id, auth_comp_id } = h.atoms;
         const { Present } = Column.ValueKind;
 
         const chainsByLabelEntityId = new MultiMap<string, ChainIndex>();
@@ -44,9 +51,16 @@ export const IndicesAndSortings = {
         const residuesSortedByLabelSeqId = new Map<ChainIndex, Sorting<ResidueIndex, number>>();
         const residuesSortedByAuthSeqId = new Map<ChainIndex, Sorting<ResidueIndex, number>>();
         const residuesByInsCode = new Map<ChainIndex, MultiMap<string, ResidueIndex>>();
+        const residuesByLabelCompId = new Map<ChainIndex, MultiMap<string, ResidueIndex>>();
+        let residuesByLabelCompIdIsPure = true;
+        const residuesByAuthCompId = new Map<ChainIndex, MultiMap<string, ResidueIndex>>();
+        let residuesByAuthCompIdIsPure = true;
         const atomsById = new NumberMap<number, ElementIndex>(nAtoms + 1);
         const atomsByIndex = new NumberMap<number, ElementIndex>(nAtoms);
 
+        const _labelCompIdSet = new Set<string>();
+        const _authCompIdSet = new Set<string>();
+
         for (let iChain = 0 as ChainIndex; iChain < nChains; iChain++) {
             chainsByLabelEntityId.add(label_entity_id.value(iChain), iChain);
             chainsByLabelAsymId.add(label_asym_id.value(iChain), iChain);
@@ -62,12 +76,28 @@ export const IndicesAndSortings = {
             residuesSortedByAuthSeqId.set(iChain, Sorting.create(residuesWithAuthSeqId, auth_seq_id.value));
 
             const residuesHereByInsCode = new MultiMap<string, ResidueIndex>();
+            const residuesHereByLabelCompId = new MultiMap<string, ResidueIndex>();
+            const residuesHereByAuthCompId = new MultiMap<string, ResidueIndex>();
             for (let iRes = iResFrom; iRes < iResTo; iRes++) {
                 if (pdbx_PDB_ins_code.valueKind(iRes) === Present) {
                     residuesHereByInsCode.add(pdbx_PDB_ins_code.value(iRes), iRes);
                 }
+                const iAtomFrom = h.residueAtomSegments.offsets[iRes];
+                const iAtomTo = h.residueAtomSegments.offsets[iRes + 1];
+                for (let iAtom = iAtomFrom; iAtom < iAtomTo; iAtom++) {
+                    _labelCompIdSet.add(label_comp_id.value(iAtom));
+                    _authCompIdSet.add(auth_comp_id.value(iAtom));
+                }
+                if (_labelCompIdSet.size > 1) residuesByLabelCompIdIsPure = false;
+                if (_authCompIdSet.size > 1) residuesByAuthCompIdIsPure = false;
+                for (const labelCompId of _labelCompIdSet) residuesHereByLabelCompId.add(labelCompId, iRes);
+                for (const authCompId of _authCompIdSet) residuesHereByAuthCompId.add(authCompId, iRes);
+                _labelCompIdSet.clear();
+                _authCompIdSet.clear();
             }
             residuesByInsCode.set(iChain, residuesHereByInsCode);
+            residuesByLabelCompId.set(iChain, residuesHereByLabelCompId);
+            residuesByAuthCompId.set(iChain, residuesHereByAuthCompId);
         }
 
         const atomId = model.atomicConformation.atomId.value;
@@ -80,6 +110,7 @@ export const IndicesAndSortings = {
         return {
             chainsByLabelEntityId, chainsByLabelAsymId, chainsByAuthAsymId,
             residuesSortedByLabelSeqId, residuesSortedByAuthSeqId, residuesByInsCode,
+            residuesByLabelCompId, residuesByLabelCompIdIsPure, residuesByAuthCompId, residuesByAuthCompIdIsPure,
             atomsById, atomsByIndex,
         };
     },

src/extensions/mvs/helpers/label-text.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -7,13 +7,13 @@
 import { Sphere3D } from '../../../mol-math/geometry';
 import { BoundaryHelper } from '../../../mol-math/geometry/boundary-helper';
 import { Vec3 } from '../../../mol-math/linear-algebra';
-import { ElementIndex, Model, Structure, StructureElement, StructureProperties } from '../../../mol-model/structure';
-import { UUID } from '../../../mol-util';
+import { ElementIndex, Model, Structure, StructureElement, StructureProperties, Unit } from '../../../mol-model/structure';
 import { arrayExtend } from '../../../mol-util/array';
 import { AtomRanges } from './atom-ranges';
 import { IndicesAndSortings } from './indexing';
 import { MVSAnnotationRow } from './schemas';
 import { getAtomRangesForRows } from './selections';
+import { isDefined } from './utils';
 
 
 /** Properties describing position, size, etc. of a text in 3D */
@@ -34,9 +34,25 @@ const boundaryHelper = new BoundaryHelper('98');
 const outAtoms: ElementIndex[] = [];
 const outFirstAtomIndex: { value?: number } = {};
 
+/** Helper for caching atom ranges qualifying to a group of annotation rows, per `Unit`. */
+class AtomRangesCache {
+    private readonly cache: { [key: string]: AtomRanges } = {};
+    private readonly hasOperators: boolean;
+
+    constructor(private readonly rows: MVSAnnotationRow[]) {
+        this.hasOperators = rows.some(row => isDefined(row.instance_id));
+    }
+
+    get(unit: Unit): AtomRanges {
+        const instanceId = unit.conformation.operator.instanceId;
+        const key = this.hasOperators ? `${unit.model.id}:${instanceId}` : unit.model.id;
+        return this.cache[key] ??= getAtomRangesForRows(this.rows, unit.model, instanceId, IndicesAndSortings.get(unit.model));
+    }
+}
+
 /** Return `TextProps` (position, size, etc.) for a text that is to be bound to a substructure of `structure` defined by union of `rows`.
  * Derives `center` and `depth` from the boundary sphere of the substructure, `scale` from the number of heavy atoms in the substructure. */
-export function textPropsForSelection(structure: Structure, sizeFunction: (location: StructureElement.Location) => number, rows: MVSAnnotationRow | MVSAnnotationRow[], onlyInModel?: Model): TextProps | undefined {
+export function textPropsForSelection(structure: Structure, sizeFunction: (location: StructureElement.Location) => number, rows: MVSAnnotationRow[], onlyInModel?: Model): TextProps | undefined {
     const loc = StructureElement.Location.create(structure);
     const { units } = structure;
     const { type_symbol } = StructureProperties.atom;
@@ -45,11 +61,11 @@ export function textPropsForSelection(structure: Structure, sizeFunction: (locat
     let includedHeavyAtoms = 0;
     let group: number | undefined = undefined;
     let atomSize: number | undefined = undefined;
-    const rangesByModel: { [modelId: UUID]: AtomRanges } = {};
+    const atomRangesCache = new AtomRangesCache(rows);
     for (let iUnit = 0, nUnits = units.length; iUnit < nUnits; iUnit++) {
         const unit = units[iUnit];
         if (onlyInModel && unit.model.id !== onlyInModel.id) continue;
-        const ranges = rangesByModel[unit.model.id] ??= getAtomRangesForRows(unit.model, rows, IndicesAndSortings.get(unit.model));
+        const ranges = atomRangesCache.get(unit);
         loc.unit = unit;
         AtomRanges.selectAtomsInRanges(unit.elements, ranges, outAtoms, outFirstAtomIndex);
         for (const atom of outAtoms) {

src/extensions/mvs/helpers/param-definition.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -7,29 +7,44 @@
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 
 
-/** Similar to `PD.Numeric` but allows leaving empty field in UI (treated as `undefined`) */
-export function MaybeIntegerParamDefinition(defaultValue?: number, info?: PD.Info): PD.Base<number | undefined> {
-    return PD.Converted<number | undefined, PD.Text>(stringifyMaybeInt, parseMaybeInt, PD.Text(stringifyMaybeInt(defaultValue), info));
+/** Similar to `PD.Numeric` but allows leaving empty field in UI (treated as `undefined`), and can only have integer values */
+export function MaybeIntegerParamDefinition(info?: PD.Info & { placeholder?: string }): PD.Converted<number | null, string> {
+    const defaultValue = null; // the default must be null, otherwise real nulls would be replaced by the default
+    return PD.Converted(stringifyMaybeInt, parseMaybeInt, PD.Text(stringifyMaybeInt(defaultValue), { ...info, disableInteractiveUpdates: true, placeholder: info?.placeholder ?? 'null' }));
 }
-/** The magic with negative zero looks crazy, but it's needed if we want to be able to write negative numbers, LOL. Please help if you know a better solution. */
-function parseMaybeInt(input: string): number | undefined {
-    if (input.trim() === '-') return -0;
+function parseMaybeInt(input: string): number | null {
     const num = parseInt(input);
-    return isNaN(num) ? undefined : num;
+    return isNaN(num) ? null : num;
 }
-function stringifyMaybeInt(num: number | undefined): string {
-    if (num === undefined) return '';
-    if (Object.is(num, -0)) return '-';
+function stringifyMaybeInt(num: number | null): string {
+    if (num === null) return '';
     return num.toString();
 }
 
+
+/** Similar to `PD.Numeric` but allows leaving empty field in UI (treated as `undefined`) */
+export function MaybeFloatParamDefinition(info?: PD.Info & { placeholder?: string }): PD.Converted<number | null, string> {
+    const defaultValue = null; // the default must be null, otherwise real nulls would be replaced by the default
+    return PD.Converted(stringifyMaybeFloat, parseMaybeFloat, PD.Text(stringifyMaybeFloat(defaultValue), { ...info, disableInteractiveUpdates: true, placeholder: info?.placeholder ?? 'null' }));
+}
+function parseMaybeFloat(input: string): number | null {
+    const num = parseFloat(input);
+    return isNaN(num) ? null : num;
+}
+function stringifyMaybeFloat(num: number | null): string {
+    if (num === null) return '';
+    return num.toString();
+}
+
+
 /** Similar to `PD.Text` but leaving empty field in UI is treated as `undefined` */
-export function MaybeStringParamDefinition(defaultValue?: string, info?: PD.Info): PD.Base<string | undefined> {
-    return PD.Converted<string | undefined, PD.Text>(stringifyMaybeString, parseMaybeString, PD.Text(stringifyMaybeString(defaultValue), info));
+export function MaybeStringParamDefinition(info?: PD.Info & { placeholder?: string }): PD.Converted<string | null, string> {
+    const defaultValue = null; // the default must be null, otherwise real nulls would be replaced by the default
+    return PD.Converted(stringifyMaybeString, parseMaybeString, PD.Text(stringifyMaybeString(defaultValue), { ...info, placeholder: info?.placeholder ?? 'null' }));
 }
-function parseMaybeString(input: string): string | undefined {
-    return input === '' ? undefined : input;
+function parseMaybeString(input: string): string | null {
+    return input === '' ? null : input;
 }
-function stringifyMaybeString(str: string | undefined): string {
-    return str === undefined ? '' : str;
+function stringifyMaybeString(str: string | null): string {
+    return str === null ? '' : str;
 }

src/extensions/mvs/helpers/schemas.ts

@@ -63,6 +63,9 @@ const AllAtomicCifAnnotationSchema = {
     beg_auth_seq_id: int,
     /** Maximum auth_seq_id (inclusive) */
     end_auth_seq_id: int,
+    label_comp_id: str,
+    auth_comp_id: str,
+    // residue_index: int, // 0-based residue index in the source file // TODO this is defined in Python builder but not supported by Molstar yet
 
     /** Atom name like 'CA', 'N', 'O'... */
     label_atom_id: str,
@@ -74,6 +77,9 @@ const AllAtomicCifAnnotationSchema = {
     atom_id: int,
     /** 0-based index of the atom in the source data */
     atom_index: int,
+    /** Instance identifier to distinguish instances of the same chain created by applying different symmetry operators,
+     * like 'ASM-X0-1' for assemblies or '1_555' for crystals */
+    instance_id: str,
 } satisfies Table.Schema;
 
 /** Allowed fields (i.e. CIF columns or JSON keys) for each annotation schema

src/extensions/mvs/helpers/selections.ts

@@ -19,13 +19,19 @@ const EmptyArray: readonly any[] = [];
 
 
 /** Return atom ranges in `model` which satisfy criteria given by `row` */
-export function getAtomRangesForRow(model: Model, row: MVSAnnotationRow, indices: IndicesAndSortings): AtomRanges {
+export function getAtomRangesForRow(row: MVSAnnotationRow, model: Model, instanceId: string, indices: IndicesAndSortings): AtomRanges {
+    if (isDefined(row.instance_id) && row.instance_id !== instanceId) return AtomRanges.empty();
+
     const h = model.atomicHierarchy;
     const nAtoms = h.atoms._rowCount;
 
     const hasAtomIds = isAnyDefined(row.atom_id, row.atom_index);
-    const hasAtomFilter = isAnyDefined(row.label_atom_id, row.auth_atom_id, row.type_symbol);
-    const hasResidueFilter = isAnyDefined(row.label_seq_id, row.auth_seq_id, row.pdbx_PDB_ins_code, row.beg_label_seq_id, row.end_label_seq_id, row.beg_auth_seq_id, row.end_auth_seq_id);
+    const hasAtomFilter = isAnyDefined(row.label_atom_id, row.auth_atom_id, row.type_symbol)
+        || isDefined(row.label_comp_id) && !indices.residuesByLabelCompIdIsPure
+        || isDefined(row.auth_comp_id) && !indices.residuesByAuthCompIdIsPure;
+    const hasResidueFilter = isAnyDefined(row.label_seq_id, row.auth_seq_id, row.pdbx_PDB_ins_code,
+        row.beg_label_seq_id, row.end_label_seq_id, row.beg_auth_seq_id, row.end_auth_seq_id,
+        row.label_comp_id, row.auth_comp_id);
     const hasChainFilter = isAnyDefined(row.label_asym_id, row.auth_asym_id, row.label_entity_id);
 
     if (hasAtomIds) {
@@ -66,12 +72,8 @@ export function getAtomRangesForRow(model: Model, row: MVSAnnotationRow, indices
 }
 
 /** Return atom ranges in `model` which satisfy criteria given by any of `rows` (atoms that satisfy more rows are still included only once) */
-export function getAtomRangesForRows(model: Model, rows: MVSAnnotationRow | MVSAnnotationRow[], indices: IndicesAndSortings): AtomRanges {
-    if (Array.isArray(rows)) {
-        return AtomRanges.union(rows.map(row => getAtomRangesForRow(model, row, indices)));
-    } else {
-        return getAtomRangesForRow(model, rows, indices);
-    }
+export function getAtomRangesForRows(rows: MVSAnnotationRow[], model: Model, instanceId: string, indices: IndicesAndSortings): AtomRanges {
+    return AtomRanges.union(rows.map(row => getAtomRangesForRow(row, model, instanceId, indices)));
 }
 
 
@@ -103,6 +105,8 @@ function getQualifyingChains(model: Model, row: MVSAnnotationRow, indices: Indic
 /** Return an array of residue indexes which satisfy criteria given by `row` */
 function getQualifyingResidues(model: Model, row: MVSAnnotationRow, indices: IndicesAndSortings, fromChains: readonly ChainIndex[]): ResidueIndex[] {
     const { label_seq_id, auth_seq_id, pdbx_PDB_ins_code } = model.atomicHierarchy.residues;
+    const { label_comp_id, auth_comp_id } = model.atomicHierarchy.atoms;
+    const { residueAtomSegments, chainAtomSegments } = model.atomicHierarchy;
     const { Present } = Column.ValueKind;
     const result: ResidueIndex[] = [];
     for (const iChain of fromChains) {
@@ -152,8 +156,37 @@ function getQualifyingResidues(model: Model, row: MVSAnnotationRow, indices: Ind
                 residuesHere = Sorting.getKeysWithValueInRange(sorting, row.beg_auth_seq_id, row.end_auth_seq_id);
             }
         }
+        if (isDefined(row.label_comp_id)) {
+            if (residuesHere) {
+                if (indices.residuesByLabelCompIdIsPure) {
+                    residuesHere = residuesHere.filter(i => label_comp_id.value(residueAtomSegments.offsets[i]) === row.label_comp_id);
+                } else {
+                    residuesHere = residuesHere.filter(i => {
+                        for (let iAtom = residueAtomSegments.offsets[i], stop = residueAtomSegments.offsets[i + 1]; iAtom < stop; iAtom++) {
+                            if (label_comp_id.value(iAtom) === row.label_comp_id) return true;
+                        }
+                    });
+                }
+            } else {
+                residuesHere = indices.residuesByLabelCompId.get(iChain)!.get(row.label_comp_id) ?? EmptyArray;
+            }
+        }
+        if (isDefined(row.auth_comp_id)) {
+            if (residuesHere) {
+                if (indices.residuesByAuthCompIdIsPure) {
+                    residuesHere = residuesHere.filter(i => auth_comp_id.value(residueAtomSegments.offsets[i]) === row.auth_comp_id);
+                } else {
+                    residuesHere = residuesHere.filter(i => {
+                        for (let iAtom = residueAtomSegments.offsets[i], stop = residueAtomSegments.offsets[i + 1]; iAtom < stop; iAtom++) {
+                            if (auth_comp_id.value(iAtom) === row.auth_comp_id) return true;
+                        }
+                    });
+                }
+            } else {
+                residuesHere = indices.residuesByAuthCompId.get(iChain)!.get(row.auth_comp_id) ?? EmptyArray;
+            }
+        }
         if (!residuesHere) {
-            const { residueAtomSegments, chainAtomSegments } = model.atomicHierarchy;
             const firstResidueForChain = residueAtomSegments.index[chainAtomSegments.offsets[iChain]];
             const firstResidueAfterChain = residueAtomSegments.index[chainAtomSegments.offsets[iChain + 1] - 1] + 1;
             residuesHere = range(firstResidueForChain, firstResidueAfterChain) as ResidueIndex[];
@@ -165,7 +198,7 @@ function getQualifyingResidues(model: Model, row: MVSAnnotationRow, indices: Ind
 
 /** Return an array of atom indexes which satisfy criteria given by `row` */
 function getQualifyingAtoms(model: Model, row: MVSAnnotationRow, indices: IndicesAndSortings, fromResidues: readonly ResidueIndex[]): ElementIndex[] {
-    const { label_atom_id, auth_atom_id, type_symbol } = model.atomicHierarchy.atoms;
+    const { label_atom_id, auth_atom_id, type_symbol, label_comp_id, auth_comp_id } = model.atomicHierarchy.atoms;
     const residueAtomSegments_offsets = model.atomicHierarchy.residueAtomSegments.offsets;
     const result: ElementIndex[] = [];
     for (const iRes of fromResidues) {
@@ -179,6 +212,12 @@ function getQualifyingAtoms(model: Model, row: MVSAnnotationRow, indices: Indice
         if (isDefined(row.type_symbol)) {
             filterInPlace(atomIdcs, iAtom => type_symbol.value(iAtom) === row.type_symbol?.toUpperCase());
         }
+        if (isDefined(row.label_comp_id) && !indices.residuesByLabelCompIdIsPure) {
+            filterInPlace(atomIdcs, iAtom => label_comp_id.value(iAtom) === row.label_comp_id);
+        }
+        if (isDefined(row.auth_comp_id) && !indices.residuesByAuthCompIdIsPure) {
+            filterInPlace(atomIdcs, iAtom => auth_comp_id.value(iAtom) === row.auth_comp_id);
+        }
         arrayExtend(result, atomIdcs);
     }
     return result;
@@ -228,11 +267,15 @@ export function atomQualifies(model: Model, iAtom: ElementIndex, row: MVSAnnotat
     if (!matchesRange(row.beg_label_seq_id, row.end_label_seq_id, label_seq_id)) return false;
     if (!matchesRange(row.beg_auth_seq_id, row.end_auth_seq_id, auth_seq_id)) return false;
 
+    const label_comp_id = h.atoms.label_comp_id.value(iAtom);
+    const auth_comp_id = h.atoms.auth_comp_id.value(iAtom);
     const label_atom_id = h.atoms.label_atom_id.value(iAtom);
     const auth_atom_id = h.atoms.auth_atom_id.value(iAtom);
     const type_symbol = h.atoms.type_symbol.value(iAtom);
     const atom_id = model.atomicConformation.atomId.value(iAtom);
     const atom_index = h.atomSourceIndex.value(iAtom);
+    if (!matches(row.label_comp_id, label_comp_id)) return false;
+    if (!matches(row.auth_comp_id, auth_comp_id)) return false;
     if (!matches(row.label_atom_id, label_atom_id)) return false;
     if (!matches(row.auth_atom_id, auth_atom_id)) return false;
     if (!matches(row.type_symbol?.toUpperCase(), type_symbol)) return false;
@@ -287,7 +330,7 @@ export function groupRows(rows: readonly MVSAnnotationRow[]): GroupedArray<numbe
     const groups: number[] = [];
     for (let i = 0; i < rows.length; i++) {
         const group_id = rows[i].group_id;
-        if (group_id === undefined) {
+        if (!isDefined(group_id)) {
             groups.push(counter++);
         } else {
             const groupIndex = groupMap.get(group_id);

src/extensions/mvs/helpers/utils.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  * @author David Sehnal <david.sehnal@gmail.com>
@@ -9,6 +9,7 @@ import { hashString } from '../../../mol-data/util';
 import { StateObject } from '../../../mol-state';
 import { Color } from '../../../mol-util/color';
 import { ColorNames } from '../../../mol-util/color/names';
+import { decodeColor as _decodeColor } from '../../../mol-util/color/utils';
 
 
 /** Represents either the result or the reason of failure of an operation that might have failed */
@@ -75,7 +76,7 @@ export function isDefined<T>(value: T | undefined | null): value is T {
 }
 /** Return `true` if at least one of `values` is not `undefined` or `null`. */
 export function isAnyDefined(...values: any[]): boolean {
-    return values.some(v => isDefined(v));
+    return values.some(isDefined);
 }
 /** Return filtered array containing all original elements except `undefined` or `null`. */
 export function filterDefined<T>(elements: (T | undefined | null)[]): T[] {
@@ -99,20 +100,11 @@ export type ElementOfSet<S> = S extends Set<infer T> ? T : never
 
 /** Convert `colorString` (either X11 color name like 'magenta' or hex code like '#ff00ff') to Color.
  * Return `undefined` if `colorString` cannot be converted. */
-export function decodeColor(colorString: string | undefined | null): Color | undefined {
-    if (colorString === undefined || colorString === null) return undefined;
-    let result: Color | undefined;
-    if (HexColor.is(colorString)) {
-        if (colorString.length === 4) {
-            // convert short form to full form (#f0f -> #ff00ff)
-            colorString = `#${colorString[1]}${colorString[1]}${colorString[2]}${colorString[2]}${colorString[3]}${colorString[3]}`;
-        }
-        result = Color.fromHexStyle(colorString);
-        if (result !== undefined && !isNaN(result)) return result;
+export function decodeColor(colorString: string | number | undefined | null): Color | undefined {
+    if (typeof colorString === 'number') {
+        return Color(colorString);
     }
-    result = ColorNames[colorString.toLowerCase() as keyof typeof ColorNames];
-    if (result !== undefined) return result;
-    return undefined;
+    return _decodeColor(colorString);
 }
 
 /** Regular expression matching a hexadecimal color string, e.g. '#FF1100' or '#f10' */
@@ -160,4 +152,25 @@ export function collectMVSReferences<T extends StateObject.Ctor>(type: T[], depe
     }
 
     return ret;
+}
+
+export function getMVSReferenceObject<T extends StateObject.Ctor>(type: T[], dependencies: Record<string, StateObject> | undefined, ref: string): StateObject | undefined {
+    if (!dependencies) return undefined;
+
+    for (const key of Object.keys(dependencies)) {
+        const o = dependencies[key];
+        let okType = false;
+        for (const t of type) {
+            if (t.is(o)) {
+                okType = true;
+                break;
+            }
+        }
+        if (!okType || !o.tags) continue;
+        for (const tag of o.tags) {
+            if (tag.startsWith('mvs-ref:')) {
+                if (tag.substring(8) === ref) return o;
+            }
+        }
+    }
 }

src/extensions/mvs/load-generic.ts

@@ -46,7 +46,7 @@ export function loadTreeVirtual<TTree extends Tree, TContext>(
 ) {
     const updateRoot: UpdateTarget = UpdateTarget.create(plugin, options?.replaceExisting ?? false);
     loadTreeInUpdate(updateRoot, tree, loadingActions, context, options);
-    const stateTree: StateTree = updateRoot.update.getTree();
+    const stateTree: StateTree = updateRoot.update.getTree({ useHashVersion: true });
     const stateSnapshot: State.Snapshot = { tree: StateTree.toJSON(stateTree) };
     const pluginStateSnapshot: PluginState.Snapshot = { id: UUID.create22(), data: stateSnapshot };
     return pluginStateSnapshot;

src/extensions/mvs/load-helpers.ts

@@ -5,16 +5,20 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import { Mat3, Mat4, Vec3 } from '../../mol-math/linear-algebra';
+import { Mat3, Mat4, Quat, Vec3 } from '../../mol-math/linear-algebra';
 import { Volume } from '../../mol-model/volume';
 import { StructureComponentParams } from '../../mol-plugin-state/helpers/structure-component';
-import { StructureFromModel, TransformStructureConformation } from '../../mol-plugin-state/transforms/model';
+import { StructureFromModel, StructureInstances, TransformStructureConformation } from '../../mol-plugin-state/transforms/model';
 import { StructureRepresentation3D, VolumeRepresentation3D } from '../../mol-plugin-state/transforms/representation';
+import { VolumeInstances, VolumeTransform } from '../../mol-plugin-state/transforms/volume';
 import { StateTransformer } from '../../mol-state';
 import { arrayDistinct } from '../../mol-util/array';
+import { Clip } from '../../mol-util/clip';
+import { Color } from '../../mol-util/color';
+import { ColorListEntry } from '../../mol-util/color/color';
 import { canonicalJsonString } from '../../mol-util/json';
 import { stringToWords } from '../../mol-util/string';
-import { MVSAnnotationColorThemeProps, MVSAnnotationColorThemeProvider } from './components/annotation-color-theme';
+import { MVSAnnotationColorThemeProps, MVSAnnotationColorThemeProvider, MVSCategoricalPaletteProps, MVSContinuousPaletteProps, MVSDiscretePaletteProps } from './components/annotation-color-theme';
 import { MVSAnnotationLabelRepresentationProvider } from './components/annotation-label/representation';
 import { MVSAnnotationSpec } from './components/annotation-prop';
 import { MVSAnnotationStructureComponentProps } from './components/annotation-structure-component';
@@ -23,13 +27,16 @@ import { CustomLabelTextProps } from './components/custom-label/visual';
 import { CustomTooltipsProps } from './components/custom-tooltips-prop';
 import { MultilayerColorThemeName, MultilayerColorThemeProps, NoColor } from './components/multilayer-color-theme';
 import { SelectorAll } from './components/selector';
+import { MvsNamedColorDicts, MvsNamedColorLists } from './helpers/colors';
 import { rowToExpression, rowsToExpression } from './helpers/selections';
 import { ElementOfSet, decodeColor, isDefined, stringHash } from './helpers/utils';
 import { MolstarLoadingContext } from './load';
+import { mvsRefTags, UpdateTarget } from './load-generic';
 import { Subtree, getChildren } from './tree/generic/tree-schema';
 import { dfs, formatObject } from './tree/generic/tree-utils';
 import { MolstarKind, MolstarNode, MolstarNodeParams, MolstarSubtree, MolstarTree } from './tree/molstar/molstar-tree';
 import { DefaultColor } from './tree/mvs/mvs-tree';
+import { CategoricalPalette, CategoricalPaletteDefaults, ColorDictNameT, ColorListNameT, ContinuousPalette, ContinuousPaletteDefaults, DiscretePalette, DiscretePaletteDefaults } from './tree/mvs/param-types';
 
 
 export const AnnotationFromUriKinds = new Set(['color_from_uri', 'component_from_uri', 'label_from_uri', 'tooltip_from_uri'] satisfies MolstarKind[]);
@@ -55,6 +62,19 @@ export function transformFromRotationTranslation(rotation: number[] | null | und
     return T;
 }
 
+export function decomposeRotationMatrix(rotation: number[] | null | undefined) {
+    if (rotation && rotation.length !== 9) throw new Error(`'rotation' param for 'transform' node must be array of 9 elements, found ${rotation}`);
+    if (rotation) {
+        const rotMatrix = Mat3.fromArray(Mat3(), rotation, 0);
+        ensureRotationMatrix(rotMatrix, rotMatrix);
+        const quat = Quat.fromMat3(Quat(), rotMatrix);
+        const axis = Vec3();
+        const angle = Quat.getAxisAngle(axis, quat) * 180 / Math.PI;
+        return { axis, angle };
+    }
+    return { axis: Vec3.create(1, 0, 0), angle: 0 };
+}
+
 /** Adjust values in a close-to-rotation matrix `a` to ensure it is a proper rotation matrix
  * (i.e. its columns and rows are orthonormal and determinant equal to 1, within available precission). */
 function ensureRotationMatrix(out: Mat3, a: Mat3) {
@@ -71,15 +91,65 @@ const _tmpVecX = Vec3();
 const _tmpVecY = Vec3();
 const _tmpVecZ = Vec3();
 
-/** Create an array of props for `TransformStructureConformation` transformers from all 'transform' nodes applied to a 'structure' node. */
-export function transformProps(node: MolstarSubtree<'structure'>): StateTransformer.Params<TransformStructureConformation>[] {
-    const result = [] as StateTransformer.Params<TransformStructureConformation>[];
-    const transforms = getChildren(node).filter(c => c.kind === 'transform') as MolstarNode<'transform'>[];
-    for (const transform of transforms) {
-        const { rotation, translation } = transform.params;
-        const matrix = transformFromRotationTranslation(rotation, translation);
-        result.push({ transform: { name: 'matrix', params: { data: matrix, transpose: false } } });
+export function transformAndInstantiateStructure(
+    target: UpdateTarget,
+    node: MolstarSubtree<'structure' | 'component' | 'component_from_source' | 'component_from_uri'>,
+) {
+    return applyTransformAndInstances(target, node, TransformStructureConformation, StructureInstances);
+}
+
+export function transformAndInstantiateVolume(target: UpdateTarget, node: MolstarSubtree<'volume'>) {
+    return applyTransformAndInstances(target, node, VolumeTransform, VolumeInstances);
+}
+
+function applyTransformAndInstances(target: UpdateTarget, node: MolstarSubtree, transform: StateTransformer, instantiate: StateTransformer) {
+    let modified = target;
+    for (const { params, ref } of transformProps(node, 'transform')) {
+        modified = UpdateTarget.apply(modified, transform, params);
+        UpdateTarget.tag(modified, mvsRefTags(ref));
     }
+
+    const instances = transformProps(node, 'instance');
+    if (instances.length > 0) {
+        modified = UpdateTarget.apply(modified, instantiate, { transforms: instances.map(i => i.params) });
+    }
+
+    return modified;
+}
+
+/** Create an array of props for `TransformStructureConformation` transformers from all 'transform' nodes applied to a 'structure' node. */
+function transformProps(node: MolstarSubtree, kind: 'transform' | 'instance') {
+    const result = [] as { params: StateTransformer.Params<TransformStructureConformation>, ref?: string }[];
+    const transforms = getChildren(node).filter(c => c.kind === kind) as MolstarNode<'transform'>[];
+    for (const transform of transforms) {
+        let matrix: Mat4 | undefined = transform.params.matrix as Mat4 | undefined;
+        if (!matrix) {
+            const { rotation, translation, rotation_center } = transform.params;
+            if (rotation_center) {
+                const axisAngle = decomposeRotationMatrix(rotation);
+                result.push({
+                    params: {
+                        transform: {
+                            name: 'components',
+                            params: {
+                                translation: translation ? Vec3.fromArray(Vec3(), translation, 0) : Vec3.create(0, 0, 0),
+                                angle: axisAngle.angle,
+                                axis: axisAngle.axis,
+                                rotationCenter: rotation_center === 'centroid'
+                                    ? { name: 'centroid', params: {} }
+                                    : { name: 'point', params: { point: Vec3.fromArray(Vec3(), rotation_center, 0) } }
+                            }
+                        }
+                    },
+                    ref: transform.ref
+                });
+                continue;
+            }
+            matrix = transformFromRotationTranslation(rotation, translation);
+        }
+        result.push({ params: { transform: { name: 'matrix', params: { data: matrix, transpose: false } } }, ref: transform.ref });
+    }
+
     return result;
 }
 
@@ -90,10 +160,18 @@ export function collectAnnotationReferences(tree: Subtree<MolstarTree>, context:
         let spec: Omit<MVSAnnotationSpec, 'id'> | undefined = undefined;
         if (AnnotationFromUriKinds.has(node.kind as any)) {
             const p = (node as MolstarNode<AnnotationFromUriKind>).params;
-            spec = { source: { name: 'url', params: { url: p.uri, format: p.format } }, schema: p.schema, cifBlock: blockSpec(p.block_header, p.block_index), cifCategory: p.category_name ?? undefined };
+            spec = {
+                source: { name: 'url', params: { url: p.uri, format: p.format } }, schema: p.schema,
+                cifBlock: blockSpec(p.block_header, p.block_index), cifCategory: p.category_name,
+                fieldRemapping: Object.entries(p.field_remapping).map(([key, value]) => ({ standardName: key, actualName: value })),
+            };
         } else if (AnnotationFromSourceKinds.has(node.kind as any)) {
             const p = (node as MolstarNode<AnnotationFromSourceKind>).params;
-            spec = { source: { name: 'source-cif', params: {} }, schema: p.schema, cifBlock: blockSpec(p.block_header, p.block_index), cifCategory: p.category_name ?? undefined };
+            spec = {
+                source: { name: 'source-cif', params: {} }, schema: p.schema,
+                cifBlock: blockSpec(p.block_header, p.block_index), cifCategory: p.category_name,
+                fieldRemapping: Object.entries(p.field_remapping).map(([key, value]) => ({ standardName: key, actualName: value })),
+            };
         }
         if (spec) {
             const key = canonicalJsonString(spec as any);
@@ -282,7 +360,7 @@ export function componentFromXProps(node: MolstarNode<'component_from_uri' | 'co
 }
 
 /** Create props for `StructureRepresentation3D` transformer from a representation node. */
-export function representationProps(node: MolstarSubtree<'representation'>): Partial<StateTransformer.Params<StructureRepresentation3D>> {
+function representationPropsBase(node: MolstarSubtree<'representation'>): Partial<StateTransformer.Params<StructureRepresentation3D>> {
     const alpha = alphaForNode(node);
     const params = node.params;
     switch (params.type) {
@@ -291,10 +369,20 @@ export function representationProps(node: MolstarSubtree<'representation'>): Par
                 type: { name: 'cartoon', params: { alpha, tubularHelices: params.tubular_helices } },
                 sizeTheme: { name: 'uniform', params: { value: params.size_factor } },
             };
+        case 'backbone':
+            return {
+                type: { name: 'backbone', params: { alpha } },
+                sizeTheme: { name: 'uniform', params: { value: params.size_factor } },
+            };
         case 'ball_and_stick':
             return {
                 type: { name: 'ball-and-stick', params: { sizeFactor: (params.size_factor ?? 1) * 0.5, sizeAspectRatio: 0.5, alpha, ignoreHydrogens: params.ignore_hydrogens } },
             };
+        case 'line':
+            return {
+                type: { name: 'line', params: { alpha, ignoreHydrogens: params.ignore_hydrogens } },
+                sizeTheme: { name: 'uniform', params: { value: params.size_factor } },
+            };
         case 'spacefill':
             return {
                 type: { name: 'spacefill', params: { alpha, ignoreHydrogens: params.ignore_hydrogens } },
@@ -304,16 +392,32 @@ export function representationProps(node: MolstarSubtree<'representation'>): Par
             return {
                 type: { name: 'carbohydrate', params: { alpha, sizeFactor: params.size_factor ?? 1 } },
             };
-        case 'surface':
+        case 'surface': {
             return {
-                type: { name: 'molecular-surface', params: { alpha, ignoreHydrogens: params.ignore_hydrogens } },
+                type: {
+                    name: params.surface_type === 'gaussian' ? 'gaussian-surface' : 'molecular-surface',
+                    params: { alpha, ignoreHydrogens: params.ignore_hydrogens }
+                },
                 sizeTheme: { name: 'physical', params: { scale: params.size_factor } },
             };
+        }
         default:
             throw new Error('NotImplementedError');
     }
 }
 
+export function representationProps(node: MolstarSubtree<'representation'>): Partial<StateTransformer.Params<StructureRepresentation3D>> {
+    const base = representationPropsBase(node);
+    const clip = clippingForNode(node);
+    if (clip) {
+        base.type!.params = { ...base.type?.params, clip };
+    }
+    if (node.custom?.molstar_representation_params) {
+        base.type!.params = { ...base.type!.params, ...node.custom.molstar_representation_params };
+    }
+    return base;
+}
+
 /** Create value for `type.params.alpha` prop for `StructureRepresentation3D` transformer from a representation node based on 'opacity' nodes in its subtree. */
 export function alphaForNode(node: MolstarSubtree<'representation' | 'volume_representation'>): number {
     const children = getChildren(node).filter(c => c.kind === 'opacity');
@@ -324,6 +428,67 @@ export function alphaForNode(node: MolstarSubtree<'representation' | 'volume_rep
     }
 }
 
+function getCommonClipParams(node: MolstarNode<'clip'>): Pick<Clip.Props['objects'][number], 'invert' | 'transform'> {
+    return {
+        invert: !!node.params.invert,
+        transform: node.params.check_transform ? Mat4.fromArray(Mat4(), node.params.check_transform, 0) : Mat4.identity(),
+    };
+}
+
+function getClipObject(node: MolstarNode<'clip'>): Clip.Props['objects'][number] | undefined {
+    switch (node.params.type) {
+        case 'sphere':
+            return {
+                type: 'sphere',
+                position: Vec3.ofArray(node.params.center),
+                scale: typeof node.params.radius === 'number'
+                    ? Vec3.create(2 * node.params.radius, 2 * node.params.radius, 2 * node.params.radius)
+                    : Vec3.create(2, 2, 2),
+                rotation: { axis: Vec3.create(1, 0, 0), angle: 0 },
+                ...getCommonClipParams(node),
+            };
+        case 'plane': {
+            const up = Vec3.create(0, 1, 0);
+            const n = Vec3.normalize(Vec3(), Vec3.ofArray(node.params.normal));
+            const axis = Vec3.cross(Vec3(), up, n);
+            const isSingular = Vec3.magnitude(axis) < 1e-6;
+            return {
+                type: 'plane',
+                position: Vec3.ofArray(node.params.point),
+                scale: Vec3.create(1, 1, 1),
+                rotation: {
+                    axis: isSingular ? Vec3.unitX : axis,
+                    angle: isSingular ? 0 : Vec3.angle(up, n) * 180 / Math.PI,
+                },
+                ...getCommonClipParams(node),
+            };
+        }
+        case 'box':
+            const q = Quat.fromMat3(Quat(), Mat3.fromArray(Mat3(), node.params.rotation, 0));
+            const axis = Vec3();
+            const angle = Quat.getAxisAngle(axis, q) * 180 / Math.PI;
+            return {
+                type: 'cube',
+                position: Vec3.ofArray(node.params.center),
+                scale: Vec3.ofArray(node.params.size),
+                rotation: { axis, angle },
+                ...getCommonClipParams(node),
+            };
+        default:
+            console.warn(`Mol* MVS: Unsupported clip type "${(node as MolstarNode<'clip'>).params.type}" in node ${node.ref}.`);
+    }
+}
+
+export function clippingForNode(node: MolstarSubtree<'representation' | 'volume_representation'>): Clip.Props | undefined {
+    const children = getChildren(node).filter(c => c.kind === 'clip');
+    if (!children.length) return;
+
+    const variant = children[0].params.variant === 'object' ? 'instance' : 'pixel';
+    const objects: Clip.Props['objects'] = children.map(getClipObject).filter(o => !!o);
+
+    return { variant, objects } satisfies Clip.Props;
+}
+
 function hasMolStarUseDefaultColoring(node: MolstarNode): boolean {
     if (!node.custom) return false;
     return 'molstar_use_default_coloring' in node.custom || 'molstar_color_theme_name' in node.custom;
@@ -361,31 +526,27 @@ export function colorThemeForNode(node: MolstarSubtree<'color' | 'color_from_uri
             };
         }
     }
-    let annotationId: string | undefined = undefined;
-    let fieldName: string | undefined = undefined;
-    let color: string | undefined = undefined;
-    switch (node?.kind) {
-        case 'color_from_uri':
-        case 'color_from_source':
-            annotationId = context.annotationMap.get(node);
-            fieldName = node.params.field_name;
-            break;
-        case 'color':
-            color = node.params.color;
-            break;
-    }
-    if (annotationId) {
-        return {
-            name: MVSAnnotationColorThemeProvider.name,
-            params: { annotationId, fieldName, background: NoColor } satisfies Partial<MVSAnnotationColorThemeProps>,
-        };
-    } else {
+    if (node?.kind === 'color') {
         return {
             name: 'uniform',
-            params: { value: decodeColor(color) },
+            params: { value: decodeColor(node.params.color) },
+        };
+    }
+    if (node?.kind === 'color_from_uri' || node?.kind === 'color_from_source') {
+        const annotationId = context.annotationMap.get(node);
+        if (annotationId === undefined) return {
+            name: 'uniform',
+            params: {},
+        };
+
+        const fieldName = node.params.field_name;
+        return {
+            name: MVSAnnotationColorThemeProvider.name,
+            params: { annotationId, fieldName, background: NoColor, palette: palettePropsFromMVSPalette(node.params.palette) } satisfies Partial<MVSAnnotationColorThemeProps>,
         };
     }
 }
+
 function appliesColorToWholeRepr(node: MolstarNode<'color' | 'color_from_uri' | 'color_from_source'>): boolean {
     if (node.kind === 'color') {
         return !isDefined(node.params.selector) || node.params.selector === 'all';
@@ -394,6 +555,153 @@ function appliesColorToWholeRepr(node: MolstarNode<'color' | 'color_from_uri' |
     }
 }
 
+const FALLBACK_COLOR = decodeColor(DefaultColor)!;
+
+export function palettePropsFromMVSPalette(palette: MolstarNode<'color_from_uri' | 'color_from_source'>['params']['palette']): MVSAnnotationColorThemeProps['palette'] {
+    if (!palette) {
+        return { name: 'direct', params: {} };
+    }
+    if (palette.kind === 'categorical') {
+        const fullParams: Required<CategoricalPalette> = objMerge(CategoricalPaletteDefaults, palette);
+        return {
+            name: 'categorical',
+            params: {
+                colors: categoricalPalettePropsFromMVSColors(fullParams.colors),
+                repeatColorList: fullParams.repeat_color_list,
+                sort: fullParams.sort,
+                sortDirection: fullParams.sort_direction,
+                caseInsensitive: fullParams.case_insensitive,
+                setMissingColor: !!fullParams.missing_color,
+                missingColor: decodeColor(fullParams.missing_color) ?? FALLBACK_COLOR,
+            } satisfies MVSCategoricalPaletteProps,
+        };
+    }
+    if (palette.kind === 'discrete') {
+        const fullParams: Required<DiscretePalette> = objMerge(DiscretePaletteDefaults, palette);
+        return {
+            name: 'discrete',
+            params: {
+                colors: discretePalettePropsFromMVSColors(fullParams.colors, fullParams.reverse),
+                mode: fullParams.mode,
+                xMin: fullParams.value_domain[0],
+                xMax: fullParams.value_domain[1],
+            } satisfies MVSDiscretePaletteProps,
+        };
+    }
+    if (palette.kind === 'continuous') {
+        const fullParams: Required<ContinuousPalette> = objMerge(ContinuousPaletteDefaults, palette);
+        const colors = continuousPalettePropsFromMVSColors(fullParams.colors, fullParams.reverse);
+        return {
+            name: 'continuous',
+            params: {
+                colors: colors,
+                mode: fullParams.mode,
+                xMin: fullParams.value_domain[0],
+                xMax: fullParams.value_domain[1],
+                setUnderflowColor: !!fullParams.underflow_color,
+                underflowColor: (fullParams.underflow_color === 'auto' ? minColor(colors.colors) : decodeColor(fullParams.underflow_color)) ?? FALLBACK_COLOR,
+                setOverflowColor: !!fullParams.overflow_color,
+                overflowColor: (fullParams.overflow_color === 'auto' ? maxColor(colors.colors) : decodeColor(fullParams.overflow_color)) ?? FALLBACK_COLOR,
+            } satisfies MVSContinuousPaletteProps,
+        };
+    }
+    throw new Error(`NotImplementedError: palettePropsFromMVSPalette is not implemented for palette kind "${(palette as any).kind}"`);
+}
+
+/** Merge properties of two object into a new object. Property values from `second` override those from `first`, but `undefined` is treated as if property missing while `null` as a regular value. */
+function objMerge<T extends object, U extends object>(first: T, second: U): T & U {
+    const out: Partial<T & U> = { ...first };
+    for (const key in second) {
+        const value = second[key];
+        if (value !== undefined) out[key] = value as any;
+    }
+    return out as T & U;
+}
+
+function categoricalPalettePropsFromMVSColors(colors: Required<CategoricalPalette>['colors']): MVSCategoricalPaletteProps['colors'] {
+    if (typeof colors === 'string') {
+        if (colors in MvsNamedColorLists) {
+            const colorList = MvsNamedColorLists[colors as ColorListNameT];
+            return { name: 'list', params: { kind: 'set', colors: colorList.list } };
+        }
+        if (colors in MvsNamedColorDicts) {
+            const colorDict = MvsNamedColorDicts[colors as ColorDictNameT];
+            return { name: 'dictionary', params: Object.entries(colorDict).map(([value, color]) => ({ value, color })) };
+        }
+        console.warn(`Could not find named color palette "${colors}"`);
+    }
+    if (Array.isArray(colors)) {
+        return { name: 'list', params: { kind: 'set', colors: colors.map(c => decodeColor(c) ?? FALLBACK_COLOR) } };
+    }
+    if (typeof colors === 'object') {
+        return { name: 'dictionary', params: Object.entries(colors).map(([value, color]) => ({ value, color: decodeColor(color) ?? FALLBACK_COLOR })) };
+    }
+    return { name: 'list', params: { kind: 'set', colors: [] } };
+}
+
+function discretePalettePropsFromMVSColors(colors: Required<DiscretePalette>['colors'], reverse: boolean): MVSDiscretePaletteProps['colors'] {
+    if (typeof colors === 'string') {
+        if (colors in MvsNamedColorLists) {
+            const colorList = MvsNamedColorLists[colors];
+            const list = reverse ? colorList.list.slice().reverse() : colorList.list;
+            const sectionLength = 1 / list.length;
+            return list.map((e, i) => ({ color: Color.fromColorListEntry(e), fromValue: i * sectionLength, toValue: (i + 1) * sectionLength }));
+        }
+        console.warn(`Could not find named color palette "${colors}"`);
+    }
+    if (Array.isArray(colors) && colors.every(t => typeof t === 'string')) {
+        const list = reverse ? colors.slice().reverse() : colors;
+        const sectionLength = 1 / colors.length;
+        return list.map((c, i) => ({ color: decodeColor(c) ?? NoColor, fromValue: i * sectionLength, toValue: (i + 1) * sectionLength }));
+    }
+    if (Array.isArray(colors) && colors.every(t => Array.isArray(t) && t.length === 2)) {
+        return colors.map((t, i) => ({ color: decodeColor(t[0]) ?? NoColor, fromValue: t[1], toValue: colors[i + 1]?.[1] ?? Infinity }));
+    }
+    if (Array.isArray(colors) && colors.every(t => Array.isArray(t) && t.length === 3)) {
+        return colors.map(t => ({ color: decodeColor(t[0]) ?? NoColor, fromValue: t[1] ?? -Infinity, toValue: t[2] ?? Infinity }));
+    }
+    return [];
+}
+
+function continuousPalettePropsFromMVSColors(colors: Required<ContinuousPalette>['colors'], reverse: boolean): MVSContinuousPaletteProps['colors'] {
+    if (typeof colors === 'string') {
+        // Named color list
+        if (colors in MvsNamedColorLists) {
+            const colorList = MvsNamedColorLists[colors];
+            const list = reverse ? colorList.list.slice().reverse() : colorList.list;
+            const n = list.length - 1;
+            return { kind: 'interpolate', colors: list.map((col, i) => [Color.fromColorListEntry(col), i / n]) };
+        }
+        console.warn(`Could not find named color palette "${colors}"`);
+    }
+    if (Array.isArray(colors)) {
+        if (colors.every(t => Array.isArray(t))) {
+            // Color list with checkpoints
+            // Not applying `reverse` here, as it would have no effect
+            return { kind: 'interpolate', colors: colors.map(t => [decodeColor(t[0]) ?? FALLBACK_COLOR, t[1]]) };
+        } else {
+            // Color list without checkpoints
+            const list = reverse ? colors.slice().reverse() : colors;
+            const n = list.length - 1;
+            return { kind: 'interpolate', colors: list.map((col, i) => [decodeColor(col) ?? FALLBACK_COLOR, i / n]) };
+        }
+    }
+    return { kind: 'interpolate', colors: [] };
+}
+
+/** Return the color with the lowest checkpoint, or the first color if checkpoints not available. */
+function minColor(colors: ColorListEntry[]): Color | undefined {
+    if (colors.length === 0) return undefined;
+    if (colors.every(t => Array.isArray(t))) return Color.fromColorListEntry(colors.reduce((a, b) => a[1] < b[1] ? a : b));
+    return Color.fromColorListEntry(colors[0]);
+}
+/** Return the color with the highest checkpoint, or the last color if checkpoints not available. */
+function maxColor(colors: ColorListEntry[]): Color | undefined {
+    if (colors.length === 0) return undefined;
+    if (colors.every(t => Array.isArray(t))) return Color.fromColorListEntry(colors.reduce((a, b) => a[1] > b[1] ? a : b));
+    return Color.fromColorListEntry(colors[colors.length - 1]);
+}
+
 /** Create a mapping of nearest representation nodes for each node in the tree
  * (to transfer coloring to label nodes smartly).
  * Only considers nodes within the same 'structure' subtree. */
@@ -420,15 +728,26 @@ export function makeNearestReprMap(root: MolstarTree) {
 /** Create props for `VolumeRepresentation3D` transformer from a representation node. */
 export function volumeRepresentationProps(node: MolstarSubtree<'volume_representation'>): Partial<StateTransformer.Params<VolumeRepresentation3D>> {
     const alpha = alphaForNode(node);
+    const clip = clippingForNode(node);
     const params = node.params;
+
+    const isoValue = typeof params.absolute_isovalue === 'number' ? Volume.IsoValue.absolute(params.absolute_isovalue) : Volume.IsoValue.relative(params.relative_isovalue ?? 0);
     switch (params.type) {
         case 'isosurface':
-            const isoValue = typeof params.absolute_isovalue === 'number' ? Volume.IsoValue.absolute(params.absolute_isovalue) : Volume.IsoValue.relative(params.relative_isovalue ?? 0);
             const visuals: ('wireframe' | 'solid')[] = [];
             if (params.show_wireframe) visuals.push('wireframe');
             if (params.show_faces) visuals.push('solid');
             return {
-                type: { name: 'isosurface', params: { alpha, isoValue, visuals } },
+                type: { name: 'isosurface', params: { alpha, isoValue, visuals, clip } },
+            };
+        case 'grid_slice':
+            const isRelative = params.relative_index !== undefined;
+            const dimension = {
+                name: isRelative ? `relative${params.dimension.toUpperCase()}` : params.dimension,
+                params: params.relative_index ?? params.relative_index
+            };
+            return {
+                type: { name: 'slice', params: { alpha, dimension, isoValue, clip } },
             };
         default:
             throw new Error('NotImplementedError');
@@ -448,4 +767,4 @@ export function volumeColorThemeForNode(node: MolstarSubtree<'volume_representat
     } if (children.length === 1) {
         return colorThemeForNode(children[0], context);
     }
-}
+}

src/extensions/mvs/load.ts

@@ -8,27 +8,32 @@
 
 import { PluginStateSnapshotManager } from '../../mol-plugin-state/manager/snapshots';
 import { PluginStateObject } from '../../mol-plugin-state/objects';
-import { Download, ParseCcp4, ParseCif } from '../../mol-plugin-state/transforms/data';
-import { CustomModelProperties, CustomStructureProperties, ModelFromTrajectory, StructureComponent, StructureFromModel, TrajectoryFromMmCif, TrajectoryFromPDB, TransformStructureConformation } from '../../mol-plugin-state/transforms/model';
-import { ShapeRepresentation3D, StructureRepresentation3D, VolumeRepresentation3D } from '../../mol-plugin-state/transforms/representation';
+import { Download, ParseCif, ParseCcp4 } from '../../mol-plugin-state/transforms/data';
+import { CoordinatesFromLammpstraj, CoordinatesFromXtc, CustomModelProperties, CustomStructureProperties, ModelFromTrajectory, StructureComponent, StructureFromModel, TrajectoryFromGRO, TrajectoryFromLammpsTrajData, TrajectoryFromMmCif, TrajectoryFromMOL, TrajectoryFromMOL2, TrajectoryFromPDB, TrajectoryFromSDF, TrajectoryFromXYZ } from '../../mol-plugin-state/transforms/model';
+import { StructureRepresentation3D, VolumeRepresentation3D } from '../../mol-plugin-state/transforms/representation';
 import { VolumeFromCcp4, VolumeFromDensityServerCif } from '../../mol-plugin-state/transforms/volume';
 import { PluginCommands } from '../../mol-plugin/commands';
 import { PluginContext } from '../../mol-plugin/context';
-import { StateObjectSelector } from '../../mol-state';
+import { PluginState } from '../../mol-plugin/state';
+import { StateObjectSelector, StateTree } from '../../mol-state';
+import { RuntimeContext, Task } from '../../mol-task';
 import { MolViewSpec } from './behavior';
-import { createPluginStateSnapshotCamera, modifyCanvasProps } from './camera';
+import { createPluginStateSnapshotCamera, modifyCanvasProps, resetCanvasProps } from './camera';
 import { MVSAnnotationsProvider } from './components/annotation-prop';
 import { MVSAnnotationStructureComponent } from './components/annotation-structure-component';
 import { MVSAnnotationTooltipsProvider } from './components/annotation-tooltips-prop';
 import { CustomLabelProps, CustomLabelRepresentationProvider } from './components/custom-label/representation';
 import { CustomTooltipsProvider } from './components/custom-tooltips-prop';
 import { IsMVSModelProps, IsMVSModelProvider } from './components/is-mvs-model-prop';
-import { getPrimitiveStructureRefs, MVSBuildPrimitiveShape, MVSDownloadPrimitiveData, MVSInlinePrimitiveData } from './components/primitives';
+import { getPrimitiveStructureRefs, MVSBuildPrimitiveShape, MVSDownloadPrimitiveData, MVSInlinePrimitiveData, MVSShapeRepresentation3D } from './components/primitives';
+import { MVSTrajectoryWithCoordinates } from './components/trajectory';
+import { generateStateTransition } from './helpers/animation';
 import { IsHiddenCustomStateExtension } from './load-extensions/is-hidden-custom-state';
 import { NonCovalentInteractionsExtension } from './load-extensions/non-covalent-interactions';
 import { LoadingActions, LoadingExtension, loadTreeVirtual, UpdateTarget } from './load-generic';
-import { AnnotationFromSourceKind, AnnotationFromUriKind, collectAnnotationReferences, collectAnnotationTooltips, collectInlineLabels, collectInlineTooltips, colorThemeForNode, componentFromXProps, componentPropsFromSelector, isPhantomComponent, labelFromXProps, makeNearestReprMap, prettyNameFromSelector, representationProps, structureProps, transformProps, volumeColorThemeForNode, volumeRepresentationProps } from './load-helpers';
-import { MVSData, MVSData_States, SnapshotMetadata } from './mvs-data';
+import { AnnotationFromSourceKind, AnnotationFromUriKind, collectAnnotationReferences, collectAnnotationTooltips, collectInlineLabels, collectInlineTooltips, colorThemeForNode, componentFromXProps, componentPropsFromSelector, isPhantomComponent, labelFromXProps, makeNearestReprMap, prettyNameFromSelector, representationProps, structureProps, transformAndInstantiateStructure, transformAndInstantiateVolume, volumeColorThemeForNode, volumeRepresentationProps } from './load-helpers';
+import { MVSData, MVSData_States, Snapshot, SnapshotMetadata } from './mvs-data';
+import { MVSAnimationNode } from './tree/animation/animation-tree';
 import { validateTree } from './tree/generic/tree-schema';
 import { convertMvsToMolstar, mvsSanityCheck } from './tree/molstar/conversion';
 import { MolstarNode, MolstarNodeParams, MolstarSubtree, MolstarTree, MolstarTreeSchema } from './tree/molstar/molstar-tree';
@@ -49,12 +54,24 @@ export interface MVSLoadOptions {
     doNotReportErrors?: boolean
 }
 
+export function loadMVS(plugin: PluginContext, data: MVSData, options: MVSLoadOptions = {}) {
+    const task = Task.create('Load MVS', ctx => _loadMVS(ctx, plugin, data, options));
+    return plugin.runTask(task);
+}
+
 /** Load a MolViewSpec (MVS) state(s) into the Mol* plugin as plugin state snapshots. */
-export async function loadMVS(plugin: PluginContext, data: MVSData, options: MVSLoadOptions = {}) {
+async function _loadMVS(ctx: RuntimeContext, plugin: PluginContext, data: MVSData, options: MVSLoadOptions = {}) {
     plugin.errorContext.clear('mvs');
     try {
         const mvsExtensionLoaded = plugin.state.hasBehavior(MolViewSpec);
         if (!mvsExtensionLoaded) throw new Error('MolViewSpec extension is not loaded.');
+
+        // Stop any currently running audio
+        plugin.managers.markdownExtensions.audio.dispose();
+
+        // Reset canvas props to default so that modifyCanvasProps works as expected
+        resetCanvasProps(plugin);
+
         // console.log(`MVS tree:\n${MVSData.toPrettyString(data)}`)
         const multiData: MVSData_States = data.kind === 'multiple' ? data : MVSData.stateToStates(data);
         const entries: PluginStateSnapshotManager.Entry[] = [];
@@ -65,8 +82,19 @@ export async function loadMVS(plugin: PluginContext, data: MVSData, options: MVS
             if (options.sanityChecks) mvsSanityCheck(snapshot.root);
             const molstarTree = convertMvsToMolstar(snapshot.root, options.sourceUrl);
             validateTree(MolstarTreeSchema, molstarTree, 'Converted Molstar');
-            const entry = molstarTreeToEntry(plugin, molstarTree, { ...snapshot.metadata, previousTransitionDurationMs: previousSnapshot.metadata.transition_duration_ms }, options);
+            const entry = molstarTreeToEntry(
+                plugin,
+                molstarTree,
+                snapshot.animation,
+                { ...snapshot.metadata, previousTransitionDurationMs: previousSnapshot.metadata.transition_duration_ms },
+                options
+            );
+            await assignStateTransition(ctx, plugin, entry, snapshot, options, i, multiData.snapshots.length);
             entries.push(entry);
+
+            if (ctx.shouldUpdate) {
+                await ctx.update({ message: 'Loading MVS...', current: i, max: multiData.snapshots.length });
+            }
         }
         if (!options.appendSnapshots) {
             plugin.managers.snapshot.clear();
@@ -74,6 +102,7 @@ export async function loadMVS(plugin: PluginContext, data: MVSData, options: MVS
         for (const entry of entries) {
             plugin.managers.snapshot.add(entry);
         }
+
         if (entries.length > 0) {
             await PluginCommands.State.Snapshots.Apply(plugin, { id: entries[0].snapshot.id });
         }
@@ -95,18 +124,65 @@ export async function loadMVS(plugin: PluginContext, data: MVSData, options: MVS
     }
 }
 
+async function assignStateTransition(ctx: RuntimeContext, plugin: PluginContext, parentEntry: PluginStateSnapshotManager.Entry, parent: Snapshot, options: MVSLoadOptions, snapshotIndex: number, snapshotCount: number) {
+    const transitions = await generateStateTransition(ctx, parent, snapshotIndex, snapshotCount);
+    if (!transitions?.frames.length) return;
 
-function molstarTreeToEntry(plugin: PluginContext, tree: MolstarTree, metadata: SnapshotMetadata & { previousTransitionDurationMs?: number }, options?: { keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+    const animation: PluginState.StateTransition = {
+        autoplay: !!transitions.tree.params?.autoplay,
+        loop: !!transitions.tree.params?.loop,
+        frames: [],
+    };
+
+    for (let i = 0; i < transitions.frames.length; i++) {
+        const frame = transitions.frames[i];
+        const molstarTree = convertMvsToMolstar(frame[0], options.sourceUrl);
+        const entry = molstarTreeToEntry(
+            plugin,
+            molstarTree,
+            parent.animation,
+            { ...parent.metadata, previousTransitionDurationMs: transitions.frametimeMs },
+            options
+        );
+
+        StateTree.reuseTransformParams(entry.snapshot.data!.tree, parentEntry.snapshot.data!.tree);
+
+        animation.frames.push({
+            durationInMs: frame[1],
+            data: entry.snapshot.data!,
+            camera: transitions.tree.params?.include_camera ? entry.snapshot.camera : undefined,
+            canvas3d: transitions.tree.params?.include_canvas ? entry.snapshot.canvas3d : undefined,
+        });
+
+        if (ctx.shouldUpdate) {
+            await ctx.update({ message: `Loading animation for snapshot ${snapshotIndex + 1}/${snapshotCount}...`, current: i + 1, max: transitions.frames.length });
+        }
+    }
+
+    parentEntry.snapshot.transition = animation;
+}
+
+function molstarTreeToEntry(
+    plugin: PluginContext,
+    tree: MolstarTree,
+    animation: MVSAnimationNode<'animation'> | undefined,
+    metadata: SnapshotMetadata & { previousTransitionDurationMs?: number },
+    options: { keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }
+) {
     const context = MolstarLoadingContext.create();
     const snapshot = loadTreeVirtual(plugin, tree, MolstarLoadingActions, context, { replaceExisting: true, extensions: options?.extensions ?? BuiltinLoadingExtensions });
     snapshot.canvas3d = {
-        props: plugin.canvas3d ? modifyCanvasProps(plugin.canvas3d.props, context.canvas) : undefined,
+        props: plugin.canvas3d ? modifyCanvasProps(plugin.canvas3d.props, context.canvas, animation) : undefined,
     };
     if (!options?.keepCamera) {
         snapshot.camera = createPluginStateSnapshotCamera(plugin, context, metadata);
     }
     snapshot.durationInMs = metadata.linger_duration_ms + (metadata.previousTransitionDurationMs ?? 0);
 
+    if (tree.custom?.molstar_on_load_markdown_commands) {
+        snapshot.onLoadMarkdownCommands = tree.custom.molstar_on_load_markdown_commands;
+    }
+
     const entryParams: PluginStateSnapshotManager.EntryParams = {
         key: metadata.key,
         name: metadata.title,
@@ -127,7 +203,7 @@ export interface MolstarLoadingContext {
         cameraParams?: MolstarNodeParams<'camera'>,
         focuses: { target: StateObjectSelector, params: MolstarNodeParams<'focus'> }[],
     },
-    canvas?: MolstarNodeParams<'canvas'>,
+    canvas?: MolstarNode<'canvas'>,
 }
 export const MolstarLoadingContext = {
     create(): MolstarLoadingContext {
@@ -153,31 +229,72 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
     },
     parse(updateParent: UpdateTarget, node: MolstarNode<'parse'>): UpdateTarget | undefined {
         const format = node.params.format;
-        if (format === 'cif') {
-            return UpdateTarget.apply(updateParent, ParseCif, {});
-        } else if (format === 'pdb') {
-            return updateParent;
-        } else if (format === 'map') {
-            return UpdateTarget.apply(updateParent, ParseCcp4, {});
-        } else {
-            console.error(`Unknown format in "parse" node: "${format}"`);
-            return undefined;
+        switch (format) {
+            case 'cif':
+                return UpdateTarget.apply(updateParent, ParseCif, {});
+            case 'pdb':
+            case 'pdbqt':
+            case 'gro':
+            case 'xyz':
+            case 'mol':
+            case 'sdf':
+            case 'mol2':
+            case 'xtc':
+            case 'lammpstrj':
+                return updateParent;
+            case 'map':
+                return UpdateTarget.apply(updateParent, ParseCcp4, {});
+            default:
+                console.error(`Unknown format in "parse" node: "${format}"`);
+                return undefined;
+        }
+    },
+    coordinates(updateParent: UpdateTarget, node: MolstarNode<'coordinates'>): UpdateTarget | undefined {
+        const format = node.params.format;
+        switch (format) {
+            case 'xtc':
+                return UpdateTarget.apply(updateParent, CoordinatesFromXtc);
+            case 'lammpstrj':
+                return UpdateTarget.apply(updateParent, CoordinatesFromLammpstraj);
+            default:
+                console.error(`Unknown format in "coordinates" node: "${format}"`);
+                return undefined;
         }
     },
     trajectory(updateParent: UpdateTarget, node: MolstarNode<'trajectory'>): UpdateTarget | undefined {
         const format = node.params.format;
-        if (format === 'cif') {
-            return UpdateTarget.apply(updateParent, TrajectoryFromMmCif, {
-                blockHeader: node.params.block_header ?? '', // Must set to '' because just undefined would get overwritten by createDefaults
-                blockIndex: node.params.block_index ?? undefined,
-            });
-        } else if (format === 'pdb') {
-            return UpdateTarget.apply(updateParent, TrajectoryFromPDB, {});
-        } else {
-            console.error(`Unknown format in "trajectory" node: "${format}"`);
-            return undefined;
+        switch (format) {
+            case 'cif':
+                return UpdateTarget.apply(updateParent, TrajectoryFromMmCif, {
+                    blockHeader: node.params.block_header ?? '', // Must set to '' because just undefined would get overwritten by createDefaults
+                    blockIndex: node.params.block_index ?? undefined,
+                });
+            case 'pdb':
+            case 'pdbqt':
+                return UpdateTarget.apply(updateParent, TrajectoryFromPDB, { isPdbqt: format === 'pdbqt' });
+            case 'gro':
+                return UpdateTarget.apply(updateParent, TrajectoryFromGRO);
+            case 'xyz':
+                return UpdateTarget.apply(updateParent, TrajectoryFromXYZ);
+            case 'mol':
+                return UpdateTarget.apply(updateParent, TrajectoryFromMOL);
+            case 'sdf':
+                return UpdateTarget.apply(updateParent, TrajectoryFromSDF);
+            case 'mol2':
+                return UpdateTarget.apply(updateParent, TrajectoryFromMOL2);
+            case 'lammpstrj':
+                return UpdateTarget.apply(updateParent, TrajectoryFromLammpsTrajData);
+            default:
+                console.error(`Unknown format in "trajectory" node: "${format}"`);
+                return undefined;
         }
     },
+    trajectory_with_coordinates(updateParent: UpdateTarget, node: MolstarNode<'trajectory_with_coordinates'>): UpdateTarget | undefined {
+        const result = UpdateTarget.apply(updateParent, MVSTrajectoryWithCoordinates, {
+            coordinatesRef: node.params.coordinates_ref,
+        });
+        return UpdateTarget.setMvsDependencies(result, [node.params.coordinates_ref]);
+    },
     model(updateParent: UpdateTarget, node: MolstarSubtree<'model'>, context: MolstarLoadingContext): UpdateTarget {
         const annotations = collectAnnotationReferences(node, context);
         const model = UpdateTarget.apply(updateParent, ModelFromTrajectory, {
@@ -198,10 +315,7 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
     structure(updateParent: UpdateTarget, node: MolstarSubtree<'structure'>, context: MolstarLoadingContext): UpdateTarget {
         const props = structureProps(node);
         const struct = UpdateTarget.apply(updateParent, StructureFromModel, props);
-        let transformed = struct;
-        for (const t of transformProps(node)) {
-            transformed = UpdateTarget.apply(transformed, TransformStructureConformation, t); // applying to the result of previous transform, to get the correct transform order
-        }
+        const transformed = transformAndInstantiateStructure(struct, node);
         const annotationTooltips = collectAnnotationTooltips(node, context);
         const inlineTooltips = collectInlineTooltips(node, context);
         if (annotationTooltips.length + inlineTooltips.length > 0) {
@@ -227,7 +341,7 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
                 colorTheme: colorThemeForNode(nearestReprNode, context),
             });
         }
-        return struct;
+        return transformed;
     },
     tooltip: undefined, // No action needed, already loaded in `structure`
     tooltip_from_uri: undefined, // No action needed, already loaded in `structure`
@@ -237,21 +351,21 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
             return updateParent;
         }
         const selector = node.params.selector;
-        return UpdateTarget.apply(updateParent, StructureComponent, {
+        return transformAndInstantiateStructure(UpdateTarget.apply(updateParent, StructureComponent, {
             type: componentPropsFromSelector(selector),
             label: prettyNameFromSelector(selector),
             nullIfEmpty: false,
-        });
+        }), node);
     },
     component_from_uri(updateParent: UpdateTarget, node: MolstarSubtree<'component_from_uri'>, context: MolstarLoadingContext): UpdateTarget | undefined {
         if (isPhantomComponent(node)) return undefined;
         const props = componentFromXProps(node, context);
-        return UpdateTarget.apply(updateParent, MVSAnnotationStructureComponent, props);
+        return transformAndInstantiateStructure(UpdateTarget.apply(updateParent, MVSAnnotationStructureComponent, props), node);
     },
     component_from_source(updateParent: UpdateTarget, node: MolstarSubtree<'component_from_source'>, context: MolstarLoadingContext): UpdateTarget | undefined {
         if (isPhantomComponent(node)) return undefined;
         const props = componentFromXProps(node, context);
-        return UpdateTarget.apply(updateParent, MVSAnnotationStructureComponent, props);
+        return transformAndInstantiateStructure(UpdateTarget.apply(updateParent, MVSAnnotationStructureComponent, props), node);
     },
     representation(updateParent: UpdateTarget, node: MolstarNode<'representation'>, context: MolstarLoadingContext): UpdateTarget {
         return UpdateTarget.apply(updateParent, StructureRepresentation3D, {
@@ -260,14 +374,16 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
         });
     },
     volume(updateParent: UpdateTarget, node: MolstarNode<'volume'>): UpdateTarget | undefined {
+        let volume: UpdateTarget;
         if (updateParent.transformer?.definition.to.includes(PluginStateObject.Format.Ccp4)) {
-            return UpdateTarget.apply(updateParent, VolumeFromCcp4, {});
+            volume = UpdateTarget.apply(updateParent, VolumeFromCcp4, {});
         } else if (updateParent.transformer?.definition.to.includes(PluginStateObject.Format.Cif)) {
-            return UpdateTarget.apply(updateParent, VolumeFromDensityServerCif, { blockHeader: node.params.channel_id || undefined });
+            volume = UpdateTarget.apply(updateParent, VolumeFromDensityServerCif, { blockHeader: node.params.channel_id || undefined });
         } else {
             console.error(`Unsupported volume format`);
             return undefined;
         }
+        return transformAndInstantiateVolume(volume, node);
     },
     volume_representation(updateParent: UpdateTarget, node: MolstarNode<'volume_representation'>, context: MolstarLoadingContext): UpdateTarget {
         return UpdateTarget.apply(updateParent, VolumeRepresentation3D, {
@@ -296,12 +412,12 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
         return updateParent;
     },
     canvas(updateParent: UpdateTarget, node: MolstarNode<'canvas'>, context: MolstarLoadingContext): UpdateTarget {
-        context.canvas = node.params;
+        context.canvas = node;
         return updateParent;
     },
     primitives(updateParent: UpdateTarget, tree: MolstarSubtree<'primitives'>, context: MolstarLoadingContext): UpdateTarget {
         const refs = getPrimitiveStructureRefs(tree);
-        const data = UpdateTarget.apply(updateParent, MVSInlinePrimitiveData, { node: tree });
+        const data = UpdateTarget.apply(updateParent, MVSInlinePrimitiveData, { node: tree as any });
         return applyPrimitiveVisuals(data, refs);
     },
     primitives_from_uri(updateParent: UpdateTarget, tree: MolstarNode<'primitives_from_uri'>, context: MolstarLoadingContext): UpdateTarget {
@@ -312,11 +428,11 @@ const MolstarLoadingActions: LoadingActions<MolstarTree, MolstarLoadingContext>
 
 function applyPrimitiveVisuals(data: UpdateTarget, refs: Set<string>) {
     const mesh = UpdateTarget.setMvsDependencies(UpdateTarget.apply(data, MVSBuildPrimitiveShape, { kind: 'mesh' }, { state: { isGhost: true } }), refs);
-    UpdateTarget.apply(mesh, ShapeRepresentation3D);
+    UpdateTarget.apply(mesh, MVSShapeRepresentation3D);
     const labels = UpdateTarget.setMvsDependencies(UpdateTarget.apply(data, MVSBuildPrimitiveShape, { kind: 'labels' }, { state: { isGhost: true } }), refs);
-    UpdateTarget.apply(labels, ShapeRepresentation3D);
+    UpdateTarget.apply(labels, MVSShapeRepresentation3D);
     const lines = UpdateTarget.setMvsDependencies(UpdateTarget.apply(data, MVSBuildPrimitiveShape, { kind: 'lines' }, { state: { isGhost: true } }), refs);
-    UpdateTarget.apply(lines, ShapeRepresentation3D);
+    UpdateTarget.apply(lines, MVSShapeRepresentation3D);
     return data;
 }
 

src/extensions/mvs/mvs-data.ts

@@ -1,11 +1,13 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
+ * @author David Sehnal <david.sehnal@gmail.com>
  */
 
 import { treeValidationIssues } from './tree/generic/tree-schema';
 import { treeToString } from './tree/generic/tree-utils';
+import { MVSAnimationSchema, MVSAnimationTree } from './tree/animation/animation-tree';
 import { Root, createMVSBuilder } from './tree/mvs/mvs-builder';
 import { MVSTree, MVSTreeSchema } from './tree/mvs/mvs-tree';
 
@@ -53,6 +55,8 @@ export interface Snapshot {
     root: MVSTree,
     /** Associated metadata */
     metadata: SnapshotMetadata,
+    /** Optional animation */
+    animation?: MVSAnimationTree,
 }
 
 /** MVSData with a single state */
@@ -189,7 +193,14 @@ function majorVersion(semanticVersion: string | number): number | undefined {
 
 function snapshotValidationIssues(snapshot: MVSData_State | Snapshot, options: { noExtra?: boolean } = {}): string[] | undefined {
     if (snapshot.root === undefined) return [`"root" missing in snapshot`];
-    return treeValidationIssues(MVSTreeSchema, snapshot.root, options);
+    const state = treeValidationIssues(MVSTreeSchema, snapshot.root, options);
+    const animation = 'animation' in snapshot && snapshot.animation !== undefined
+        ? treeValidationIssues(MVSAnimationSchema, snapshot.animation, options)
+        : undefined;
+    if (state && animation) return [...state, ...animation];
+    if (state) return state;
+    if (animation) return animation;
+    return undefined;
 }
 
 /** Return the current universal time, in ISO format, e.g. '2023-11-24T10:45:49.873Z' */

src/extensions/mvs/tree/animation/animation-tree.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { bool, float, int, list, OptionalField, RequiredField, str, union, nullable, literal, ValueFor } from '../generic/field-schema';
+import { SimpleParamsSchema, UnionParamsSchema } from '../generic/params-schema';
+import { NodeFor, ParamsOfKind, SubtreeOfKind, TreeFor, TreeSchema } from '../generic/tree-schema';
+import { ColorT, ContinuousPalette, DiscretePalette, Matrix, Vector3 } from '../mvs/param-types';
+
+const Easing = literal(
+    'linear',
+    'bounce-in', 'bounce-out', 'bounce-in-out',
+    'circle-in', 'circle-out', 'circle-in-out',
+    'cubic-in', 'cubic-out', 'cubic-in-out',
+    'exp-in', 'exp-out', 'exp-in-out',
+    'quad-in', 'quad-out', 'quad-in-out',
+    'sin-in', 'sin-out', 'sin-in-out',
+);
+
+export type MVSAnimationEasing = ValueFor<typeof Easing>;
+
+const _Noise = {
+    noise_magnitude: OptionalField(float, 0, 'Magnitude of the noise to apply to the interpolated value.')
+    // support cummulative noise?
+};
+
+const _Common = {
+    target_ref: RequiredField(str, 'Reference to the node.'),
+    property: RequiredField(union(str, list(union(str, int))), 'Value accessor.'),
+    start_ms: OptionalField(float, 0, 'Start time of the transition in milliseconds.'),
+    duration_ms: RequiredField(float, 'Duration of the transition in milliseconds.'),
+};
+
+const _Frequency = {
+    frequency: OptionalField(int, 1, 'Determines how many times the interpolation loops. Current T = frequency * t mod 1.'),
+    alternate_direction: OptionalField(bool, false, 'Whether to alternate the direction of the interpolation for frequency > 1.'),
+};
+
+const _Easing = {
+    easing: OptionalField(Easing, 'linear', 'Easing function to use for the transition.'),
+};
+
+const ScalarInterpolation = {
+    ..._Common,
+    ..._Frequency,
+    ..._Easing,
+    start: OptionalField(nullable(union(float, list(float))), null, 'Start value. If a list of values is provided, each element will be interpolated separately. If unset, parent state value is used.'),
+    end: OptionalField(nullable(union(float, list(float))), null, 'End value. If a list of values is provided, each element will be interpolated separately. If unset, only noise is applied.'),
+    discrete: OptionalField(bool, false, 'Whether to round the values to the closest integer. Useful for example for trajectory animation.'),
+    ..._Noise,
+};
+
+const Vec3Interpolation = {
+    ..._Common,
+    ..._Frequency,
+    ..._Easing,
+    start: OptionalField(nullable(list(float)), null, 'Start value. If unset, parent state value is used. Must be array of length 3N (x1, y1, z1, x2, y2, z2, ...).'),
+    end: OptionalField(nullable(list(float)), null, 'End value. Must be array of length 3N (x1, y1, z1, x2, y2, z2, ...). If unset, only noise is applied.'),
+    spherical: OptionalField(bool, false, 'Whether to use spherical interpolation.'),
+    ..._Noise,
+};
+
+const RotationMatrixInterpolation = {
+    ..._Common,
+    ..._Frequency,
+    ..._Easing,
+    start: OptionalField(nullable(Matrix), null, 'Start value. If unset, parent state value is used.'),
+    end: OptionalField(nullable(Matrix), null, 'End value. If unset, only noise is applied.'),
+    ..._Noise,
+};
+
+const ColorInterpolation = {
+    ..._Common,
+    ..._Frequency,
+    ..._Easing,
+    start: OptionalField(nullable(ColorT), null, 'Start value. If unset, parent state value is used.'),
+    end: OptionalField(nullable(ColorT), null, 'End value.'),
+    palette: OptionalField(nullable(union(DiscretePalette, ContinuousPalette)), null, 'Palette to sample colors from. Overrides start and end values.'),
+};
+
+const TransformationMatrixInterpolation = {
+    ..._Common,
+    pivot: OptionalField(nullable(Vector3), null, 'Pivot point for rotation and scale.'),
+    rotation_start: OptionalField(nullable(Matrix), null, 'Start rotation value. If unset, parent state value is used.'),
+    rotation_end: OptionalField(nullable(Matrix), null, 'End rotation value. If unset, only noise is applied.'),
+    rotation_noise_magnitude: OptionalField(float, 0, 'Magnitude of the noise to apply to the rotation.'),
+    rotation_easing: OptionalField(Easing, 'linear', 'Easing function to use for the rotation.'),
+    rotation_frequency: OptionalField(int, 1, 'Determines how many times the rotation interpolation loops. Current T = frequency * t mod 1.'),
+    rotation_alternate_direction: OptionalField(bool, false, 'Whether to alternate the direction of the interpolation for frequency > 1.'),
+    translation_start: OptionalField(nullable(Vector3), null, 'Start translation value. If unset, parent state value is used.'),
+    translation_end: OptionalField(nullable(Vector3), null, 'End translation value. If unset, only noise is applied.'),
+    translation_noise_magnitude: OptionalField(float, 0, 'Magnitude of the noise to apply to the translation.'),
+    translation_easing: OptionalField(Easing, 'linear', 'Easing function to use for the translation.'),
+    translation_frequency: OptionalField(int, 1, 'Determines how many times the translation interpolation loops. Current T = frequency * t mod 1.'),
+    translation_alternate_direction: OptionalField(bool, false, 'Whether to alternate the direction of the interpolation for frequency > 1.'),
+    scale_start: OptionalField(nullable(Vector3), null, 'Start scale value. If unset, parent state value is used.'),
+    scale_end: OptionalField(nullable(Vector3), null, 'End scale value. If unset, only noise is applied.'),
+    scale_noise_magnitude: OptionalField(float, 0, 'Magnitude of the noise to apply to the scale.'),
+    scale_easing: OptionalField(Easing, 'linear', 'Easing function to use for the scale.'),
+    scale_frequency: OptionalField(int, 1, 'Determines how many times the scale interpolation loops. Current T = frequency * t mod 1.'),
+    scale_alternate_direction: OptionalField(bool, false, 'Whether to alternate the direction of the interpolation for frequency > 1.'),
+};
+
+export const MVSAnimationSchema = TreeSchema({
+    rootKind: 'animation',
+    nodes: {
+        animation: {
+            description: 'Animation root node',
+            parent: [],
+            params: SimpleParamsSchema({
+                frame_time_ms: OptionalField(float, 1000 / 60, 'Frame time in milliseconds'),
+                duration_ms: OptionalField(nullable(float), null, 'Total duration of the animation. If not specified, computed as maximum of all transitions.'),
+                autoplay: OptionalField(bool, true, 'Determines whether the animation should autoplay when a snapshot is loaded'),
+                loop: OptionalField(bool, false, 'Determines whether the animation should loop when it reaches the end'),
+                include_camera: OptionalField(bool, false, 'Determines whether the camera state should be included in the animation'),
+                include_canvas: OptionalField(bool, false, 'Determines whether the canvas state should be included in the animation'),
+            }),
+        },
+        interpolate: {
+            description: 'This node enables interpolating between values',
+            parent: ['animation'],
+            params: UnionParamsSchema(
+                'kind',
+                'Interpolation kind',
+                {
+                    scalar: SimpleParamsSchema(ScalarInterpolation),
+                    vec3: SimpleParamsSchema(Vec3Interpolation),
+                    rotation_matrix: SimpleParamsSchema(RotationMatrixInterpolation),
+                    transform_matrix: SimpleParamsSchema(TransformationMatrixInterpolation),
+                    color: SimpleParamsSchema(ColorInterpolation),
+                },
+            )
+        }
+    }
+});
+
+export type MVSAnimationKind = keyof typeof MVSAnimationSchema.nodes
+export type MVSAnimationNode<TKind extends MVSAnimationKind = MVSAnimationKind> = NodeFor<typeof MVSAnimationSchema, TKind>
+export type MVSAnimationTree = TreeFor<typeof MVSAnimationSchema>
+export type MVSAnimationNodeParams<TKind extends MVSAnimationKind> = ParamsOfKind<MVSAnimationTree, TKind>
+export type MVSAnimationSubtree<TKind extends MVSAnimationKind = MVSAnimationKind> = SubtreeOfKind<MVSAnimationTree, TKind>

src/extensions/mvs/tree/generic/_spec/field-schema.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -48,7 +48,7 @@ describe('fieldValidationIssues', () => {
         expect(fieldValidationIssues(numberParam, undefined)).toBeTruthy();
     });
     it('fieldValidationIssues union', async () => {
-        const stringOrNumberParam = RequiredField(union([str, float]), 'Testing required field stringOrNumberParam');
+        const stringOrNumberParam = RequiredField(union(str, float), 'Testing required field stringOrNumberParam');
         expect(fieldValidationIssues(stringOrNumberParam, 1)).toBeUndefined();
         expect(fieldValidationIssues(stringOrNumberParam, 2)).toBeUndefined();
         expect(fieldValidationIssues(stringOrNumberParam, 'hello')).toBeUndefined();

src/extensions/mvs/tree/generic/field-schema.ts

@@ -1,15 +1,13 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
 import * as iots from 'io-ts';
-import { PathReporter } from 'io-ts/PathReporter';
 import { onelinerJsonString } from '../../../../mol-util/json';
 
-
 /** All types that can be used in tree node params.
  * Can be extended, this is just to list them all in one place and possibly catch some typing errors */
 type AllowedValueTypes = string | number | boolean | null | [number, number, number] | string[] | number[] | {};
@@ -26,34 +24,74 @@ export const bool = iots.boolean;
 export const tuple = iots.tuple;
 /** Type definition for a list/array, e.g. `list(str)`  */
 export const list = iots.array;
-/** Type definition for union types, e.g. `union([str, int])` means string or integer  */
-export const union = iots.union;
-/** Type definition used to create objects */
-export const obj = iots.type;
-/** Type definition used to create partial objects */
-export const partial = iots.partial;
+/** Type definition for a dictionary/mapping/record, e.g. `dict(str, float)` means type `{ [K in string]: number }` */
+export const dict = iots.record;
+
+/** Type definition used to create objects, e.g. `object({ name: str, age: float }, { address: str })` means type `{ name: string, age: number, address?: string }` */
+export function object<P extends iots.Props, Q extends iots.Props>(props: P, optionalProps: undefined, name?: string): iots.TypeC<P>;
+export function object<P extends iots.Props, Q extends iots.Props>(props: P, optionalProps: Q, name?: string): iots.IntersectionC<[iots.TypeC<P>, iots.PartialC<Q>]>;
+export function object<P extends iots.Props, Q extends iots.Props>(props: P, optionalProps?: Q, name?: string) {
+    if (!optionalProps) {
+        return iots.type(props, name);
+    }
+
+    if (name === undefined) {
+        const nameChunks = [];
+        for (const key in props) {
+            nameChunks.push(`${key}: ${props[key].name}`);
+        }
+        for (const key in optionalProps) {
+            nameChunks.push(`${key}?: ${optionalProps[key].name}`);
+        }
+        name = `{ ${nameChunks.join(', ')} }`;
+    }
+    return iots.intersection([iots.type(props), iots.partial(optionalProps)], name);
+}
+
+/** Type definition used to create partial objects, e.g. `partial({ name: str, age: float })` means type `{ name?: string, age?: number }` */
+export function partial<P extends iots.Props>(props: P, name?: string) {
+    if (name === undefined) {
+        const nameChunks = [];
+        for (const key in props) {
+            nameChunks.push(`${key}?: ${props[key].name}`);
+        }
+        name = `{ ${nameChunks.join(', ')} }`;
+    }
+    return iots.partial(props, name);
+}
+
+/** Type definition for union types, e.g. `union(str, int)` means string or integer */
+export function union<T1 extends iots.Mixed, T2 extends iots.Mixed, TOthers extends iots.Mixed[]>(first: T1, second: T2, ...others: TOthers): iots.UnionC<[T1, T2, ...TOthers]> {
+    const baseTypes: iots.Mixed[] = [];
+    for (const type of [first, second, ...others]) {
+        if (type instanceof iots.UnionType) {
+            baseTypes.push(...type.types);
+        } else {
+            baseTypes.push(type);
+        }
+    }
+    return iots.union(baseTypes as any);
+}
 
 /** Type definition for nullable types, e.g. `nullable(str)` means string or `null`  */
-export function nullable<T extends iots.Type<any>>(type: T) {
-    return union([type, iots.null]);
+export function nullable<V>(type: iots.Type<V>): iots.Type<V | null> {
+    return union(type, iots.null);
 }
+
 /** Type definition for literal types, e.g. `literal('red', 'green', 'blue')` means 'red' or 'green' or 'blue'  */
 export function literal<V extends string | number | boolean>(...values: V[]) {
     if (values.length === 0) {
         throw new Error(`literal type must have at least one value`);
     }
-    const typeName = `(${values.map(v => onelinerJsonString(v)).join(' | ')})`;
+    const typeName = values.length === 1 ? onelinerJsonString(values[0]) : `(${values.map(v => onelinerJsonString(v)).join(' | ')})`;
+    const valueSet = new Set(values);
     return new iots.Type<V>(
         typeName,
-        ((value: any) => values.includes(value)) as any,
-        (value, ctx) => values.includes(value as any) ? { _tag: 'Right', right: value as any } : { _tag: 'Left', left: [{ value: value, context: ctx, message: `"${value}" is not a valid value for literal type ${typeName}` }] },
+        ((value: any) => valueSet.has(value)) as any,
+        (value, ctx) => valueSet.has(value as any) ? { _tag: 'Right', right: value as any } : { _tag: 'Left', left: [{ value: value, context: ctx, message: `"${value}" is not a valid value for literal type ${typeName}` }] },
         value => value
     );
 }
-/** Type definition for mapping between two types, e.g. `mapping(str, float)` means type `{ [key in string]: number }` */
-export function mapping<A extends iots.Type<any>, B extends iots.Type<any>>(from: A, to: B) {
-    return iots.record(from, to);
-}
 
 
 interface FieldBase<V extends AllowedValueTypes = any, R extends boolean = boolean> {
@@ -102,6 +140,41 @@ export function fieldValidationIssues<F extends Field>(field: F, value: any): st
     if (validation._tag === 'Right') {
         return undefined;
     } else {
-        return PathReporter.report(validation);
+        return reportErrors(validation.left);
     }
 }
+
+// Inlining `reportErrors` instead of `import { PathReporter } from 'io-ts/PathReporter'`;
+// because it breaks Deno usage.
+
+function reportErrors(errors: iots.Errors): string[] | undefined {
+    if (errors.length === 0) return undefined;
+    return errors.map(getMessage);
+}
+
+function getMessage(e: iots.ValidationError) {
+    return e.message !== undefined
+        ? e.message
+        : `Invalid value ${stringifyError(e.value)} supplied to ${getContextPath(e.context)}`;
+}
+
+function getContextPath(context: iots.ValidationError['context']) {
+    return context.map(a => `${a.key}: ${a.type.name}`).join('/');
+}
+
+function getFunctionName(f: Function & { displayName?: string }) {
+    return f.displayName || f.name || `<function ${f.length}>`;
+}
+
+function stringifyError(v: any) {
+    if (typeof v === 'function') {
+        return getFunctionName(v);
+    }
+    if (typeof v === 'number' && !isFinite(v)) {
+        if (isNaN(v)) {
+            return 'NaN';
+        }
+        return v > 0 ? 'Infinity' : '-Infinity';
+    }
+    return JSON.stringify(v);
+}

src/extensions/mvs/tree/generic/tree-utils.ts

@@ -86,7 +86,7 @@ export function copyTree<T extends Tree>(root: T): T {
  * nodes of kind `C` will be converted to `Y` with a child `Z` (original children moved to `Z`),
  * nodes of other kinds will just be copied. */
 export type ConversionRules<A extends Tree, B extends Tree> = {
-    [kind in Kind<Subtree<A>>]?: (node: SubtreeOfKind<A, kind>, parent?: Subtree<A>) => Subtree<B>[]
+    [kind in Kind<Subtree<A>>]?: (node: SubtreeOfKind<A, kind>, parent?: Subtree<A>) => { subtree: Subtree<B>[] }
 };
 
 /** Apply a set of conversion rules to a tree to change to a different schema. */
@@ -94,12 +94,12 @@ export function convertTree<A extends Tree, B extends Tree>(root: A, conversions
     const mapping = new Map<Subtree<A>, Subtree<B>>();
     let convertedRoot: Subtree<B>;
     dfs<A>(root, (node, parent) => {
-        const conversion = conversions[node.kind as (typeof node)['kind']] as ((n: typeof node, p?: Subtree<A>) => Subtree<B>[]) | undefined;
+        const conversion = conversions[node.kind as (typeof node)['kind']] as ((n: typeof node, p?: Subtree<A>) => { subtree: Subtree<B>[] }) | undefined;
         if (conversion) {
-            const convertidos = conversion(node, parent);
-            if (!parent && convertidos.length === 0) throw new Error('Cannot convert root to empty path');
+            const converted = conversion(node, parent);
+            if (!parent && converted?.subtree.length === 0) throw new Error('Cannot convert root to empty path');
             let convParent = parent ? mapping.get(parent) : undefined;
-            for (const conv of convertidos) {
+            for (const conv of converted.subtree) {
                 if (convParent) {
                     (convParent.children ??= []).push(conv);
                 } else {
@@ -153,12 +153,14 @@ export function addDefaults<S extends TreeSchema>(tree: TreeFor<S>, treeSchema:
     type TTree = TreeFor<S>;
     const rules: ConversionRules<TTree, TTree> = {};
     for (const kind in treeSchema.nodes) {
-        rules[kind as Kind<Subtree<TTree>>] = node => [{
-            kind: node.kind,
-            params: addParamDefaults(treeSchema.nodes[kind].params, node.params as any),
-            custom: node.custom,
-            ref: node.ref,
-        } as Node as any];
+        rules[kind as Kind<Subtree<TTree>>] = node => ({
+            subtree: [{
+                kind: node.kind,
+                params: addParamDefaults(treeSchema.nodes[kind].params, node.params as any),
+                custom: node.custom,
+                ref: node.ref,
+            } as Node as any]
+        });
     }
     return convertTree(tree, rules) as any;
 }

src/extensions/mvs/tree/molstar/conversion.ts

@@ -15,37 +15,76 @@ import { MolstarKind, MolstarNode, MolstarTree } from './molstar-tree';
 /** Convert `format` parameter of `parse` node in `MolstarTree`
  * into `format` and `is_binary` parameters in `MolstarTree` */
 export const ParseFormatMvsToMolstar = {
+    // trajectory
     mmcif: { format: 'cif', is_binary: false },
     bcif: { format: 'cif', is_binary: true },
     pdb: { format: 'pdb', is_binary: false },
+    pdbqt: { format: 'pdbqt', is_binary: false },
+    gro: { format: 'gro', is_binary: false },
+    xyz: { format: 'xyz', is_binary: false },
+    mol: { format: 'mol', is_binary: false },
+    sdf: { format: 'sdf', is_binary: false },
+    mol2: { format: 'mol2', is_binary: false },
+    lammpstrj: { format: 'lammpstrj', is_binary: false },
+    // coordinates
+    xtc: { format: 'xtc', is_binary: true },
+    // maps
     map: { format: 'map', is_binary: true },
 } satisfies { [p in ParseFormatT]: { format: MolstarParseFormatT, is_binary: boolean } };
 
-
 /** Conversion rules for conversion from `MVSTree` (with all parameter values) to `MolstarTree` */
 const mvsToMolstarConversionRules: ConversionRules<FullMVSTree, MolstarTree> = {
-    'download': node => [],
+    'download': node => ({ subtree: [] }),
     'parse': (node, parent) => {
         const { format, is_binary } = ParseFormatMvsToMolstar[node.params.format];
-        const convertedNode: MolstarNode<'parse'> = { kind: 'parse', params: { ...node.params, format }, custom: node.custom, ref: node.ref };
         if (parent?.kind === 'download') {
-            return [
-                { kind: 'download', params: { ...parent.params, is_binary }, custom: parent.custom, ref: parent.ref },
-                convertedNode,
-            ] satisfies MolstarNode[];
+            return {
+                subtree: [
+                    { kind: 'download', params: { ...parent.params, is_binary }, custom: parent.custom, ref: parent.ref },
+                    { kind: 'parse', params: { ...node.params, format }, custom: node.custom, ref: node.ref }
+                ] satisfies MolstarNode[]
+            };
         } else {
             console.warn('"parse" node is not being converted, this is suspicious');
-            return [convertedNode] satisfies MolstarNode[];
+            return {
+                subtree: [
+                    { kind: 'parse', params: { ...node.params, format }, custom: node.custom, ref: node.ref }
+                ] satisfies MolstarNode[]
+            };
         }
     },
+    'coordinates': (node, parent) => {
+        if (parent?.kind !== 'parse') throw new Error(`Parent of "coordinates" must be "parse", not "${parent?.kind}".`);
+        const { format } = ParseFormatMvsToMolstar[parent.params.format];
+        return {
+            subtree: [
+                { kind: 'coordinates', params: { format }, custom: node.custom, ref: node.ref }
+            ] satisfies MolstarNode[]
+        };
+    },
     'structure': (node, parent) => {
         if (parent?.kind !== 'parse') throw new Error(`Parent of "structure" must be "parse", not "${parent?.kind}".`);
         const { format } = ParseFormatMvsToMolstar[parent.params.format];
-        return [
-            { kind: 'trajectory', params: { format, ...pickObjectKeys(node.params, ['block_header', 'block_index']) } },
-            { kind: 'model', params: pickObjectKeys(node.params, ['model_index']) },
-            { kind: 'structure', params: omitObjectKeys(node.params, ['block_header', 'block_index', 'model_index']), custom: node.custom, ref: node.ref },
-        ] satisfies MolstarNode[];
+
+        if (node.params.coordinates_ref) {
+            return {
+                subtree: [
+                    { kind: 'trajectory', params: { format, ...pickObjectKeys(node.params, ['block_header', 'block_index']) } },
+                    { kind: 'model', params: { model_index: 0 } },
+                    { kind: 'trajectory_with_coordinates', params: { coordinates_ref: node.params.coordinates_ref } },
+                    { kind: 'model', params: pickObjectKeys(node.params, ['model_index']) },
+                    { kind: 'structure', params: omitObjectKeys(node.params, ['block_header', 'block_index', 'model_index', 'coordinates_ref']), custom: node.custom, ref: node.ref },
+                ] satisfies MolstarNode[]
+            };
+        } else {
+            return {
+                subtree: [
+                    { kind: 'trajectory', params: { format, ...pickObjectKeys(node.params, ['block_header', 'block_index']) } },
+                    { kind: 'model', params: pickObjectKeys(node.params, ['model_index']) },
+                    { kind: 'structure', params: omitObjectKeys(node.params, ['block_header', 'block_index', 'model_index', 'coordinates_ref']), custom: node.custom, ref: node.ref },
+                ] satisfies MolstarNode[]
+            };
+        }
     },
 };
 
@@ -70,9 +109,20 @@ function fileExtensionMatches(filename: string, extensions: (FileExtension | '*'
 }
 
 const StructureFormatExtensions: Record<ParseFormatT, (FileExtension | '*')[]> = {
+    // trajectory
     mmcif: ['.cif', '.mmif'],
     bcif: ['.bcif'],
     pdb: ['.pdb', '.ent'],
+    pdbqt: ['.pdbqt'],
+    gro: ['.gro'],
+    xyz: ['.xyz'],
+    mol: ['.mol'],
+    sdf: ['.sdf'],
+    mol2: ['.mol2'],
+    lammpstrj: ['.lammpstrj'],
+    // coordinates
+    xtc: ['.xtc'],
+    // volumes
     map: ['.map', '.ccp4', '.mrc', '.mrcs'],
 };
 

src/extensions/mvs/tree/molstar/molstar-tree.ts

@@ -5,7 +5,7 @@
  */
 
 import { omitObjectKeys, pickObjectKeys } from '../../../../mol-util/object';
-import { RequiredField, bool } from '../generic/field-schema';
+import { RequiredField, bool, str } from '../generic/field-schema';
 import { SimpleParamsSchema } from '../generic/params-schema';
 import { NodeFor, ParamsOfKind, SubtreeOfKind, TreeFor, TreeSchema } from '../generic/tree-schema';
 import { FullMVSTreeSchema } from '../mvs/mvs-tree';
@@ -30,6 +30,14 @@ export const MolstarTreeSchema = TreeSchema({
                 format: RequiredField(MolstarParseFormatT, 'File format'),
             }),
         },
+        /** Auxiliary node corresponding to Molstar's CoordinatesFrom*. */
+        coordinates: {
+            description: "Auxiliary node corresponding to Molstar's CoordinatesFrom*.",
+            parent: ['parse'],
+            params: SimpleParamsSchema({
+                format: RequiredField(MolstarParseFormatT, 'File format'),
+            }),
+        },
         /** Auxiliary node corresponding to Molstar's TrajectoryFrom*. */
         trajectory: {
             description: "Auxiliary node corresponding to Molstar's TrajectoryFrom*.",
@@ -39,10 +47,18 @@ export const MolstarTreeSchema = TreeSchema({
                 ...pickObjectKeys(FullMVSTreeSchema.nodes.structure.params.fields, ['block_header', 'block_index'] as const),
             }),
         },
+        /** Auxiliary node corresponding to Molstar's TrajectoryFrom*. */
+        trajectory_with_coordinates: {
+            description: 'Auxiliary node corresponding to assigning a separate coordinates to a trajectory.',
+            parent: ['model'],
+            params: SimpleParamsSchema({
+                coordinates_ref: RequiredField(str, 'Coordinates reference'),
+            }),
+        },
         /** Auxiliary node corresponding to Molstar's ModelFromTrajectory. */
         model: {
             description: "Auxiliary node corresponding to Molstar's ModelFromTrajectory.",
-            parent: ['trajectory'],
+            parent: ['trajectory', 'trajectory_with_coordinates'],
             params: SimpleParamsSchema(
                 pickObjectKeys(FullMVSTreeSchema.nodes.structure.params.fields, ['model_index'] as const)
             ),
@@ -52,7 +68,7 @@ export const MolstarTreeSchema = TreeSchema({
             ...FullMVSTreeSchema.nodes.structure,
             parent: ['model'],
             params: SimpleParamsSchema(
-                omitObjectKeys(FullMVSTreeSchema.nodes.structure.params.fields, ['block_header', 'block_index', 'model_index'] as const)
+                omitObjectKeys(FullMVSTreeSchema.nodes.structure.params.fields, ['block_header', 'block_index', 'model_index', 'coordinates_ref'] as const)
             ),
         },
     }

src/extensions/mvs/tree/mvs/mvs-builder.ts

@@ -8,6 +8,7 @@
 import { deepClone, pickObjectKeys } from '../../../../mol-util/object';
 import { GlobalMetadata, MVSData_State, Snapshot, SnapshotMetadata } from '../../mvs-data';
 import { CustomProps } from '../generic/tree-schema';
+import { MVSAnimationNodeParams, MVSAnimationSubtree } from '../animation/animation-tree';
 import { MVSKind, MVSNode, MVSNodeParams, MVSSubtree } from './mvs-tree';
 
 
@@ -50,6 +51,8 @@ class _Base<TKind extends MVSKind> {
 
 /** MVS builder pointing to the 'root' node */
 export class Root extends _Base<'root'> implements FocusMixin, PrimitivesMixin {
+    protected _animation: Animation | undefined = undefined;
+
     constructor(params_: CustomAndRef) {
         const { custom, ref } = params_;
         const node: MVSNode<'root'> = { kind: 'root', custom, ref };
@@ -69,6 +72,7 @@ export class Root extends _Base<'root'> implements FocusMixin, PrimitivesMixin {
         return {
             root: deepClone(this._node),
             metadata: { ...metadata },
+            animation: this?._animation ? deepClone(this._animation.node) : undefined,
         };
     }
 
@@ -89,6 +93,43 @@ export class Root extends _Base<'root'> implements FocusMixin, PrimitivesMixin {
     focus = bindMethod(this, FocusMixinImpl, 'focus');
     primitives = bindMethod(this, PrimitivesMixinImpl, 'primitives');
     primitives_from_uri = bindMethod(this, PrimitivesMixinImpl, 'primitives_from_uri');
+
+    animation(params: MVSAnimationNodeParams<'animation'> & CustomAndRef = {}): Animation {
+        this._animation ??= new Animation(params);
+        return this._animation;
+    }
+
+    /** Modifies custom state of the root */
+    extendRootCustomState(custom: Record<string, any>): this {
+        this._node.custom = { ...this._node.custom, ...custom };
+        return this;
+    }
+}
+
+export class Animation {
+    private _node: MVSAnimationSubtree<'animation'>;
+    constructor(
+        parameters: MVSAnimationNodeParams<'animation'> & CustomAndRef
+    ) {
+        this._node = {
+            kind: 'animation',
+            children: [],
+            ...splitParams<MVSAnimationNodeParams<'animation'>>(parameters),
+        };
+    }
+
+    get node(): MVSAnimationSubtree<'animation'> {
+        return this._node;
+    }
+
+    interpolate(params: MVSAnimationNodeParams<'interpolate'> & CustomAndRef): Animation {
+        const node = {
+            kind: 'interpolate',
+            ...splitParams<MVSAnimationNodeParams<'interpolate'>>(params)
+        } as MVSAnimationSubtree<'interpolate'>;
+        this._node.children!.push(node);
+        return this;
+    }
 }
 
 
@@ -103,10 +144,10 @@ export class Download extends _Base<'download'> {
 
 /** Subsets of 'structure' node params which will be passed to individual builder functions. */
 const StructureParamsSubsets = {
-    model: ['block_header', 'block_index', 'model_index'],
-    assembly: ['block_header', 'block_index', 'model_index', 'assembly_id'],
-    symmetry: ['block_header', 'block_index', 'model_index', 'ijk_min', 'ijk_max'],
-    symmetry_mates: ['block_header', 'block_index', 'model_index', 'radius'],
+    model: ['block_header', 'block_index', 'model_index', 'coordinates_ref'],
+    assembly: ['block_header', 'block_index', 'model_index', 'assembly_id', 'coordinates_ref'],
+    symmetry: ['block_header', 'block_index', 'model_index', 'ijk_min', 'ijk_max', 'coordinates_ref'],
+    symmetry_mates: ['block_header', 'block_index', 'model_index', 'radius', 'coordinates_ref'],
 } satisfies { [kind in MVSNodeParams<'structure'>['type']]: (keyof MVSNodeParams<'structure'>)[] };
 
 
@@ -156,11 +197,16 @@ export class Parse extends _Base<'parse'> {
     volume(params: MVSNodeParams<'volume'> & CustomAndRef = {}): Volume {
         return new Volume(this._root, this.addChild('volume', params));
     }
+    /** Add a 'coordinates' node indicating the parsed data type */
+    coordinates(params: MVSNodeParams<'coordinates'> & CustomAndRef = {}): Parse {
+        this.addChild('coordinates', params);
+        return this;
+    }
 }
 
 
 /** MVS builder pointing to a 'structure' node */
-export class Structure extends _Base<'structure'> implements PrimitivesMixin {
+export class Structure extends _Base<'structure'> implements PrimitivesMixin, TransformMixin {
     /** Add a 'component' node and return builder pointing to it. 'component' node instructs to create a component (i.e. a subset of the parent structure). */
     component(params: Partial<MVSNodeParams<'component'>> & CustomAndRef = {}): Component {
         const fullParams = { ...params, selector: params.selector ?? 'all' };
@@ -194,21 +240,15 @@ export class Structure extends _Base<'structure'> implements PrimitivesMixin {
         this.addChild('tooltip_from_source', params);
         return this;
     }
-    /** Add a 'transform' node and return builder pointing back to the structure node. 'transform' node instructs to rotate and/or translate structure coordinates. */
-    transform(params: MVSNodeParams<'transform'> & CustomAndRef = {}): Structure {
-        if (params.rotation && params.rotation.length !== 9) {
-            throw new Error('ValueError: `rotation` parameter must be an array of 9 numbers');
-        }
-        this.addChild('transform', params);
-        return this;
-    }
+    transform = bindMethod(this, TransformMixinImpl, 'transform');
+    instance = bindMethod(this, TransformMixinImpl, 'instance');
     primitives = bindMethod(this, PrimitivesMixinImpl, 'primitives');
     primitives_from_uri = bindMethod(this, PrimitivesMixinImpl, 'primitives_from_uri');
 }
 
 
 /** MVS builder pointing to a 'component' or 'component_from_uri' or 'component_from_source' node */
-export class Component extends _Base<'component' | 'component_from_uri' | 'component_from_source'> implements FocusMixin {
+export class Component extends _Base<'component' | 'component_from_uri' | 'component_from_source'> implements FocusMixin, TransformMixin {
     /** Add a 'representation' node and return builder pointing to it. 'representation' node instructs to create a visual representation of a component. */
     representation(params: Partial<MVSNodeParams<'representation'>> & CustomAndRef = {}): Representation {
         const fullParams: MVSNodeParams<'representation'> = { ...params, type: params.type ?? 'cartoon' };
@@ -225,6 +265,8 @@ export class Component extends _Base<'component' | 'component_from_uri' | 'compo
         return this;
     }
     focus = bindMethod(this, FocusMixinImpl, 'focus');
+    transform = bindMethod(this, TransformMixinImpl, 'transform');
+    instance = bindMethod(this, TransformMixinImpl, 'instance');
 }
 
 
@@ -250,17 +292,26 @@ export class Representation extends _Base<'representation'> {
         this.addChild('opacity', params);
         return this;
     }
+    /** Add a 'clip' node and return builder pointing back to the representation node. 'clip' node instructs to apply clipping to a visual representation. */
+    clip(params: MVSNodeParams<'clip'> & CustomAndRef): Representation {
+        this.addChild('clip', params);
+        return this;
+    }
 }
 
 
 /** MVS builder pointing to a 'component' or 'component_from_uri' or 'component_from_source' node */
-export class Volume extends _Base<'volume'> implements FocusMixin {
+export class Volume extends _Base<'volume'> implements FocusMixin, TransformMixin {
     /** Add a 'representation' node and return builder pointing to it. 'representation' node instructs to create a visual representation of a component. */
-    representation(params: Partial<MVSNodeParams<'volume_representation'>> & CustomAndRef = {}): VolumeRepresentation {
-        const fullParams: MVSNodeParams<'volume_representation'> = { ...params, type: params.type ?? 'isosurface' };
-        return new VolumeRepresentation(this._root, this.addChild('volume_representation', fullParams));
+    representation(params?: MVSNodeParams<'volume_representation'> & CustomAndRef): VolumeRepresentation {
+        if (!params) {
+            params = { type: 'isosurface' };
+        }
+        return new VolumeRepresentation(this._root, this.addChild('volume_representation', params));
     }
     focus = bindMethod(this, FocusMixinImpl, 'focus');
+    transform = bindMethod(this, TransformMixinImpl, 'transform');
+    instance = bindMethod(this, TransformMixinImpl, 'instance');
 }
 
 
@@ -277,6 +328,11 @@ export class VolumeRepresentation extends _Base<'volume_representation'> impleme
         return this;
     }
     focus = bindMethod(this, FocusMixinImpl, 'focus');
+    /** Add a 'clip' node and return builder pointing back to the representation node. 'clip' node instructs to apply clipping to a visual representation. */
+    clip(params: MVSNodeParams<'clip'> & CustomAndRef): VolumeRepresentation {
+        this.addChild('clip', params);
+        return this;
+    }
 }
 
 
@@ -380,6 +436,37 @@ class PrimitivesMixinImpl extends _Base<MVSKind> implements PrimitivesMixin {
     }
 };
 
+interface TransformMixin {
+    /** Add a 'transform' node and return builder pointing back to this node. 'transform' node instructs to rotate and/or translate coordinates. */
+    transform(params: MVSNodeParams<'transform'> & CustomAndRef): this
+    /** Add an 'instance' node and return builder pointing back to this node. 'instance' node instructs to create a new instance of the object. */
+    instance(params: MVSNodeParams<'instance'> & CustomAndRef): this
+};
+class TransformMixinImpl extends _Base<MVSKind> implements TransformMixin {
+    transform(params: MVSNodeParams<'transform'> & CustomAndRef = {}): any {
+        validateTransformParams(params);
+        this.addChild('transform', params);
+        return this;
+    }
+
+    instance(params: MVSNodeParams<'instance'> & CustomAndRef = {}): any {
+        validateTransformParams(params);
+        this.addChild('instance', params);
+        return this;
+    }
+};
+
+function validateTransformParams(params: MVSNodeParams<'transform' | 'instance'> & CustomAndRef) {
+    if (params.rotation && params.rotation.length !== 9) {
+        throw new Error('ValueError: `rotation` parameter must be an array of 9 numbers');
+    }
+    if (params.matrix && params.matrix.length !== 16) {
+        throw new Error('ValueError: `matrix` parameter must be an array of 16 numbers');
+    }
+    if (params.matrix && (params.translation || params.rotation)) {
+        throw new Error('ValueError: `matrix` parameter cannot be used together with `translation` or `rotation` parameters');
+    }
+}
 
 /** Demonstration of usage of MVS builder */
 export function builderDemo() {

src/extensions/mvs/tree/mvs/mvs-tree-primitives.ts

@@ -1,11 +1,11 @@
 /**
- * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Adam Midlik <midlik@gmail.com>
  */
 
-import { bool, float, int, mapping, nullable, OptionalField, RequiredField, str, union } from '../generic/field-schema';
+import { bool, dict, float, int, nullable, OptionalField, RequiredField, str, union } from '../generic/field-schema';
 import { SimpleParamsSchema, UnionParamsSchema } from '../generic/params-schema';
 import { ColorT, FloatList, IntList, PrimitivePositionT, Vector3 } from './param-types';
 
@@ -31,9 +31,9 @@ const MeshParams = {
     /** Assign a number to each triangle to group them. If not specified, each triangle is considered a separate group (triangle i = group i). */
     triangle_groups: OptionalField(nullable(IntList), null, 'Assign a number to each triangle to group them. If not specified, each triangle is considered a separate group (triangle i = group i).'),
     /** Assign a color to each group. Where not assigned, uses `color`. */
-    group_colors: OptionalField(mapping(int, ColorT), {}, 'Assign a color to each group. Where not assigned, uses `color`.'),
+    group_colors: OptionalField(dict(int, ColorT), {}, 'Assign a color to each group. Where not assigned, uses `color`.'),
     /** Assign a tooltip to each group. Where not assigned, uses `tooltip`. */
-    group_tooltips: OptionalField(mapping(int, str), {}, 'Assign a tooltip to each group. Where not assigned, uses `tooltip`.'),
+    group_tooltips: OptionalField(dict(int, str), {}, 'Assign a tooltip to each group. Where not assigned, uses `tooltip`.'),
     /** Color of the triangles and wireframe. Can be overwritten by `group_colors`. If not specified, uses the parent primitives group `color`. */
     color: OptionalField(nullable(ColorT), null, 'Color of the triangles and wireframe. Can be overwritten by `group_colors`. If not specified, uses the parent primitives group `color`.'),
     /** Tooltip shown when hovering over the mesh. Can be overwritten by `group_tooltips`. If not specified, uses the parent primitives group `tooltip`. */
@@ -56,11 +56,11 @@ const LinesParams = {
     /** Assign a number to each triangle to group them. If not specified, each line is considered a separate group (line i = group i). */
     line_groups: OptionalField(nullable(IntList), null, 'Assign a number to each triangle to group them. If not specified, each line is considered a separate group (line i = group i).'),
     /** Assign a color to each group. Where not assigned, uses `color`. */
-    group_colors: OptionalField(mapping(int, ColorT), {}, 'Assign a color to each group. Where not assigned, uses `color`.'),
+    group_colors: OptionalField(dict(int, ColorT), {}, 'Assign a color to each group. Where not assigned, uses `color`.'),
     /** Assign a tooltip to each group. Where not assigned, uses `tooltip`. */
-    group_tooltips: OptionalField(mapping(int, str), {}, 'Assign a tooltip to each group. Where not assigned, uses `tooltip`.'),
+    group_tooltips: OptionalField(dict(int, str), {}, 'Assign a tooltip to each group. Where not assigned, uses `tooltip`.'),
     /** Assign a line width to each group. Where not assigned, uses `width`. */
-    group_widths: OptionalField(mapping(int, float), {}, 'Assign a line width to each group. Where not assigned, uses `width`.'),
+    group_widths: OptionalField(dict(int, float), {}, 'Assign a line width to each group. Where not assigned, uses `width`.'),
     /** Color of the lines. Can be overwritten by `group_colors`. If not specified, uses the parent primitives group `color`. */
     color: OptionalField(nullable(ColorT), null, 'Color of the lines. Can be overwritten by `group_colors`. If not specified, uses the parent primitives group `color`.'),
     /** Tooltip shown when hovering over the lines. Can be overwritten by `group_tooltips`. If not specified, uses the parent primitives group `tooltip`. */
@@ -87,15 +87,15 @@ const ArrowParams = {
     /** Draw a cap at the start of the arrow. */
     show_start_cap: OptionalField(bool, false, 'Draw a cap at the start of the arrow.'),
     /** Length of the start cap. */
-    start_cap_length: OptionalField(float, 0.1, 'Length of the start cap.'),
+    start_cap_length: OptionalField(nullable(float), null, 'Length of the start cap. If not provided, will be 2 * start_cap_radius.'),
     /** Radius of the start cap. */
-    start_cap_radius: OptionalField(float, 0.1, 'Radius of the start cap.'),
+    start_cap_radius: OptionalField(nullable(float), null, 'Radius of the start cap. If not provided, will be 2 * tube_radius.'),
     /** Draw an arrow at the end of the arrow. */
     show_end_cap: OptionalField(bool, false, 'Draw a cap at the end of the arrow.'),
     /** Height of the arrow at the end. */
-    end_cap_length: OptionalField(float, 0.1, 'Length of the end cap.'),
+    end_cap_length: OptionalField(nullable(float), null, 'Length of the end cap. If not provided, will be 2 * end_cap_radius.'),
     /** Radius of the arrow at the end. */
-    end_cap_radius: OptionalField(float, 0.1, 'Radius of the end cap.'),
+    end_cap_radius: OptionalField(nullable(float), null, 'Radius of the end cap. If not provided, will be 2 * tube_radius.'),
     /** Draw a tube connecting the start and end points. */
     show_tube: OptionalField(bool, true, 'Draw a tube connecting the start and end points.'),
     /** Tube radius (in Angstroms). */
@@ -143,6 +143,8 @@ const AngleMeasurementParams = {
     show_vector: OptionalField(bool, true, 'Draw vectors between (a, b) and (b, c).'),
     /** Color of the vectors. */
     vector_color: OptionalField(nullable(ColorT), null, 'Color of the vectors.'),
+    /** Radius of the vectors. */
+    vector_radius: OptionalField(float, 0.05, 'Radius of the vectors.'),
     /** Draw a filled circle section representing the angle. */
     show_section: OptionalField(bool, true, 'Draw a filled circle section representing the angle.'),
     /** Color of the angle section. If not specified, the primitives group color is used. */
@@ -207,9 +209,9 @@ const EllipsoidParams = {
     /** Minor axis endpoint. If specified, overrides minor axis to be minor_axis_endpoint - center. */
     minor_axis_endpoint: OptionalField(nullable(PrimitivePositionT), null, 'Minor axis endpoint. If specified, overrides minor axis to be minor_axis_endpoint - center.'),
     /** Radii of the ellipsoid along each axis. */
-    radius: OptionalField(nullable(union([Vector3, float])), null, 'Radii of the ellipsoid along each axis.'),
+    radius: OptionalField(nullable(union(Vector3, float)), null, 'Radii of the ellipsoid along each axis.'),
     /** Added to the radii of the ellipsoid along each axis. */
-    radius_extent: OptionalField(nullable(union([Vector3, float])), null, 'Added to the radii of the ellipsoid along each axis.'),
+    radius_extent: OptionalField(nullable(union(Vector3, float)), null, 'Added to the radii of the ellipsoid along each axis.'),
     /** Tooltip to show when hovering over the tube. If not specified, uses the parent primitives group `tooltip`. */
     tooltip: OptionalField(nullable(str), null, 'Tooltip to show when hovering over the tube. If not specified, uses the parent primitives group `tooltip`.'),
 };

src/extensions/mvs/tree/mvs/mvs-tree-representations.ts

@@ -4,8 +4,9 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import { bool, float, nullable, OptionalField } from '../generic/field-schema';
+import { bool, float, int, literal, nullable, OptionalField, RequiredField } from '../generic/field-schema';
 import { SimpleParamsSchema, UnionParamsSchema } from '../generic/params-schema';
+import { Matrix, Vector3 } from './param-types';
 
 const Cartoon = {
     /** Scales the corresponding visuals */
@@ -14,6 +15,11 @@ const Cartoon = {
     tubular_helices: OptionalField(bool, false, 'Simplify corkscrew helices to tubes.'),
 };
 
+const Backbone = {
+    /** Scales the corresponding visuals */
+    size_factor: OptionalField(float, 1, 'Scales the corresponding visuals.'),
+};
+
 const BallAndStick = {
     /** Scales the corresponding visuals */
     size_factor: OptionalField(float, 1, 'Scales the corresponding visuals.'),
@@ -21,6 +27,13 @@ const BallAndStick = {
     ignore_hydrogens: OptionalField(bool, false, 'Controls whether hydrogen atoms are drawn.'),
 };
 
+const Line = {
+    /** Scales the corresponding visuals */
+    size_factor: OptionalField(float, 1, 'Scales the corresponding visuals.'),
+    /** Controls whether hydrogen atoms are drawn. */
+    ignore_hydrogens: OptionalField(bool, false, 'Controls whether hydrogen atoms are drawn.'),
+};
+
 const Spacefill = {
     /** Scales the corresponding visuals */
     size_factor: OptionalField(float, 1, 'Scales the corresponding visuals.'),
@@ -34,6 +47,8 @@ const Carbohydrate = {
 };
 
 const Surface = {
+    /** Type of surface representation. (Default is 'molecular') */
+    surface_type: OptionalField(literal('molecular', 'gaussian'), 'molecular', `Type of surface representation. (Default is 'molecular')`),
     /** Scales the corresponding visuals */
     size_factor: OptionalField(float, 1, 'Scales the corresponding visuals.'),
     /** Controls whether hydrogen atoms are drawn. */
@@ -45,7 +60,9 @@ export const MVSRepresentationParams = UnionParamsSchema(
     'Representation type',
     {
         cartoon: SimpleParamsSchema(Cartoon),
+        backbone: SimpleParamsSchema(Backbone),
         ball_and_stick: SimpleParamsSchema(BallAndStick),
+        line: SimpleParamsSchema(Line),
         spacefill: SimpleParamsSchema(Spacefill),
         carbohydrate: SimpleParamsSchema(Carbohydrate),
         surface: SimpleParamsSchema(Surface),
@@ -63,10 +80,63 @@ const VolumeIsoSurface = {
     show_faces: OptionalField(bool, true, 'Show mesh faces. Defaults to true.'),
 };
 
+const VolumeGridSlice = {
+    /** Dimension of the grid slice, i.e. 'x', 'y', or 'z'. */
+    dimension: RequiredField(literal('x', 'y', 'z'), 'Dimension of the grid slice, i.e. \'x\', \'y\', or \'z\'.'),
+    /** Index of the grid slice in the specified dimension. 0-based index, i.e. 0 is the first slice. */
+    absolute_index: OptionalField(nullable(int), null, 'Index of the grid slice in the specified dimension. 0-based index, i.e. 0 is the first slice.'),
+    /** Relative index of the grid slice in the specified dimension. 0.0 is the first slice, 1.0 is the last slice. Overrides `absolute_index`. */
+    relative_index: OptionalField(nullable(float), null, 'Relative index of the grid slice in the specified dimension. 0.0 is the first slice, 1.0 is the last slice. Overrides `absolute_index`.'),
+    /** Relative isovalue. */
+    relative_isovalue: OptionalField(nullable(float), null, 'Relative isovalue.'),
+    /** Absolute isovalue. Overrides `relative_isovalue`. */
+    absolute_isovalue: OptionalField(nullable(float), null, 'Absolute isovalue. Overrides `relative_isovalue`.'),
+};
+
 export const MVSVolumeRepresentationParams = UnionParamsSchema(
     'type',
     'Representation type',
     {
         'isosurface': SimpleParamsSchema(VolumeIsoSurface),
+        'grid_slice': SimpleParamsSchema(VolumeGridSlice),
+    },
+);
+
+const ClipParamsBase = {
+    /** Transformation matrix to applied to each point before clipping. For example, can be used to clip volumes in the grid/fractional space. Default is null. */
+    check_transform: OptionalField(nullable(Matrix), null, 'Transformation matrix to applied to each point before clipping. For example, can be used to clip volumes in the grid/fractional space. Default is null.'),
+    /** Inverts the clipping region. Default is false. */
+    invert: OptionalField(bool, false, 'Inverts the clipping region. Default is false'),
+    /** Variant of the clip node, either "object" or "pixel". */
+    variant: OptionalField(literal('object', 'pixel'), 'pixel', 'Variant of the clip node, either "object" or "pixel"'),
+};
+
+export const MVSClipParams = UnionParamsSchema(
+    'type',
+    'Clip type',
+    {
+        plane: SimpleParamsSchema({
+            ...ClipParamsBase,
+            /** Normal vector of the clipping plane. */
+            normal: RequiredField(Vector3, 'Normal vector of the clipping plane.'),
+            /** Point on the clipping plane. */
+            point: RequiredField(Vector3, 'Point on the clipping plane.'),
+        }),
+        sphere: SimpleParamsSchema({
+            ...ClipParamsBase,
+            /** Center of the clipping sphere. */
+            center: RequiredField(Vector3, 'Center of the clipping sphere.'),
+            /** Radius of the clipping sphere. */
+            radius: OptionalField(float, 1, 'Radius of the clipping sphere.'),
+        }),
+        box: SimpleParamsSchema({
+            ...ClipParamsBase,
+            /** Center of the clipping box. */
+            center: RequiredField(Vector3, 'Center of the clipping box.'),
+            /** Size of the clipping box. */
+            size: OptionalField(Vector3, [1, 1, 1], 'Size of the clipping box.'),
+            /** Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation). */
+            rotation: OptionalField(Matrix, [1, 0, 0, 0, 1, 0, 0, 0, 1], 'Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation).'),
+        }),
     },
 );

src/extensions/mvs/tree/mvs/mvs-tree.ts

@@ -5,12 +5,12 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import { float, int, list, literal, nullable, OptionalField, RequiredField, str, tuple, union } from '../generic/field-schema';
+import { bool, dict, float, int, list, literal, nullable, OptionalField, RequiredField, str, tuple, union } from '../generic/field-schema';
 import { SimpleParamsSchema } from '../generic/params-schema';
 import { NodeFor, ParamsOfKind, SubtreeOfKind, TreeFor, TreeSchema, TreeSchemaWithAllRequired } from '../generic/tree-schema';
-import { MVSRepresentationParams, MVSVolumeRepresentationParams } from './mvs-tree-representations';
+import { MVSClipParams, MVSRepresentationParams, MVSVolumeRepresentationParams } from './mvs-tree-representations';
 import { MVSPrimitiveParams } from './mvs-tree-primitives';
-import { ColorT, ComponentExpressionT, ComponentSelectorT, Matrix, ParseFormatT, SchemaFormatT, SchemaT, StrList, StructureTypeT, Vector3 } from './param-types';
+import { ColorT, ComponentExpressionT, ComponentSelectorT, Matrix, Palette, ParseFormatT, SchemaFormatT, SchemaT, StrList, StructureTypeT, Vector3 } from './param-types';
 
 
 const _DataFromUriParams = {
@@ -28,6 +28,8 @@ const _DataFromUriParams = {
     category_name: OptionalField(nullable(str), null, 'Name of the CIF category to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, the first category in the block is used.'),
     /** Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...). The default value is 'color'/'label'/'tooltip'/'component' depending on the node type */
     field_name: RequiredField(str, 'Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).'),
+    /** Optional remapping of annotation field names `{ standardName1: actualName1, ... }`. Use `{ "label_asym_id": "X" }` to load actual field "X" as "label_asym_id". Use `{ "label_asym_id": null }` to ignore actual field "label_asym_id". Fields not mentioned here are mapped implicitely (i.e. actual name = standard name). */
+    field_remapping: OptionalField(dict(str, nullable(str)), {}, 'Optional remapping of annotation field names `{ standardName1: actualName1, ... }`. Use `{ "label_asym_id": "X" }` to load actual field "X" as "label_asym_id". Use `{ "label_asym_id": null }` to ignore actual field "label_asym_id". Fields not mentioned here are mapped implicitely (i.e. actual name = standard name).'),
 };
 
 const _DataFromSourceParams = {
@@ -41,11 +43,26 @@ const _DataFromSourceParams = {
     category_name: OptionalField(nullable(str), null, 'Name of the CIF category to read annotation from. If `null`, the first category in the block is used.'),
     /** Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...). The default value is 'color'/'label'/'tooltip'/'component' depending on the node type */
     field_name: RequiredField(str, 'Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).'),
+    /** Optional remapping of annotation field names `{ standardName1: actualName1, ... }`. Use `{ "label_asym_id": "X" }` to load actual field "X" as "label_asym_id". Use `{ "label_asym_id": null }` to ignore actual field "label_asym_id". Fields not mentioned here are mapped implicitely (i.e. actual name = standard name). */
+    field_remapping: OptionalField(dict(str, nullable(str)), {}, 'Optional remapping of annotation field names `{ standardName1: actualName1, ... }`. Use `{ "label_asym_id": "X" }` to load actual field "X" as "label_asym_id". Use `{ "label_asym_id": null }` to ignore actual field "label_asym_id". Fields not mentioned here are mapped implicitely (i.e. actual name = standard name).'),
 };
 
 /** Color to be used e.g. for representations without 'color' node */
 export const DefaultColor = 'white';
 
+const LabelAttachments = literal('bottom-left', 'bottom-center', 'bottom-right', 'middle-left', 'middle-center', 'middle-right', 'top-left', 'top-center', 'top-right');
+
+const TransformParams = SimpleParamsSchema({
+    /** Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation). */
+    rotation: OptionalField(Matrix, [1, 0, 0, 0, 1, 0, 0, 0, 1], 'Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation).'),
+    /** Translation vector, applied to the structure coordinates after rotation. The default value is the zero vector (corresponds to no translation). */
+    translation: OptionalField(Vector3, [0, 0, 0], 'Translation vector, applied to the structure coordinates after rotation. The default value is the zero vector (corresponds to no translation).'),
+    /** Point to rotate the object around. Can be either a 3D vector or dynamically computed object centroid. */
+    rotation_center: OptionalField(nullable(union(Vector3, literal('centroid'))), null, 'Point to rotate the object around. Can be either a 3D vector or dynamically computed object centroid.'),
+    /** Transform matrix (4x4 matrix flattened in column major format (j*4+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. Takes precedence over `rotation` and `translation`. */
+    matrix: OptionalField(nullable(Matrix), null, 'Transform matrix (4x4 matrix flattened in column major format (j*4+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. Takes precedence over `rotation` and `translation`.'),
+});
+
 /** Schema for `MVSTree` (MolViewSpec tree) */
 export const MVSTreeSchema = TreeSchema({
     rootKind: 'root',
@@ -75,6 +92,12 @@ export const MVSTreeSchema = TreeSchema({
                 format: RequiredField(ParseFormatT, 'Format of the input data resource.'),
             }),
         },
+        /** This node instructs to retrieve molecular coordinates from a parsed data resource. */
+        coordinates: {
+            description: 'This node instructs to retrieve molecular coordinates from a parsed data resource.',
+            parent: ['parse'],
+            params: SimpleParamsSchema({}),
+        },
         /** This node instructs to create a structure from a parsed data resource. "Structure" refers to an internal representation of molecular coordinates without any visual representation. */
         structure: {
             description: 'This node instructs to create a structure from a parsed data resource. "Structure" refers to an internal representation of molecular coordinates without any visual representation.',
@@ -96,18 +119,21 @@ export const MVSTreeSchema = TreeSchema({
                 ijk_min: OptionalField(tuple([int, int, int]), [-1, -1, -1], 'Miller indices of the bottom-left unit cell to be included (only applies when `kind` is `"symmetry"`).'),
                 /** Miller indices of the top-right unit cell to be included (only applies when `kind` is `"symmetry"`). */
                 ijk_max: OptionalField(tuple([int, int, int]), [1, 1, 1], 'Miller indices of the top-right unit cell to be included (only applies when `kind` is `"symmetry"`).'),
+                /** Reference to a specific set of coordinates. */
+                coordinates_ref: OptionalField(nullable(str), null, 'Reference to a specific set of coordinates.')
             }),
         },
         /** This node instructs to rotate and/or translate structure coordinates. */
         transform: {
-            description: 'This node instructs to rotate and/or translate structure coordinates.',
-            parent: ['structure'],
-            params: SimpleParamsSchema({
-                /** Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation). */
-                rotation: OptionalField(Matrix, [1, 0, 0, 0, 1, 0, 0, 0, 1], 'Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation).'),
-                /** Translation vector, applied to the structure coordinates after rotation. The default value is the zero vector (corresponds to no translation). */
-                translation: OptionalField(Vector3, [0, 0, 0], 'Translation vector, applied to the structure coordinates after rotation. The default value is the zero vector (corresponds to no translation).'),
-            }),
+            description: 'This node instructs to rotate and/or translate coordinates OR provide a transformation matrix.',
+            parent: ['structure', 'component', 'volume'],
+            params: TransformParams,
+        },
+        /** This node allows instantiation using the provided transformation parameters. */
+        instance: {
+            description: 'This node allows instantiation using the provided transformation parameters.',
+            parent: ['structure', 'component', 'volume'],
+            params: TransformParams,
         },
         /** This node instructs to create a component (i.e. a subset of the parent structure). */
         component: {
@@ -115,7 +141,7 @@ export const MVSTreeSchema = TreeSchema({
             parent: ['structure'],
             params: SimpleParamsSchema({
                 /** Defines what part of the parent structure should be included in this component. */
-                selector: RequiredField(union([ComponentSelectorT, ComponentExpressionT, list(ComponentExpressionT)]), 'Defines what part of the parent structure should be included in this component.'),
+                selector: RequiredField(union(ComponentSelectorT, ComponentExpressionT, list(ComponentExpressionT)), 'Defines what part of the parent structure should be included in this component.'),
             }),
         },
         /** This node instructs to create a component defined by an external annotation resource. */
@@ -170,7 +196,7 @@ export const MVSTreeSchema = TreeSchema({
                 /** Color to apply to the representation. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`). */
                 color: OptionalField(ColorT, DefaultColor, 'Color to apply to the representation. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`).'),
                 /** Defines to what part of the representation this color should be applied. */
-                selector: OptionalField(union([ComponentSelectorT, ComponentExpressionT, list(ComponentExpressionT)]), 'all', 'Defines to what part of the representation this color should be applied.'),
+                selector: OptionalField(union(ComponentSelectorT, ComponentExpressionT, list(ComponentExpressionT)), 'all', 'Defines to what part of the representation this color should be applied.'),
             }),
         },
         /** This node instructs to apply colors to a visual representation. The colors are defined by an external annotation resource. */
@@ -181,6 +207,8 @@ export const MVSTreeSchema = TreeSchema({
                 ..._DataFromUriParams,
                 /** Name of the column in CIF or field name (key) in JSON that contains the color. */
                 field_name: OptionalField(str, 'color', 'Name of the column in CIF or field name (key) in JSON that contains the color.'),
+                /** Customize mapping of annotation values to colors. */
+                palette: OptionalField(nullable(Palette), null, 'Customize mapping of annotation values to colors.'),
             }),
         },
         /** This node instructs to apply colors to a visual representation. The colors are defined by an annotation resource included in the same file this structure was loaded from. Only applicable if the structure was loaded from an mmCIF or BinaryCIF file. */
@@ -191,8 +219,16 @@ export const MVSTreeSchema = TreeSchema({
                 ..._DataFromSourceParams,
                 /** Name of the column in CIF or field name (key) in JSON that contains the color. */
                 field_name: OptionalField(str, 'color', 'Name of the column in CIF or field name (key) in JSON that contains the color.'),
+                /** Customize mapping of annotation values to colors. */
+                palette: OptionalField(nullable(Palette), null, 'Customize mapping of annotation values to colors.'),
             }),
         },
+        /** This node instructs to apply clipping to a visual representation. */
+        clip: {
+            description: 'This node instructs to apply clipping to a visual representation.',
+            parent: ['representation', 'volume_representation'],
+            params: MVSClipParams,
+        },
         /** This node instructs to apply opacity/transparency to a visual representation. */
         opacity: {
             description: 'This node instructs to apply opacity/transparency to a visual representation.',
@@ -296,7 +332,7 @@ export const MVSTreeSchema = TreeSchema({
             parent: ['root'],
             params: SimpleParamsSchema({
                 /** Color of the canvas background. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`). */
-                background_color: RequiredField(ColorT, 'Color of the canvas background. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`).'),
+                background_color: OptionalField(ColorT, 'white', 'Color of the canvas background. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`). Defaults to white.'),
             }),
         },
         primitives: {
@@ -313,6 +349,16 @@ export const MVSTreeSchema = TreeSchema({
                 opacity: OptionalField(float, 1, 'Opacity of primitive geometry in this group.'),
                 /** Opacity of primitive labels in this group. */
                 label_opacity: OptionalField(float, 1, 'Opacity of primitive labels in this group.'),
+                /** Whether to show a tether line between the label and the target. Defaults to false. */
+                label_show_tether: OptionalField(bool, false, 'Whether to show a tether line between the label and the target. Defaults to false.'),
+                /** Length of the tether line between the label and the target. Defaults to 1 (Angstrom). */
+                label_tether_length: OptionalField(float, 1, 'Length of the tether line between the label and the target. Defaults to 1 (Angstrom).'),
+                /** How to attach the label to the target. Defaults to "middle-center". */
+                label_attachment: OptionalField(LabelAttachments, 'middle-center', 'How to attach the label to the target. Defaults to "middle-center".'),
+                /** Background color of the label. Defaults to none/transparent. */
+                label_background_color: OptionalField(nullable(ColorT), null, 'Background color of the label. Defaults to none/transparent.'),
+                /** Load snapshot with the provided key when interacting with this primitives group. */
+                snapshot_key: OptionalField(nullable(str), null, 'Load snapshot with the provided key when interacting with this primitives group.'),
                 /** Instances of this primitive group defined as 4x4 column major (j * 4 + i indexing) transformation matrices. */
                 instances: OptionalField(nullable(list(Matrix)), null, 'Instances of this primitive group defined as 4x4 column major (j * 4 + i indexing) transformation matrices.'),
             }),

src/extensions/mvs/tree/mvs/param-types.ts

@@ -6,17 +6,47 @@
  */
 
 import * as iots from 'io-ts';
-import { HexColor, ColorName } from '../../helpers/utils';
-import { ValueFor, float, int, list, literal, str, tuple, union } from '../generic/field-schema';
-import { ColorNames } from '../../../../mol-util/color/names';
+import { ColorName, HexColor } from '../../helpers/utils';
+import { ValueFor, bool, dict, float, int, list, literal, nullable, object, partial, str, tuple, union } from '../generic/field-schema';
 
 
 /** `format` parameter values for `parse` node in MVS tree */
-export const ParseFormatT = literal('mmcif', 'bcif', 'pdb', 'map');
+export const ParseFormatT = literal(
+    // trajectory
+    'mmcif',
+    'bcif', // +volumes
+    'pdb',
+    'pdbqt',
+    'gro',
+    'xyz',
+    'mol',
+    'sdf',
+    'mol2',
+    'lammpstrj', // + coordinates
+    // coordinates
+    'xtc',
+    // volumes
+    'map',
+);
 export type ParseFormatT = ValueFor<typeof ParseFormatT>
 
 /** `format` parameter values for `parse` node in Molstar tree */
-export const MolstarParseFormatT = literal('cif', 'pdb', 'map');
+export const MolstarParseFormatT = literal(
+    // trajectory
+    'cif', // +volumes
+    'pdb',
+    'pdbqt',
+    'gro',
+    'xyz',
+    'mol',
+    'sdf',
+    'mol2',
+    'lammpstrj',
+    // coordinates
+    'xtc',
+    // volumes
+    'map'
+);
 export type MolstarParseFormatT = ValueFor<typeof MolstarParseFormatT>
 
 /** `kind` parameter values for `structure` node in MVS tree */
@@ -26,7 +56,7 @@ export const StructureTypeT = literal('model', 'assembly', 'symmetry', 'symmetry
 export const ComponentSelectorT = literal('all', 'polymer', 'protein', 'nucleic', 'branched', 'ligand', 'ion', 'water', 'coarse');
 
 /** `selector` parameter values for `component` node in MVS tree */
-export const ComponentExpressionT = iots.partial({
+export const ComponentExpressionT = partial({
     label_entity_id: str,
     label_asym_id: str,
     auth_asym_id: str,
@@ -37,11 +67,17 @@ export const ComponentExpressionT = iots.partial({
     end_label_seq_id: int,
     beg_auth_seq_id: int,
     end_auth_seq_id: int,
+    label_comp_id: str,
+    auth_comp_id: str,
+    // residue_index: int, // 0-based residue index in the source file // TODO this is defined in Python builder but not supported by Molstar yet
     label_atom_id: str,
     auth_atom_id: str,
     type_symbol: str,
     atom_id: int,
     atom_index: int,
+    /** Instance identifier to distinguish instances of the same chain created by applying different symmetry operators,
+     * like 'ASM-X0-1' for assemblies or '1_555' for crystals */
+    instance_id: str,
 });
 export type ComponentExpressionT = ValueFor<typeof ComponentExpressionT>
 
@@ -59,9 +95,9 @@ export type Vector3 = ValueFor<typeof Vector3>
 export const Matrix = list(float);
 
 /** Primitives-related types */
-export const PrimitiveComponentExpressionT = iots.partial({ structure_ref: str, expression_schema: SchemaT, expressions: list(ComponentExpressionT) });
+export const PrimitiveComponentExpressionT = partial({ structure_ref: str, expression_schema: SchemaT, expressions: list(ComponentExpressionT) });
 export type PrimitiveComponentExpressionT = ValueFor<typeof PrimitiveComponentExpressionT>
-export const PrimitivePositionT = iots.union([Vector3, ComponentExpressionT, PrimitiveComponentExpressionT]);
+export const PrimitivePositionT = union(Vector3, ComponentExpressionT, PrimitiveComponentExpressionT);
 export type PrimitivePositionT = ValueFor<typeof PrimitivePositionT>
 
 export const FloatList = list(float);
@@ -81,15 +117,12 @@ export const HexColorT = new iots.Type<HexColor>(
 export const ColorNameT = new iots.Type<ColorName>(
     'ColorName',
     ((value: any) => typeof value === 'string') as any,
-    (value, ctx) => ColorName.is(value) ? { _tag: 'Right', right: value } : { _tag: 'Left', left: [{ value: value, context: ctx, message: `"${value}" is not a valid hex color string` }] },
+    (value, ctx) => ColorName.is(value) ? { _tag: 'Right', right: value } : { _tag: 'Left', left: [{ value: value, context: ctx, message: `"${value}" is not a valid color name` }] },
     value => value
 );
 
 /** `color` parameter values for `color` node in MVS tree */
-export const ColorNamesT = literal(...Object.keys(ColorNames) as (keyof ColorNames)[]);
-
-/** `color` parameter values for `color` node in MVS tree */
-export const ColorT = union([ColorNameT, HexColorT]);
+export const ColorT = union(ColorNameT, HexColorT);
 export type ColorT = ValueFor<typeof ColorT>
 
 /** Type helpers */
@@ -104,3 +137,146 @@ export function isPrimitiveComponentExpressions(x: any): x is PrimitiveComponent
 export function isComponentExpression(x: any): x is ComponentExpressionT {
     return !!x && typeof x === 'object' && !x.expressions;
 }
+
+
+export const ColorListNameT = literal(
+    // Color lists from https://observablehq.com/@d3/color-schemes (definitions: https://colorbrewer2.org/export/colorbrewer.js)
+    // Sequential single-hue
+    'Reds', 'Oranges', 'Greens', 'Blues', 'Purples', 'Greys',
+    // Sequential multi-hue
+    'OrRd', 'BuGn', 'PuBuGn', 'GnBu', 'PuBu', 'BuPu', 'RdPu', 'PuRd', 'YlOrRd', 'YlOrBr', 'YlGn', 'YlGnBu',
+    'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Turbo', 'Warm', 'Cool', 'CubehelixDefault',
+    // Cyclical
+    'Rainbow', 'Sinebow',
+    // Diverging
+    'RdBu', 'RdGy', 'PiYG', 'BrBG', 'PRGn', 'PuOr', 'RdYlGn', 'RdYlBu', 'Spectral',
+    // Categorical
+    'Category10', 'Observable10', 'Tableau10',
+    'Set1', 'Set2', 'Set3', 'Pastel1', 'Pastel2', 'Dark2', 'Paired', 'Accent',
+
+    // Additional lists, not standard for visualization in general, but commonly used for structures
+    'Chainbow',
+);
+export type ColorListNameT = ValueFor<typeof ColorListNameT>;
+
+export const ColorDictNameT = literal('ElementSymbol', 'ResidueName', 'ResidueProperties', 'SecondaryStructure');
+export type ColorDictNameT = ValueFor<typeof ColorDictNameT>;
+
+
+export const CategoricalPalette = object(
+    {
+        kind: literal('categorical'),
+    },
+    // Optionals:
+    {
+        colors: union(
+            ColorListNameT,
+            ColorDictNameT,
+            list(ColorT),
+            dict(str, ColorT),
+        ),
+        /** Repeat color list once all colors are depleted (only applies if `colors` is a list or a color list name). */
+        repeat_color_list: bool,
+        /** Sort actual annotation values before assigning colors from a list (none = take values in order of their first occurrence). */
+        sort: literal('none', 'lexical', 'numeric'),
+        /** Sort direction. */
+        sort_direction: literal('ascending', 'descending'),
+        /** Treat annotation values as case-insensitive strings. */
+        case_insensitive: bool,
+        /** Color to use when a) `colors` is a dictionary (or a color dictionary name) and given key is not present, or b) `colors` is a list (or a color list name) and there are more actual annotation values than listed colors and `repeat_color_list` is not true. */
+        missing_color: nullable(ColorT),
+    }
+);
+export type CategoricalPalette = ValueFor<typeof CategoricalPalette>;
+
+export const CategoricalPaletteDefaults: Required<CategoricalPalette> = {
+    kind: 'categorical',
+    colors: 'Category10', // this is also default for categorical in Matplotlib
+    repeat_color_list: false,
+    sort: 'none',
+    sort_direction: 'ascending',
+    case_insensitive: false,
+    missing_color: null,
+};
+
+
+export const DiscretePalette = object(
+    {
+        kind: literal('discrete'),
+    },
+    // Optionals:
+    {
+        /** Define colors for the discrete color palette and optionally corresponding checkpoints.
+         * Checkpoints refer to the values normalized to interval [0, 1] if `mode` is `"normalized"` (default), or to the values directly if `mode` is `"absolute"`.
+         * If checkpoints are not provided, they will created automatically (uniformly distributed over interval [0, 1]).
+         * If 1 checkpoint is provided for each color, then the color applies to values from this checkpoint (inclusive) until the next listed checkpoint (exclusive); the last color applies until Infinity.
+         * If 2 checkpoints are provided for each color, then the color applies to values from the first until the second checkpoint (inclusive); null means +/-Infinity; if ranges overlap, the later listed takes precedence.
+         */
+        colors: union(
+            ColorListNameT,
+            list(ColorT),
+            list(tuple([ColorT, float])),
+            list(tuple([nullable(ColorT), nullable(float), nullable(float)])),
+        ),
+        /** Reverse order of `colors` list. Only has effect when `colors` is a color list name or a color list without explicit checkpoints. */
+        reverse: bool,
+        /** Defines whether the annotation values should be normalized before assigning color based on checkpoints in `colors` (`x_normalized = (x - x_min) / (x_max - x_min)`, where `[x_min, x_max]` are either `value_domain` if provided, or the lowest and the highest value encountered in the annotation). Default is `"normalized"`. */
+        mode: literal('normalized', 'absolute'),
+        /** Defines `x_min` and `x_max` for normalization of annotation values. Either can be `null`, meaning that minimum/maximum of the actual values will be used. Only used when `mode` is `"normalized"`. */
+        value_domain: tuple([nullable(float), nullable(float)]),
+    }
+);
+export type DiscretePalette = ValueFor<typeof DiscretePalette>;
+
+export const DiscretePaletteDefaults: Required<DiscretePalette> = {
+    kind: 'discrete',
+    colors: 'YlGn', // YlGn was selected as default because (a) Matplotlib's default Viridis looks ugly in 3D and (b) YlGn does not contain white, so it's easier to see that it's doing something even when values are in wrong range
+    reverse: false,
+    mode: 'normalized',
+    value_domain: [null, null],
+};
+
+
+export const ContinuousPalette = object(
+    {
+        kind: literal('continuous'),
+
+    },
+    // Optionals:
+    {
+        /** Define colors for the continuous color palette and optionally corresponding checkpoints (i.e. annotation values that are mapped to each color).
+         * Checkpoints refer to the values normalized to interval [0, 1] if `mode` is `"normalized"` (default), or to the values directly if `mode` is `"absolute"`.
+         * If checkpoints are not provided, they will created automatically (uniformly distributed over interval [0, 1]). */
+        colors: union(
+            ColorListNameT,
+            list(ColorT),
+            list(tuple([ColorT, float])),
+        ),
+        /** Reverse order of `colors` list. Only has effect when `colors` is a color list name or a color list without explicit checkpoints. */
+        reverse: bool,
+        /** Defines whether the annotation values should be normalized before assigning color based on checkpoints in `colors` (`x_normalized = (x - x_min) / (x_max - x_min)`, where `[x_min, x_max]` are either `value_domain` if provided, or the lowest and the highest value encountered in the annotation). Default is `"normalized"`. */
+        mode: literal('normalized', 'absolute'),
+        /** Defines `x_min` and `x_max` for normalization of annotation values. Either can be `null`, meaning that minimum/maximum of the actual values will be used. Only used when `mode` is `"normalized"`. */
+        value_domain: tuple([nullable(float), nullable(float)]),
+        /** Color to use for values below the lowest checkpoint. 'auto' means color of the lowest checkpoint. */
+        underflow_color: nullable(union(literal('auto'), ColorT)),
+        /** Color to use for values above the highest checkpoint. 'auto' means color of the highest checkpoint. */
+        overflow_color: nullable(union(literal('auto'), ColorT)),
+    }
+);
+export type ContinuousPalette = ValueFor<typeof ContinuousPalette>;
+
+export const ContinuousPaletteDefaults: Required<ContinuousPalette> = {
+    kind: 'continuous',
+    colors: 'YlGn', // YlGn was selected as default because (a) Matplotlib's default Viridis looks ugly in 3D and (b) YlGn does not contain white, so it's easier to see that it's doing something even when values are in wrong range
+    reverse: false,
+    mode: 'normalized',
+    value_domain: [null, null],
+    underflow_color: null,
+    overflow_color: null,
+};
+
+// TODO consider spreading the palette param directly into color_from_uri/color_from_source params (though this will be tricky)
+// TODO consider implementing some kind of recursion for object-typed params to achieve smart error messages and default value handling
+
+export const Palette = union(CategoricalPalette, DiscretePalette, ContinuousPalette);

src/extensions/volumes-and-segmentations/entry-root.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -34,6 +34,7 @@ import { VolsegGlobalStateData } from './global-state';
 import { applyEllipsis, isDefined, lazyGetter, splitEntryId } from './helpers';
 import { type VolsegStateFromEntry } from './transformers';
 import { StateTransforms } from '../../mol-plugin-state/transforms';
+import { OrderedSet } from '../../mol-data/int';
 
 
 export const MAX_VOXELS = 10 ** 7;
@@ -346,8 +347,8 @@ export class VolsegEntryData extends PluginBehavior.WithSubscribers<VolsegEntryP
 
     private getSegmentIdFromLoci(loci: Loci): number | undefined {
         if (Volume.Segment.isLoci(loci) && loci.volume._propertyData.ownerId === this.ref) {
-            if (loci.segments.length === 1) {
-                return loci.segments[0];
+            if (loci.elements.length === 1 && OrderedSet.size(loci.elements[0].segments) === 1) {
+                return OrderedSet.start(loci.elements[0].segments);
             }
         }
         if (ShapeGroup.isLoci(loci)) {

src/extensions/volumes-and-segmentations/entry-segmentation.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  */
@@ -17,6 +17,8 @@ import { Segment } from './volseg-api/data';
 import { BOX, VolsegEntryData, MAX_VOXELS } from './entry-root';
 import { VolumeVisualParams } from './entry-volume';
 import { VolsegGlobalStateData } from './global-state';
+import { Interval } from '../../mol-data/int/interval';
+import { SortedArray } from '../../mol-data/int';
 
 
 const GROUP_TAG = 'lattice-segmentation-group';
@@ -89,7 +91,11 @@ export class VolsegLatticeSegmentationData {
         const repr = vis.obj?.data.repr;
         const wholeLoci = repr.getAllLoci()[0];
         if (!wholeLoci || !Volume.Segment.isLoci(wholeLoci)) return undefined;
-        return { loci: Volume.Segment.Loci(wholeLoci.volume, segments), repr: repr };
+        const elements = [{
+            segments: SortedArray.ofUnsortedArray<Volume.SegmentIndex>(segments),
+            instances: Interval.ofLength(wholeLoci.volume.instances.length as Volume.InstanceIndex)
+        }];
+        return { loci: Volume.Segment.Loci(wholeLoci.volume, elements), repr: repr };
     }
     async highlightSegment(segment: Segment) {
         const segmentLoci = this.makeLoci([segment.id]);

src/mol-canvas3d/camera.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -11,8 +11,9 @@ import { CameraTransitionManager } from './camera/transition';
 import { BehaviorSubject } from 'rxjs';
 import { Scene } from '../mol-gl/scene';
 import { assertUnreachable } from '../mol-util/type-helpers';
+import { Ray3D } from '../mol-math/geometry/primitives/ray3d';
 
-export { ICamera, Camera };
+export type { ICamera };
 
 interface ICamera {
     readonly viewport: Viewport,
@@ -26,15 +27,17 @@ interface ICamera {
     readonly near: number,
     readonly fogFar: number,
     readonly fogNear: number,
+    readonly headRotation: Mat4,
 }
 
 const tmpClip = Vec4();
 
-class Camera implements ICamera {
+export class Camera implements ICamera {
     readonly view: Mat4 = Mat4.identity();
     readonly projection: Mat4 = Mat4.identity();
     readonly projectionView: Mat4 = Mat4.identity();
     readonly inverseProjectionView: Mat4 = Mat4.identity();
+    readonly headRotation: Mat4 = Mat4.zero();
 
     readonly viewport: Viewport;
     readonly state: Readonly<Camera.Snapshot> = Camera.createDefaultSnapshot();
@@ -69,7 +72,7 @@ class Camera implements ICamera {
             return false;
         }
 
-        const height = 2 * Math.tan(snapshot.fov / 2) * Vec3.distance(snapshot.position, snapshot.target);
+        const height = 2 * Math.tan(snapshot.fov / 2) * Vec3.distance(snapshot.position, snapshot.target) * this.state.scale;
         this.zoom = this.viewport.height / height;
 
         updateClip(this);
@@ -191,13 +194,29 @@ class Camera implements ICamera {
         return (2 / w) / (rx * Math.abs(P00));
     }
 
+    getRay(out: Ray3D, x: number, y: number) {
+        if (this.state.mode === 'orthographic') {
+            Vec3.set(out.origin, x, y, 0);
+            this.unproject(out.origin, out.origin);
+            Vec3.normalize(out.direction, Vec3.sub(out.direction, this.target, this.position));
+            Vec3.scaleAndAdd(out.origin, out.origin, out.direction, -this.near);
+        } else {
+            Vec3.copy(out.origin, this.state.position);
+            Vec3.scale(out.origin, out.origin, this.state.scale);
+            Vec3.set(out.direction, x, y, 0.5);
+            this.unproject(out.direction, out.direction);
+            Vec3.normalize(out.direction, Vec3.sub(out.direction, out.direction, out.origin));
+        }
+        return out;
+    }
+
     constructor(state?: Partial<Camera.Snapshot>, viewport = Viewport.create(0, 0, 128, 128)) {
         this.viewport = viewport;
         Camera.copySnapshot(this.state, state);
     }
 }
 
-namespace Camera {
+export namespace Camera {
     export type Mode = 'perspective' | 'orthographic'
 
     export type SnapshotProvider = Partial<Snapshot> | ((scene: Scene, camera: Camera) => Partial<Snapshot>)
@@ -270,6 +289,8 @@ namespace Camera {
             clipFar: true,
             minNear: 5,
             minFar: 0,
+
+            scale: 1,
         };
     }
 
@@ -287,6 +308,8 @@ namespace Camera {
         clipFar: boolean
         minNear: number
         minFar: number
+
+        scale: number
     }
 
     export function copySnapshot(out: Snapshot, source?: Partial<Snapshot>) {
@@ -306,6 +329,8 @@ namespace Camera {
         if (typeof source.minNear !== 'undefined') out.minNear = source.minNear;
         if (typeof source.minFar !== 'undefined') out.minFar = source.minFar;
 
+        if (typeof source.scale !== 'undefined') out.scale = source.scale;
+
         return out;
     }
 
@@ -318,12 +343,26 @@ namespace Camera {
             && a.clipFar === b.clipFar
             && a.minNear === b.minNear
             && a.minFar === b.minFar
+            && a.scale === b.scale
             && Vec3.exactEquals(a.position, b.position)
             && Vec3.exactEquals(a.up, b.up)
             && Vec3.exactEquals(a.target, b.target);
     }
 }
 
+const tmpPosition = Vec3();
+const tmpTarget = Vec3();
+
+function updateView(camera: Camera) {
+    if (camera.state.scale === 1) {
+        Mat4.lookAt(camera.view, camera.state.position, camera.state.target, camera.state.up);
+    } else {
+        Vec3.scale(tmpPosition, camera.state.position, camera.state.scale);
+        Vec3.scale(tmpTarget, camera.state.target, camera.state.scale);
+        Mat4.lookAt(camera.view, tmpPosition, tmpTarget, camera.state.up);
+    }
+}
+
 function updateOrtho(camera: Camera) {
     const { viewport, zoom, near, far, viewOffset } = camera;
 
@@ -357,7 +396,7 @@ function updateOrtho(camera: Camera) {
     Mat4.ortho(camera.projection, left, right, top, bottom, near, far);
 
     // build view matrix
-    Mat4.lookAt(camera.view, camera.position, camera.target, camera.up);
+    updateView(camera);
 }
 
 function updatePers(camera: Camera) {
@@ -381,15 +420,23 @@ function updatePers(camera: Camera) {
     Mat4.perspective(camera.projection, left, left + width, top, top - height, near, far);
 
     // build view matrix
-    Mat4.lookAt(camera.view, camera.position, camera.target, camera.up);
+    updateView(camera);
 }
 
 function updateClip(camera: Camera) {
-    let { radius, radiusMax, mode, fog, clipFar, minNear, minFar } = camera.state;
-    if (radius < 0.01) radius = 0.01;
+    let { radius, radiusMax, mode, fog, clipFar, minNear, minFar, scale } = camera.state;
+    radiusMax *= scale;
+    minFar *= scale;
+    minNear *= scale;
+    radius *= scale;
+
+    const minRadius = 0.01 * scale;
+    if (radius < minRadius) radius = minRadius;
 
     const normalizedFar = Math.max(clipFar ? radius : radiusMax, minFar);
-    const cameraDistance = Vec3.distance(camera.position, camera.target);
+    Vec3.scale(tmpTarget, camera.state.target, scale);
+    Vec3.scale(tmpPosition, camera.state.position, scale);
+    const cameraDistance = Vec3.distance(tmpPosition, tmpTarget);
     let near = cameraDistance - radius;
     let far = cameraDistance + normalizedFar;
 
@@ -405,7 +452,7 @@ function updateClip(camera: Camera) {
 
     if (near === far) {
         // make sure near and far are not identical to avoid Infinity in the projection matrix
-        far = near + 0.01;
+        far = near + 0.01 * scale;
     }
 
     const fogNearFactor = -(50 - fog) / 50;

src/mol-canvas3d/camera/stereo.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -61,6 +61,7 @@ class EyeCamera implements ICamera {
     projection = Mat4();
     projectionView = Mat4();
     inverseProjectionView = Mat4();
+    headRotation = Mat4();
     state: Readonly<Camera.Snapshot> = Camera.createDefaultSnapshot();
     viewOffset: Readonly<Camera.ViewOffset> = Camera.ViewOffset();
     far: number = 0;
@@ -69,30 +70,29 @@ class EyeCamera implements ICamera {
     fogNear: number = 0;
 }
 
-const eyeLeft = Mat4.identity(), eyeRight = Mat4.identity();
+const tmpEyeLeft = Mat4.identity();
+const tmpEyeRight = Mat4.identity();
+
+function copyStates(parent: Camera, eye: EyeCamera) {
+    Viewport.copy(eye.viewport, parent.viewport);
+    Mat4.copy(eye.view, parent.view);
+    Mat4.copy(eye.projection, parent.projection);
+    Mat4.copy(eye.headRotation, parent.headRotation);
+    Camera.copySnapshot(eye.state, parent.state);
+    Camera.copyViewOffset(eye.viewOffset, parent.viewOffset);
+    eye.far = parent.far;
+    eye.near = parent.near;
+    eye.fogFar = parent.fogFar;
+    eye.fogNear = parent.fogNear;
+}
+
+//
 
 function update(camera: Camera, props: StereoCameraProps, left: EyeCamera, right: EyeCamera) {
     // Copy the states
 
-    Viewport.copy(left.viewport, camera.viewport);
-    Mat4.copy(left.view, camera.view);
-    Mat4.copy(left.projection, camera.projection);
-    Camera.copySnapshot(left.state, camera.state);
-    Camera.copyViewOffset(left.viewOffset, camera.viewOffset);
-    left.far = camera.far;
-    left.near = camera.near;
-    left.fogFar = camera.fogFar;
-    left.fogNear = camera.fogNear;
-
-    Viewport.copy(right.viewport, camera.viewport);
-    Mat4.copy(right.view, camera.view);
-    Mat4.copy(right.projection, camera.projection);
-    Camera.copySnapshot(right.state, camera.state);
-    Camera.copyViewOffset(right.viewOffset, camera.viewOffset);
-    right.far = camera.far;
-    right.near = camera.near;
-    right.fogFar = camera.fogFar;
-    right.fogNear = camera.fogNear;
+    copyStates(camera, left);
+    copyStates(camera, right);
 
     // update the view offsets
 
@@ -112,8 +112,8 @@ function update(camera: Camera, props: StereoCameraProps, left: EyeCamera, right
 
     // translate xOffset
 
-    eyeLeft[12] = -eyeSepHalf;
-    eyeRight[12] = eyeSepHalf;
+    tmpEyeLeft[12] = -eyeSepHalf;
+    tmpEyeRight[12] = eyeSepHalf;
 
     // for left eye
 
@@ -123,7 +123,7 @@ function update(camera: Camera, props: StereoCameraProps, left: EyeCamera, right
     left.projection[0] = 2 * camera.near / (xmax - xmin);
     left.projection[8] = (xmax + xmin) / (xmax - xmin);
 
-    Mat4.mul(left.view, left.view, eyeLeft);
+    Mat4.mul(left.view, left.view, tmpEyeLeft);
     Mat4.mul(left.projectionView, left.projection, left.view);
     Mat4.invert(left.inverseProjectionView, left.projectionView);
 
@@ -135,7 +135,7 @@ function update(camera: Camera, props: StereoCameraProps, left: EyeCamera, right
     right.projection[0] = 2 * camera.near / (xmax - xmin);
     right.projection[8] = (xmax + xmin) / (xmax - xmin);
 
-    Mat4.mul(right.view, right.view, eyeRight);
+    Mat4.mul(right.view, right.view, tmpEyeRight);
     Mat4.mul(right.projectionView, right.projection, right.view);
     Mat4.invert(right.inverseProjectionView, right.projectionView);
 }

src/mol-canvas3d/canvas3d.ts

@@ -13,7 +13,7 @@ import { Vec3, Vec2 } from '../mol-math/linear-algebra';
 import { InputObserver, ModifiersKeys, ButtonsType } from '../mol-util/input/input-observer';
 import { Renderer, RendererStats, RendererParams } from '../mol-gl/renderer';
 import { GraphicsRenderObject } from '../mol-gl/render-object';
-import { TrackballControls, TrackballControlsParams } from './controls/trackball';
+import { DefaultTrackballControlsAttribs, TrackballControls, TrackballControlsParams } from './controls/trackball';
 import { Viewport } from './camera/util';
 import { createContext, WebGLContext, getGLContext } from '../mol-gl/webgl/context';
 import { Representation } from '../mol-repr/representation';
@@ -28,13 +28,12 @@ import { SetUtils } from '../mol-util/set';
 import { Canvas3dInteractionHelper, Canvas3dInteractionHelperParams } from './helper/interaction-events';
 import { PostprocessingParams } from './passes/postprocessing';
 import { MultiSampleHelper, MultiSampleParams, MultiSamplePass } from './passes/multi-sample';
-import { PickData } from './passes/pick';
-import { PickHelper } from './passes/pick';
+import { AsyncPickData, DefaultPickOptions, PickData } from './passes/pick';
+import { PickHelper } from './helper/pick-helper';
 import { ImagePass, ImageProps } from './passes/image';
 import { Sphere3D } from '../mol-math/geometry';
 import { addConsoleStatsProvider, isDebugMode, isTimingMode, removeConsoleStatsProvider } from '../mol-util/debug';
 import { CameraHelperParams } from './helper/camera-helper';
-import { produce } from 'immer';
 import { HandleHelperParams } from './helper/handle-helper';
 import { StereoCamera, StereoCameraParams } from './camera/stereo';
 import { Helper } from './helper/helper';
@@ -47,7 +46,13 @@ import { deepClone } from '../mol-util/object';
 import { HiZParams, HiZPass } from './passes/hi-z';
 import { IlluminationParams } from './passes/illumination';
 import { isMobileBrowser } from '../mol-util/browser';
+import { Ray3D } from '../mol-math/geometry/primitives/ray3d';
+import { RayHelper } from './helper/ray-helper';
+import { produce } from '../mol-util/produce';
 
+export const CameraFogParams = {
+    intensity: PD.Numeric(15, { min: 1, max: 100, step: 1 }),
+};
 export const Canvas3DParams = {
     camera: PD.Group({
         mode: PD.Select('perspective', PD.arrayToOptions(['perspective', 'orthographic'] as const), { label: 'Camera' }),
@@ -57,12 +62,11 @@ export const Canvas3DParams = {
             off: PD.Group({})
         }, { cycle: true, hideIf: p => p?.mode !== 'perspective' }),
         fov: PD.Numeric(45, { min: 10, max: 130, step: 1 }, { label: 'Field of View' }),
+        scale: PD.Numeric(1, { min: 0.001, max: 1, step: 0.001 }, { label: 'Scene scale' }),
         manualReset: PD.Boolean(false, { isHidden: true }),
     }, { pivot: 'mode' }),
     cameraFog: PD.MappedStatic('on', {
-        on: PD.Group({
-            intensity: PD.Numeric(15, { min: 1, max: 100, step: 1 }),
-        }),
+        on: PD.Group(CameraFogParams),
         off: PD.Group({})
     }, { cycle: true, description: 'Show fog in the distance' }),
     cameraClipping: PD.Group({
@@ -110,6 +114,11 @@ export type PartialCanvas3DProps = {
     [K in keyof Canvas3DProps]?: Canvas3DProps[K] extends { name: string, params: any } ? Canvas3DProps[K] : Partial<Canvas3DProps[K]>
 }
 
+export const DefaultCanvas3DAttribs = {
+    trackball: DefaultTrackballControlsAttribs,
+};
+export type Canvas3DAttribs = typeof DefaultCanvas3DAttribs
+
 export { Canvas3DContext };
 
 /** Can be used to create multiple Canvas3D objects */
@@ -330,7 +339,8 @@ interface Canvas3D {
     pause(noDraw?: boolean): void
     /** Sets drawPaused = false without starting the built in animation loop */
     resume(): void
-    identify(x: number, y: number): PickData | undefined
+    identify(target: Vec2 | Ray3D): PickData | undefined
+    asyncIdentify(target: Vec2 | Ray3D): AsyncPickData | undefined
     mark(loci: Representation.Loci, action: MarkerAction): void
     getLoci(pickingId: PickingId | undefined): Representation.Loci
 
@@ -355,6 +365,7 @@ interface Canvas3D {
 
     /** Returns a copy of the current Canvas3D instance props */
     readonly props: Readonly<Canvas3DProps>
+    readonly attribs: Readonly<Canvas3DAttribs>
     readonly input: InputObserver
     readonly stats: RendererStats
     readonly interaction: Canvas3dInteractionHelper['events']
@@ -374,9 +385,10 @@ namespace Canvas3D {
     export interface DragEvent { current: Representation.Loci, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys, pageStart: Vec2, pageEnd: Vec2 }
     export interface ClickEvent { current: Representation.Loci, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys, page?: Vec2, position?: Vec3 }
 
-    export function create(ctx: Canvas3DContext, props: Partial<Canvas3DProps> = {}): Canvas3D {
+    export function create(ctx: Canvas3DContext, props: Partial<Canvas3DProps> = {}, attribs: Partial<Canvas3DAttribs> = {}): Canvas3D {
         const { webgl, input, passes, assetManager, canvas, contextLost } = ctx;
         const p: Canvas3DProps = { ...deepClone(DefaultCanvas3DParams), ...deepClone(props) };
+        const a = { ...deepClone(DefaultCanvas3DAttribs), ...deepClone(attribs) };
 
         const reprRenderObjects = new Map<Representation.Any, Set<GraphicsRenderObject>>();
         const reprUpdatedSubscriptions = new Map<Representation.Any, Subscription>();
@@ -388,7 +400,7 @@ namespace Canvas3D {
         const commited = new BehaviorSubject<now.Timestamp>(0 as now.Timestamp);
         const commitQueueSize = new BehaviorSubject<number>(0);
 
-        const { gl, contextRestored } = webgl;
+        const { contextRestored } = webgl;
 
         let x = 0;
         let y = 0;
@@ -412,18 +424,24 @@ namespace Canvas3D {
             clipFar: p.cameraClipping.far,
             minNear: p.cameraClipping.minNear,
             fov: degToRad(p.camera.fov),
+            scale: p.camera.scale,
         }, { x, y, width, height });
         const stereoCamera = new StereoCamera(camera, p.camera.stereo.params);
 
-        const controls = TrackballControls.create(input, camera, scene, p.trackball);
+        const controls = TrackballControls.create(input, camera, scene, p.trackball, a.trackball);
         const helper = new Helper(webgl, scene, p);
         const hiZ = new HiZPass(webgl, passes.draw, canvas, p.hiZ);
 
         const renderer = Renderer.create(webgl, p.renderer);
         renderer.setOcclusionTest(hiZ.isOccluded);
 
-        const pickHelper = new PickHelper(webgl, renderer, scene, helper, passes.pick, { x, y, width, height }, p.pickPadding);
-        const interactionHelper = new Canvas3dInteractionHelper(identify, getLoci, input, camera, controls, p.interaction);
+        const pickOptions = {
+            pickPadding: p.pickPadding,
+            maxAsyncReadLag: DefaultPickOptions.maxAsyncReadLag,
+        };
+        const pickHelper = new PickHelper(webgl, renderer, scene, helper, passes.pick, { x, y, width, height }, pickOptions);
+        const rayHelper = new RayHelper(webgl, renderer, scene, helper, pickOptions);
+        const interactionHelper = new Canvas3dInteractionHelper(identify, asyncIdentify, getLoci, input, camera, controls, p.interaction);
         const multiSampleHelper = new MultiSampleHelper(passes.multiSample);
 
         passes.draw.postprocessing.background.update(camera, p.postprocessing.background, changed => {
@@ -510,8 +528,9 @@ namespace Canvas3D {
                 resized = true;
             }
 
-            if (x > gl.drawingBufferWidth || x + width < 0 ||
-                y > gl.drawingBufferHeight || y + height < 0
+            const drs = webgl.getDrawingBufferSize();
+            if (x > drs.width || x + width < 0 ||
+                y > drs.height || y + height < 0
             ) return false;
 
             if (fenceSync !== null) {
@@ -648,9 +667,26 @@ namespace Canvas3D {
             animationFrameHandle = 0;
         }
 
-        function identify(x: number, y: number): PickData | undefined {
-            const cam = p.camera.stereo.name === 'on' ? stereoCamera : camera;
-            return webgl.isContextLost ? undefined : pickHelper.identify(x, y, cam);
+        function identify(target: Vec2 | Ray3D): PickData | undefined {
+            if (webgl.isContextLost) return undefined;
+
+            if ('origin' in target) {
+                return rayHelper.identify(target, camera);
+            } else {
+                const cam = (p.camera.stereo.name === 'on') ? stereoCamera : camera;
+                return pickHelper.identify(target[0], target[1], cam);
+            }
+        }
+
+        function asyncIdentify(target: Vec2 | Ray3D): AsyncPickData | undefined {
+            if (webgl.isContextLost) return undefined;
+
+            if ('origin' in target) {
+                return rayHelper.asyncIdentify(target, camera);
+            } else {
+                const cam = (p.camera.stereo.name === 'on') ? stereoCamera : camera;
+                return pickHelper.asyncIdentify(target[0], target[1], cam);
+            }
         }
 
         function commit(isSynchronous: boolean = false) {
@@ -840,6 +876,7 @@ namespace Canvas3D {
                     helper: { ...helper.camera.props },
                     stereo: { ...p.camera.stereo },
                     fov: Math.round(radToDeg(camera.state.fov)),
+                    scale: camera.state.scale,
                     manualReset: !!p.camera.manualReset
                 },
                 cameraFog: camera.state.fog > 0
@@ -874,6 +911,10 @@ namespace Canvas3D {
         });
 
         const contextRestoredSub = contextRestored.subscribe(() => {
+            pickHelper.reset();
+            rayHelper.reset();
+            hiZ.reset();
+
             scene.forEach(r => {
                 if (r.values.meta?.ref.value.reset) {
                     r.values.meta.ref.value.reset();
@@ -951,7 +992,7 @@ namespace Canvas3D {
             input.click.subscribe(e => {
                 if (!e.modifiers.control || e.button !== 2) return;
 
-                const p = identify(e.x, e.y);
+                const p = identify(Vec2.create(e.x, e.y));
                 if (!p) {
                     occlusionLoci = undefined;
                     printOcclusion(occlusionLoci);
@@ -1019,6 +1060,7 @@ namespace Canvas3D {
             pause,
             resume: () => { drawPaused = false; },
             identify,
+            asyncIdentify,
             mark,
             getLoci,
 
@@ -1059,6 +1101,9 @@ namespace Canvas3D {
                 if (props.camera && props.camera.fov !== undefined && props.camera.fov !== oldFov) {
                     cameraState.fov = degToRad(props.camera.fov);
                 }
+                if (props.camera && props.camera.scale !== undefined && props.camera.scale !== cameraState.scale) {
+                    cameraState.scale = props.camera.scale;
+                }
                 if (props.cameraFog !== undefined && props.cameraFog.params) {
                     const newFog = props.cameraFog.name === 'on' ? props.cameraFog.params.intensity : 0;
                     if (newFog !== camera.state.fog) cameraState.fog = newFog;
@@ -1142,6 +1187,9 @@ namespace Canvas3D {
             get props() {
                 return getProps();
             },
+            get attribs() {
+                return a;
+            },
             get input() {
                 return input;
             },
@@ -1169,6 +1217,9 @@ namespace Canvas3D {
                 renderer.dispose();
                 interactionHelper.dispose();
                 hiZ.dispose();
+                pickHelper.dispose();
+                rayHelper.dispose();
+
                 if (fenceSync !== null) {
                     webgl.deleteSync(fenceSync);
                     fenceSync = null;
@@ -1180,22 +1231,23 @@ namespace Canvas3D {
 
         function updateViewport() {
             const oldX = x, oldY = y, oldWidth = width, oldHeight = height;
+            const drs = webgl.getDrawingBufferSize();
 
             if (p.viewport.name === 'canvas') {
                 x = 0;
                 y = 0;
-                width = gl.drawingBufferWidth;
-                height = gl.drawingBufferHeight;
+                width = drs.width;
+                height = drs.height;
             } else if (p.viewport.name === 'static-frame') {
                 x = p.viewport.params.x * webgl.pixelRatio;
                 height = p.viewport.params.height * webgl.pixelRatio;
-                y = gl.drawingBufferHeight - height - p.viewport.params.y * webgl.pixelRatio;
+                y = drs.height - height - p.viewport.params.y * webgl.pixelRatio;
                 width = p.viewport.params.width * webgl.pixelRatio;
             } else if (p.viewport.name === 'relative-frame') {
-                x = Math.round(p.viewport.params.x * gl.drawingBufferWidth);
-                height = Math.round(p.viewport.params.height * gl.drawingBufferHeight);
-                y = Math.round(gl.drawingBufferHeight - height - p.viewport.params.y * gl.drawingBufferHeight);
-                width = Math.round(p.viewport.params.width * gl.drawingBufferWidth);
+                x = Math.round(p.viewport.params.x * drs.width);
+                height = Math.round(p.viewport.params.height * drs.height);
+                y = Math.round(drs.height - height - p.viewport.params.y * drs.height);
+                width = Math.round(p.viewport.params.width * drs.width);
             }
 
             if (oldX !== x || oldY !== y || oldWidth !== width || oldHeight !== height) {

src/mol-canvas3d/controls/trackball.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  * @author David Sehnal <david.sehnal@gmail.com>
@@ -56,8 +56,6 @@ export const DefaultTrackballBindings = {
 };
 
 export const TrackballControlsParams = {
-    noScroll: PD.Boolean(true, { isHidden: true }),
-
     rotateSpeed: PD.Numeric(5.0, { min: 1, max: 10, step: 1 }),
     zoomSpeed: PD.Numeric(7.0, { min: 1, max: 15, step: 1 }),
     panSpeed: PD.Numeric(1.0, { min: 0.1, max: 5, step: 0.1 }),
@@ -68,10 +66,10 @@ export const TrackballControlsParams = {
     animate: PD.MappedStatic('off', {
         off: PD.EmptyGroup(),
         spin: PD.Group({
-            speed: PD.Numeric(1, { min: -20, max: 20, step: 1 }, { description: 'Rotation speed in radians per second' }),
+            speed: PD.Numeric(0.3, { min: -5, max: 5, step: 0.1 }, { description: 'Number of rotations per second' }),
         }, { description: 'Spin the 3D scene around the x-axis in view space' }),
         rock: PD.Group({
-            speed: PD.Numeric(0.3, { min: -5, max: 5, step: 0.1 }),
+            speed: PD.Numeric(0.3, { min: -5, max: 5, step: 0.1 }, { description: 'Number of oscilations per second' }),
             angle: PD.Numeric(10, { min: 0, max: 90, step: 1 }, { description: 'How many degrees to rotate in each direction.' }),
         }, { description: 'Rock the 3D scene around the x-axis in view space' })
     }),
@@ -85,8 +83,6 @@ export const TrackballControlsParams = {
     gestureScaleFactor: PD.Numeric(1, {}, { isHidden: true }),
     maxWheelDelta: PD.Numeric(0.02, {}, { isHidden: true }),
 
-    bindings: PD.Value(DefaultTrackballBindings, { isHidden: true }),
-
     /**
      * minDistance = minDistanceFactor * boundingSphere.radius + minDistancePadding
      * maxDistance = max(maxDistanceFactor * boundingSphere.radius, maxDistanceMin)
@@ -103,6 +99,11 @@ export const TrackballControlsParams = {
 };
 export type TrackballControlsProps = PD.Values<typeof TrackballControlsParams>
 
+export const DefaultTrackballControlsAttribs = {
+    bindings: DefaultTrackballBindings,
+};
+export type TrackballControlsAttribs = typeof DefaultTrackballControlsAttribs
+
 export { TrackballControls };
 interface TrackballControls {
     readonly viewport: Viewport
@@ -112,20 +113,25 @@ interface TrackballControls {
     readonly props: Readonly<TrackballControlsProps>
     setProps: (props: Partial<TrackballControlsProps>) => void
 
+    readonly attribs: Readonly<TrackballControlsAttribs>
+    setAttribs: (attribs: Partial<TrackballControlsAttribs>) => void
+
     start: (t: number) => void
     update: (t: number) => void
     reset: () => void
     dispose: () => void
 }
 namespace TrackballControls {
-    export function create(input: InputObserver, camera: Camera, scene: Scene, props: Partial<TrackballControlsProps> = {}): TrackballControls {
+    export function create(input: InputObserver, camera: Camera, scene: Scene, props: Partial<TrackballControlsProps> = {}, attribs: Partial<TrackballControlsAttribs> = {}): TrackballControls {
         const p: TrackballControlsProps = {
             ...PD.getDefaultValues(TrackballControlsParams),
             ...props,
-            // include default bindings for backwards state compatibility
-            bindings: { ...DefaultTrackballBindings, ...props.bindings }
         };
-        const b = p.bindings;
+        const a: TrackballControlsAttribs = {
+            ...DefaultTrackballControlsAttribs,
+            ...attribs
+        };
+        const b = a.bindings;
 
         const viewport = Viewport.clone(camera.viewport);
 
@@ -825,7 +831,7 @@ namespace TrackballControls {
         function spin(deltaT: number) {
             if (p.animate.name !== 'spin' || p.animate.params.speed === 0 || _isInteracting) return;
 
-            const radPerMs = p.animate.params.speed / 1000;
+            const radPerMs = 2 * Math.PI * p.animate.params.speed / 1000;
             _spinSpeed[0] = deltaT * radPerMs / getRotateFactor();
             Vec2.add(_rotCurr, _rotPrev, _spinSpeed);
         }
@@ -885,7 +891,12 @@ namespace TrackballControls {
                     }
                 }
                 Object.assign(p, props);
-                Object.assign(b, props.bindings);
+            },
+
+            get attribs() { return a as Readonly<TrackballControlsAttribs>; },
+            setAttribs: (attribs: Partial<TrackballControlsAttribs>) => {
+                Object.assign(a, attribs);
+                Object.assign(b, a.bindings);
             },
 
             start,

src/mol-canvas3d/helper/camera-helper.ts

@@ -4,7 +4,7 @@
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
-import { produce } from 'immer';
+import { produce } from '../../mol-util/produce';
 import { Interval } from '../../mol-data/int/interval';
 import { addCylinder } from '../../mol-geo/geometry/mesh/builder/cylinder';
 import { addSphere } from '../../mol-geo/geometry/mesh/builder/sphere';

src/mol-canvas3d/helper/handle-helper.ts

@@ -16,7 +16,7 @@ import { addCylinder } from '../../mol-geo/geometry/mesh/builder/cylinder';
 import { ValueCell } from '../../mol-util';
 import { Sphere3D } from '../../mol-math/geometry';
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
-import { produce } from 'immer';
+import { produce } from '../../mol-util/produce';
 import { Shape } from '../../mol-model/shape';
 import { PickingId } from '../../mol-geo/geometry/picking';
 import { Camera } from '../camera';

src/mol-canvas3d/helper/interaction-events.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2018-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -14,14 +14,14 @@ import { Camera } from '../camera';
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
 import { Bond } from '../../mol-model/structure';
 import { TrackballControls } from '../controls/trackball';
+import { Ray3D } from '../../mol-math/geometry/primitives/ray3d';
+import { AsyncPickData } from '../passes/pick';
 
 type Canvas3D = import('../canvas3d').Canvas3D
 type HoverEvent = import('../canvas3d').Canvas3D.HoverEvent
 type DragEvent = import('../canvas3d').Canvas3D.DragEvent
 type ClickEvent = import('../canvas3d').Canvas3D.ClickEvent
 
-enum InputEvent { Move, Click, Drag }
-
 const tmpPosA = Vec3();
 const tmpPos = Vec3();
 const tmpNorm = Vec3();
@@ -29,6 +29,7 @@ const tmpNorm = Vec3();
 export const Canvas3dInteractionHelperParams = {
     maxFps: PD.Numeric(30, { min: 10, max: 60, step: 10 }),
     preferAtomPixelPadding: PD.Numeric(3, { min: 0, max: 20, step: 1 }, { description: 'Number of extra pixels at which to prefer atoms over bonds.' }),
+    convertCoordsToRay: PD.Boolean(false, { description: 'Convert screen coordinates to ray for picking.' }),
 };
 export type Canvas3dInteractionHelperParams = typeof Canvas3dInteractionHelperParams
 export type Canvas3dInteractionHelperProps = PD.Values<Canvas3dInteractionHelperParams>
@@ -47,10 +48,11 @@ export class Canvas3dInteractionHelper {
     private endX = -1;
     private endY = -1;
 
-    private id: PickingId | undefined = void 0;
+    private ray: Ray3D | undefined = void 0;
+
+    private pickData: AsyncPickData | undefined = void 0;
     private position: Vec3 | undefined = void 0;
 
-    private currentIdentifyT = 0;
     private isInteracting = false;
 
     private prevLoci: Representation.Loci = Representation.Loci.Empty;
@@ -68,46 +70,66 @@ export class Canvas3dInteractionHelper {
         Object.assign(this.props, props);
     }
 
-    private identify(e: InputEvent, t: number) {
-        const xyChanged = this.startX !== this.endX || this.startY !== this.endY || (this.input.pointerLock && !this.controls.isMoving);
-
-        if (e === InputEvent.Drag) {
-            if (xyChanged && !this.outsideViewport(this.startX, this.startY)) {
-                this.events.drag.next({ current: this.prevLoci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, pageStart: Vec2.create(this.startX, this.startY), pageEnd: Vec2.create(this.endX, this.endY) });
-
-                this.startX = this.endX;
-                this.startY = this.endY;
-            }
-            return;
+    private getTarget(): Vec2 | Ray3D {
+        if (this.ray) {
+            return this.ray;
+        } else if (this.props.convertCoordsToRay) {
+            return this.camera.getRay(Ray3D(), this.endX, this.input.height - this.endY);
+        } else {
+            return Vec2.create(this.endX, this.endY);
         }
+    }
 
+    private handleMove() {
+        const xyChanged = this.startX !== this.endX || this.startY !== this.endY || (this.input.pointerLock && !this.controls.isMoving);
         if (xyChanged) {
-            const pickData = this.canvasIdentify(this.endX, this.endY);
-            this.id = pickData?.id;
-            this.position = pickData?.position;
+            this.pickData = this.canvasAsyncIdentify(this.getTarget());
             this.startX = this.endX;
             this.startY = this.endY;
         }
+    }
 
-        if (e === InputEvent.Click) {
-            const loci = this.getLoci(this.id, this.position);
-            this.events.click.next({ current: loci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, page: Vec2.create(this.endX, this.endY), position: this.position });
-            this.prevLoci = loci;
-            return;
-        }
-
-        if (!this.inside || this.currentIdentifyT !== t || !xyChanged || this.outsideViewport(this.endX, this.endY)) return;
-
-        const loci = this.getLoci(this.id, this.position);
-        this.events.hover.next({ current: loci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, page: Vec2.create(this.endX, this.endY), position: this.position });
+    private handleClick() {
+        const pickData = this.canvasIdentify(this.getTarget());
+        const loci = this.getLoci(pickData?.id, pickData?.position);
+        this.events.click.next({ current: loci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, page: Vec2.create(this.endX, this.endY), position: pickData?.position });
         this.prevLoci = loci;
     }
 
+    private handleDrag() {
+        const xyChanged = this.startX !== this.endX || this.startY !== this.endY || (this.input.pointerLock && !this.controls.isMoving);
+
+        if (xyChanged && !this.outsideViewport(this.startX, this.startY, this.ray)) {
+            this.events.drag.next({ current: this.prevLoci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, pageStart: Vec2.create(this.startX, this.startY), pageEnd: Vec2.create(this.endX, this.endY) });
+
+            this.startX = this.endX;
+            this.startY = this.endY;
+        }
+    }
+
     tick(t: number) {
-        if (this.inside && t - this.prevT > 1000 / this.props.maxFps) {
+        if (!this.inside) return;
+
+        if (this.pickData) {
+            const pickData = this.pickData.tryGet();
+            if (pickData !== 'pending') {
+                this.position = pickData?.position;
+                if (this.inside) {
+                    const loci = this.getLoci(pickData?.id, pickData?.position);
+                    this.events.hover.next({ current: loci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, page: Vec2.create(this.endX, this.endY), position: pickData?.position });
+                    this.prevLoci = loci;
+                }
+                this.pickData = undefined;
+            }
+        }
+
+        if (t - this.prevT > 1000 / this.props.maxFps) {
             this.prevT = t;
-            this.currentIdentifyT = t;
-            this.identify(this.isInteracting ? InputEvent.Drag : InputEvent.Move, t);
+            if (this.isInteracting) {
+                this.handleDrag();
+            } else {
+                this.handleMove();
+            }
         }
     }
 
@@ -119,22 +141,24 @@ export class Canvas3dInteractionHelper {
         }
     }
 
-    private move(x: number, y: number, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys) {
+    private move(x: number, y: number, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys, ray?: Ray3D) {
         this.inside = true;
         this.buttons = buttons;
         this.button = button;
         this.modifiers = modifiers;
+        this.ray = ray;
         this.endX = x;
         this.endY = y;
     }
 
-    private click(x: number, y: number, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys) {
+    private click(x: number, y: number, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys, ray?: Ray3D) {
         this.endX = x;
         this.endY = y;
         this.buttons = buttons;
         this.button = button;
         this.modifiers = modifiers;
-        this.identify(InputEvent.Click, 0);
+        this.ray = ray;
+        this.handleClick();
     }
 
     private drag(x: number, y: number, buttons: ButtonsType, button: ButtonsType.Flag, modifiers: ModifiersKeys) {
@@ -143,7 +167,7 @@ export class Canvas3dInteractionHelper {
         this.buttons = buttons;
         this.button = button;
         this.modifiers = modifiers;
-        this.identify(InputEvent.Drag, 0);
+        this.handleDrag();
     }
 
     private modify(modifiers: ModifiersKeys) {
@@ -152,7 +176,9 @@ export class Canvas3dInteractionHelper {
         this.events.hover.next({ current: this.prevLoci, buttons: this.buttons, button: this.button, modifiers: this.modifiers, page: Vec2.create(this.endX, this.endY), position: this.position });
     }
 
-    private outsideViewport(x: number, y: number) {
+    private outsideViewport(x: number, y: number, ray?: Ray3D) {
+        if (ray) return false;
+
         const { input, camera: { viewport } } = this;
         x *= input.pixelRatio;
         y *= input.pixelRatio;
@@ -189,7 +215,7 @@ export class Canvas3dInteractionHelper {
         this.ev.dispose();
     }
 
-    constructor(private canvasIdentify: Canvas3D['identify'], private lociGetter: Canvas3D['getLoci'], private input: InputObserver, private camera: Camera, private controls: TrackballControls, props: Partial<Canvas3dInteractionHelperProps> = {}) {
+    constructor(private canvasIdentify: Canvas3D['identify'], private canvasAsyncIdentify: Canvas3D['asyncIdentify'], private lociGetter: Canvas3D['getLoci'], private input: InputObserver, private camera: Camera, private controls: TrackballControls, props: Partial<Canvas3dInteractionHelperProps> = {}) {
         this.props = { ...PD.getDefaultValues(Canvas3dInteractionHelperParams), ...props };
 
         input.drag.subscribe(({ x, y, buttons, button, modifiers }) => {
@@ -198,14 +224,14 @@ export class Canvas3dInteractionHelper {
             this.drag(x, y, buttons, button, modifiers);
         });
 
-        input.move.subscribe(({ x, y, inside, buttons, button, modifiers, onElement }) => {
+        input.move.subscribe(({ x, y, inside, buttons, button, modifiers, onElement, ray }) => {
             if (!inside || this.isInteracting) return;
             if (!onElement) {
                 this.leave();
                 return;
             }
             // console.log('move');
-            this.move(x, y, buttons, button, modifiers);
+            this.move(x, y, buttons, button, modifiers, ray);
         });
 
         input.leave.subscribe(() => {
@@ -213,10 +239,10 @@ export class Canvas3dInteractionHelper {
             this.leave();
         });
 
-        input.click.subscribe(({ x, y, buttons, button, modifiers }) => {
-            if (this.outsideViewport(x, y)) return;
+        input.click.subscribe(({ x, y, buttons, button, modifiers, ray }) => {
+            if (this.outsideViewport(x, y, ray)) return;
             // console.log('click');
-            this.click(x, y, buttons, button, modifiers);
+            this.click(x, y, buttons, button, modifiers, ray);
         });
 
         input.interactionEnd.subscribe(() => {

src/mol-canvas3d/helper/pick-helper.ts

@@ -0,0 +1,208 @@
+/**
+ * Copyright (c) 2019-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Renderer } from '../../mol-gl/renderer';
+import { Scene } from '../../mol-gl/scene';
+import { WebGLContext } from '../../mol-gl/webgl/context';
+import { Vec3 } from '../../mol-math/linear-algebra/3d/vec3';
+import { spiral2d } from '../../mol-math/misc';
+import { isTimingMode } from '../../mol-util/debug';
+import { Camera } from '../camera';
+import { StereoCamera } from '../camera/stereo';
+import { cameraUnproject, Viewport } from '../camera/util';
+import { Helper } from '../helper/helper';
+import { AsyncPickData, AsyncPickStatus, checkAsyncPickingSupport, PickBuffers, PickData, PickOptions, PickPass } from '../passes/pick';
+
+export class PickHelper {
+    dirty = true;
+
+    private pickPadding: number;
+    private buffers = new PickBuffers(this.webgl, this.pickPass);
+    private viewport = Viewport();
+
+    private pickRatio: number;
+    private pickX: number;
+    private pickY: number;
+    private pickWidth: number;
+    private pickHeight: number;
+    private halfPickWidth: number;
+
+    private spiral: [number, number][];
+
+    setViewport(x: number, y: number, width: number, height: number) {
+        Viewport.set(this.viewport, x, y, width, height);
+        this.update();
+    }
+
+    setPickPadding(pickPadding: number) {
+        if (this.pickPadding !== pickPadding) {
+            this.pickPadding = pickPadding;
+            this.update();
+        }
+    }
+
+    private update() {
+        const { x, y, width, height } = this.viewport;
+
+        this.pickRatio = this.pickPass.pickRatio;
+        this.pickX = Math.ceil(x * this.pickRatio);
+        this.pickY = Math.ceil(y * this.pickRatio);
+
+        const pickWidth = Math.floor(width * this.pickRatio);
+        const pickHeight = Math.floor(height * this.pickRatio);
+
+        if (pickWidth !== this.pickWidth || pickHeight !== this.pickHeight) {
+            this.pickWidth = pickWidth;
+            this.pickHeight = pickHeight;
+            this.halfPickWidth = Math.floor(this.pickWidth / 2);
+
+            this.buffers.setViewport(this.pickX, this.pickY, this.pickWidth, this.pickHeight);
+        }
+
+        this.spiral = spiral2d(Math.ceil(this.pickRatio * this.pickPadding));
+        this.dirty = true;
+    }
+
+    private render(camera: Camera | StereoCamera) {
+        if (isTimingMode) this.webgl.timer.mark('PickHelper.render', { captureStats: true });
+        const { pickX, pickY, pickWidth, pickHeight, halfPickWidth } = this;
+        const { renderer, scene, helper } = this;
+
+        renderer.setTransparentBackground(false);
+        renderer.setDrawingBufferSize(pickWidth, pickHeight);
+        renderer.setPixelRatio(this.pickRatio);
+
+        if (StereoCamera.is(camera)) {
+            renderer.setViewport(pickX, pickY, halfPickWidth, pickHeight);
+            this.pickPass.render(renderer, camera.left, scene, helper);
+
+            renderer.setViewport(pickX + halfPickWidth, pickY, pickWidth - halfPickWidth, pickHeight);
+            this.pickPass.render(renderer, camera.right, scene, helper);
+        } else {
+            renderer.setViewport(pickX, pickY, pickWidth, pickHeight);
+            this.pickPass.render(renderer, camera, scene, helper);
+        }
+
+        this.dirty = false;
+        if (isTimingMode) this.webgl.timer.markEnd('PickHelper.render');
+    }
+
+    private identifyInternal(x: number, y: number, camera: Camera | StereoCamera): PickData | undefined {
+        if (this.webgl.isContextLost) return;
+
+        const { webgl, pickRatio } = this;
+        if (webgl.isContextLost) return;
+
+        x *= webgl.pixelRatio;
+        y *= webgl.pixelRatio;
+        y = this.pickPass.drawingBufferHeight - y; // flip y
+
+        const { viewport } = this;
+
+        // check if within viewport
+        if (x < viewport.x ||
+            y < viewport.y ||
+            x > viewport.x + viewport.width ||
+            y > viewport.y + viewport.height
+        ) return;
+
+        const xv = x - viewport.x;
+        const yv = y - viewport.y;
+
+        const xp = Math.floor(xv * pickRatio);
+        const yp = Math.floor(yv * pickRatio);
+
+        const pickingId = this.buffers.getPickingId(xp, yp);
+        if (pickingId === undefined) return;
+
+        const z = this.buffers.getDepth(xp, yp);
+        const position = Vec3.create(x, y, z);
+        if (StereoCamera.is(camera)) {
+            const halfWidth = Math.floor(viewport.width / 2);
+            if (x > viewport.x + halfWidth) {
+                position[0] = viewport.x + (xv - halfWidth) * 2;
+                cameraUnproject(position, position, viewport, camera.right.inverseProjectionView);
+            } else {
+                position[0] = viewport.x + xv * 2;
+                cameraUnproject(position, position, viewport, camera.left.inverseProjectionView);
+            }
+        } else {
+            cameraUnproject(position, position, viewport, camera.inverseProjectionView);
+        }
+
+        return { id: pickingId, position };
+    }
+
+    private prepare() {
+        if (this.pickRatio !== this.pickPass.pickRatio) {
+            this.update();
+        }
+    }
+
+    private getPickData(x: number, y: number, camera: Camera | StereoCamera): PickData | undefined {
+        for (const d of this.spiral) {
+            const pickData = this.identifyInternal(x + d[0], y + d[1], camera);
+            if (pickData) return pickData;
+        }
+    }
+
+    identify(x: number, y: number, camera: Camera | StereoCamera): PickData | undefined {
+        this.prepare();
+
+        if (this.dirty) {
+            if (isTimingMode) this.webgl.timer.mark('PickHelper.identify');
+            this.render(camera);
+            this.buffers.read();
+            if (isTimingMode) this.webgl.timer.markEnd('PickHelper.identify');
+        }
+
+        return this.getPickData(x, y, camera);
+    }
+
+    asyncIdentify(x: number, y: number, camera: Camera | StereoCamera): AsyncPickData | undefined {
+        this.prepare();
+
+        if (this.dirty) {
+            if (isTimingMode) this.webgl.timer.mark('PickHelper.asyncIdentify');
+            this.render(camera);
+            this.buffers.asyncRead();
+            if (isTimingMode) this.webgl.timer.markEnd('PickHelper.asyncIdentify');
+        }
+
+        return {
+            tryGet: () => {
+                const status = this.buffers.check();
+                if (status === AsyncPickStatus.Resolved) {
+                    return this.getPickData(x, y, camera);
+                } else if (status === AsyncPickStatus.Pending) {
+                    return 'pending';
+                } else if (status === AsyncPickStatus.Failed) {
+                    this.dirty = true;
+                }
+            }
+        };
+    }
+
+    reset() {
+        this.buffers.reset();
+        this.dirty = true;
+    }
+
+    dispose() {
+        this.buffers.dispose();
+    }
+
+    constructor(private webgl: WebGLContext, private renderer: Renderer, private scene: Scene, private helper: Helper, private pickPass: PickPass, viewport: Viewport, options: PickOptions) {
+        this.setViewport(viewport.x, viewport.y, viewport.width, viewport.height);
+        this.pickPadding = options.pickPadding;
+
+        if (!checkAsyncPickingSupport(webgl)) {
+            this.asyncIdentify = (x, y, camera) => ({
+                tryGet: () => this.identify(x, y, camera)
+            });
+        }
+    }
+}

src/mol-canvas3d/helper/ray-helper.ts

@@ -0,0 +1,205 @@
+/**
+ * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Renderer } from '../../mol-gl/renderer';
+import { Scene } from '../../mol-gl/scene';
+import { WebGLContext } from '../../mol-gl/webgl/context';
+import { Ray3D } from '../../mol-math/geometry/primitives/ray3d';
+import { Mat4, Quat, Vec3 } from '../../mol-math/linear-algebra';
+import { degToRad, spiral2d } from '../../mol-math/misc';
+import { isTimingMode } from '../../mol-util/debug';
+import { Camera } from '../camera';
+import { cameraUnproject } from '../camera/util';
+import { Viewport } from '../camera/util';
+import { Helper } from './helper';
+import { AsyncPickData, PickBuffers, PickData, PickPass, PickOptions, checkAsyncPickingSupport, AsyncPickStatus } from '../passes/pick';
+import { Sphere3D } from '../../mol-math/geometry/primitives/sphere3d';
+
+export class RayHelper {
+    private viewport = Viewport();
+    private size: number;
+    private spiral: [number, number][];
+
+    private pickPadding: number;
+    private camera: Camera;
+    private pickPass: PickPass;
+    private buffers: PickBuffers;
+
+    setPickPadding(pickPadding: number) {
+        if (this.pickPadding !== pickPadding) {
+            this.pickPadding = pickPadding;
+            this.update();
+        }
+    }
+
+    private update() {
+        const size = this.pickPadding * 2 + 1;
+        Viewport.set(this.viewport, 0, 0, size, size);
+        this.buffers.setViewport(0, 0, size, size);
+
+        this.spiral = spiral2d(this.pickPadding);
+        this.size = size;
+
+        this.pickPass.setSize(size, size);
+    }
+
+    private render(camera: Camera) {
+        if (isTimingMode) this.webgl.timer.mark('RayHelper.render', { captureStats: true });
+        const { renderer, scene, helper } = this;
+
+        renderer.setTransparentBackground(false);
+        renderer.setDrawingBufferSize(this.size, this.size);
+        renderer.setPixelRatio(1);
+
+        renderer.setViewport(0, 0, this.size, this.size);
+        this.pickPass.render(renderer, camera, scene, helper);
+
+        if (isTimingMode) this.webgl.timer.markEnd('RayHelper.render');
+    }
+
+    private identifyInternal(x: number, y: number): PickData | undefined {
+        if (this.webgl.isContextLost) return;
+
+        const { viewport } = this;
+
+        const pickingId = this.buffers.getPickingId(x, y);
+        if (pickingId === undefined) return;
+
+        const z = this.buffers.getDepth(x, y);
+        const position = Vec3.create(x, y, z);
+        cameraUnproject(position, position, viewport, this.camera.inverseProjectionView);
+
+        return { id: pickingId, position };
+    }
+
+    private prepare(ray: Ray3D, cam: Camera) {
+        this.camera.far = cam.far;
+        this.camera.near = cam.near;
+        this.camera.fogFar = cam.fogFar;
+        this.camera.fogNear = cam.fogNear;
+        Viewport.copy(this.camera.viewport, this.viewport);
+        Camera.copySnapshot(this.camera.state, { ...cam.state, mode: 'orthographic' });
+
+        updateOrthoRayCamera(this.camera, ray);
+        Mat4.mul(this.camera.projectionView, this.camera.projection, this.camera.view);
+        Mat4.tryInvert(this.camera.inverseProjectionView, this.camera.projectionView);
+    }
+
+    private getPickData(): PickData | undefined {
+        const c = this.pickPadding;
+        for (const d of this.spiral) {
+            const pickData = this.identifyInternal(c + d[0], c + d[1]);
+            if (pickData) return pickData;
+        }
+    }
+
+    sphere = Sphere3D();
+
+    private intersectsScene(ray: Ray3D, scale: number): boolean {
+        Sphere3D.scaleNX(this.sphere, this.scene.boundingSphereVisible, scale);
+        return Ray3D.isInsideSphere3D(ray, this.sphere) || Ray3D.isIntersectingSphere3D(ray, this.sphere);
+    }
+
+    identify(ray: Ray3D, cam: Camera): PickData | undefined {
+        if (!this.intersectsScene(ray, cam.state.scale)) return;
+
+        this.prepare(ray, cam);
+
+        if (isTimingMode) this.webgl.timer.mark('RayHelper.identify');
+        this.render(this.camera);
+        this.buffers.read();
+        if (isTimingMode) this.webgl.timer.markEnd('RayHelper.identify');
+
+        return this.getPickData();
+    }
+
+    asyncIdentify(ray: Ray3D, cam: Camera): AsyncPickData | undefined {
+        if (!this.intersectsScene(ray, cam.state.scale)) return;
+
+        this.prepare(ray, cam);
+
+        if (isTimingMode) this.webgl.timer.mark('RayHelper.asyncIdentify');
+        this.render(this.camera);
+        this.buffers.asyncRead();
+        if (isTimingMode) this.webgl.timer.markEnd('RayHelper.asyncIdentify');
+
+        return {
+            tryGet: () => {
+                const status = this.buffers.check();
+                if (status === AsyncPickStatus.Resolved) {
+                    return this.getPickData();
+                } else if (status === AsyncPickStatus.Pending) {
+                    return 'pending';
+                }
+            }
+        };
+    }
+
+    reset() {
+        this.buffers.reset();
+        this.pickPass.reset();
+    }
+
+    dispose() {
+        this.buffers.dispose();
+        this.pickPass.dispose();
+    }
+
+    constructor(private webgl: WebGLContext, private renderer: Renderer, private scene: Scene, private helper: Helper, options: PickOptions) {
+        const size = options.pickPadding * 2 + 1;
+
+        this.camera = new Camera();
+        this.pickPass = new PickPass(webgl, size, size, 1);
+        this.buffers = new PickBuffers(this.webgl, this.pickPass, options.maxAsyncReadLag);
+        this.pickPadding = options.pickPadding;
+
+        this.update();
+
+        if (!checkAsyncPickingSupport(webgl)) {
+            this.asyncIdentify = (ray, cam) => ({
+                tryGet: () => this.identify(ray, cam)
+            });
+        }
+    }
+}
+
+//
+
+function updateOrthoRayCamera(camera: Camera, ray: Ray3D) {
+    const { near, far, viewport } = camera;
+
+    const height = 2 * Math.tan(degToRad(0.1) / 2) * Vec3.distance(camera.position, camera.target) * camera.state.scale;
+    const zoom = viewport.height / height;
+
+    const fullLeft = -viewport.width / 2;
+    const fullRight = viewport.width / 2;
+    const fullTop = viewport.height / 2;
+    const fullBottom = -viewport.height / 2;
+
+    const dx = (fullRight - fullLeft) / (2 * zoom);
+    const dy = (fullTop - fullBottom) / (2 * zoom);
+    const cx = (fullRight + fullLeft) / 2;
+    const cy = (fullTop + fullBottom) / 2;
+
+    const left = cx - dx;
+    const right = cx + dx;
+    const top = cy + dy;
+    const bottom = cy - dy;
+
+    // build projection matrix
+    Mat4.ortho(camera.projection, left, right, top, bottom, near, far);
+
+    const direction = Vec3.normalize(Vec3(), ray.direction);
+    const r = Quat.fromUnitVec3(Quat(), direction, Vec3.negUnitZ);
+    Quat.invert(r, r);
+
+    const eye = Vec3.clone(ray.origin);
+    const up = Vec3.transformQuat(Vec3(), Vec3.unitY, r);
+    const target = Vec3.add(Vec3(), eye, direction);
+
+    // build view matrix
+    Mat4.lookAt(camera.view, eye, target, up);
+}

src/mol-canvas3d/passes/background.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -26,6 +26,7 @@ import { Vec4 } from '../../mol-math/linear-algebra/3d/vec4';
 import { degToRad, isPowerOfTwo } from '../../mol-math/misc';
 import { Mat3 } from '../../mol-math/linear-algebra/3d/mat3';
 import { Euler } from '../../mol-math/linear-algebra/3d/euler';
+import { PostprocessingProps } from './postprocessing';
 
 const SharedParams = {
     opacity: PD.Numeric(1, { min: 0.0, max: 1.0, step: 0.01 }),
@@ -172,10 +173,14 @@ export class BackgroundPass {
         }
 
         const m = this.renderable.values.uViewDirectionProjectionInverse.ref.value;
-        Vec3.sub(this.dir, cam.state.position, cam.state.target);
-        Vec3.setMagnitude(this.dir, this.dir, 0.1);
-        Vec3.copy(this.position, this.dir);
-        Mat4.lookAt(m, this.position, this.target, cam.state.up);
+        if (Mat4.isZero(camera.headRotation)) {
+            Vec3.sub(this.dir, cam.state.position, cam.state.target);
+            Vec3.setMagnitude(this.dir, this.dir, 0.1);
+            Vec3.copy(this.position, this.dir);
+            Mat4.lookAt(m, this.position, this.target, cam.state.up);
+        } else {
+            Mat4.invert(m, camera.headRotation);
+        }
         Mat4.mul(m, cam.projection, m);
         Mat4.invert(m, m);
         ValueCell.update(this.renderable.values.uViewDirectionProjectionInverse, m);
@@ -292,7 +297,7 @@ export class BackgroundPass {
         ValueCell.update(this.renderable.values.uViewport, Vec4.set(this.renderable.values.uViewport.ref.value, x, y, width, height));
     }
 
-    isEnabled(props: BackgroundProps) {
+    private _isEnabled(props: BackgroundProps) {
         return !!(
             (this.skybox && this.skybox.loaded) ||
             (this.image && this.image.loaded) ||
@@ -301,6 +306,10 @@ export class BackgroundPass {
         );
     }
 
+    isEnabled(props: PostprocessingProps) {
+        return props.enabled && this._isEnabled(props.background);
+    }
+
     private isReady() {
         return !!(
             (this.skybox && this.skybox.loaded) ||
@@ -315,7 +324,7 @@ export class BackgroundPass {
     clear(props: BackgroundProps, transparentBackground: boolean, backgroundColor: Color) {
         const { gl, state } = this.webgl;
 
-        if (this.isEnabled(props)) {
+        if (this._isEnabled(props)) {
             if (transparentBackground) {
                 state.clearColor(0, 0, 0, 0);
             } else {
@@ -332,7 +341,7 @@ export class BackgroundPass {
     }
 
     render(props: BackgroundProps) {
-        if (!this.isEnabled(props) || !this.isReady()) return;
+        if (!this._isEnabled(props) || !this.isReady()) return;
 
         if (this.renderable.values.dVariant.ref.value === 'image') {
             this.updateImageScaling();

src/mol-canvas3d/passes/bloom.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2024-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  *
@@ -38,7 +38,7 @@ export type BloomProps = PD.Values<typeof BloomParams>
 
 export class BloomPass {
     static isEnabled(props: PostprocessingProps) {
-        return props.bloom.name === 'on';
+        return props.enabled && props.bloom.name === 'on';
     }
 
     readonly emissiveTarget: RenderTarget;
@@ -207,7 +207,7 @@ export class BloomPass {
         if (target) {
             target.bind();
         } else {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         }
         state.enable(gl.BLEND);
         state.blendFunc(gl.ONE, gl.ONE);

src/mol-canvas3d/passes/cas.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -79,7 +79,7 @@ export class CasPass {
         if (target) {
             target.bind();
         } else {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         }
         this.updateState(viewport);
         this.renderable.render();

src/mol-canvas3d/passes/dof.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2024-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Ludovic Autin <autin@scripps.edu>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -37,7 +37,7 @@ export type DofProps = PD.Values<typeof DofParams>
 
 export class DofPass {
     static isEnabled(props: PostprocessingProps) {
-        return props.dof.name !== 'off';
+        return props.enabled && props.dof.name !== 'off';
     }
 
     readonly target: RenderTarget;
@@ -119,18 +119,18 @@ export class DofPass {
             needsUpdate = true;
         }
 
-        const wolrdCenter = (props.center === 'scene-center' ? sphere.center : camera.state.target);
-        const distance = Vec3.distance(camera.state.position, wolrdCenter);
+        const worldCenter = (props.center === 'scene-center' ? sphere.center : camera.state.target);
+        const distance = Vec3.distance(camera.state.position, worldCenter);
         const inFocus = distance + props.inFocus;
-        ValueCell.updateIfChanged(this.renderable.values.uInFocus, inFocus);
+        ValueCell.updateIfChanged(this.renderable.values.uInFocus, inFocus * camera.state.scale);
 
         // transform center in view space
         const center = this.renderable.values.uCenter.ref.value;
-        Vec3.transformMat4(center, wolrdCenter, camera.view);
+        Vec3.transformMat4(center, worldCenter, camera.view);
         ValueCell.update(this.renderable.values.uCenter, center);
 
         ValueCell.updateIfChanged(this.renderable.values.uBlurSpread, props.blurSpread);
-        ValueCell.updateIfChanged(this.renderable.values.uPPM, props.PPM);
+        ValueCell.updateIfChanged(this.renderable.values.uPPM, props.PPM * camera.state.scale);
 
         if (needsUpdate) {
             this.renderable.update();
@@ -142,7 +142,7 @@ export class DofPass {
         if (target) {
             target.bind();
         } else {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         }
         this.updateState(viewport);
         this.renderable.render();

src/mol-canvas3d/passes/dpoit.ts

@@ -167,6 +167,7 @@ export class DpoitPass {
         if (isTimingMode) this.webgl.timer.mark('DpoitPass.render');
         const { state, gl } = this.webgl;
 
+        state.blendEquation(gl.FUNC_ADD);
         state.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 
         ValueCell.update(this.renderable.values.tDpoitFrontColor, this.colorFrontTextures[this.writeId]);

src/mol-canvas3d/passes/draw.ts

@@ -7,7 +7,7 @@
  */
 
 import { WebGLContext } from '../../mol-gl/webgl/context';
-import { createNullRenderTarget, RenderTarget } from '../../mol-gl/webgl/render-target';
+import { RenderTarget } from '../../mol-gl/webgl/render-target';
 import { Renderer } from '../../mol-gl/renderer';
 import { Scene } from '../../mol-gl/scene';
 import { Texture } from '../../mol-gl/webgl/texture';
@@ -90,7 +90,7 @@ export class DrawPass {
 
     constructor(private webgl: WebGLContext, assetManager: AssetManager, width: number, height: number, transparency: 'wboit' | 'dpoit' | 'blended') {
         const { extensions, resources, isWebGL2 } = webgl;
-        this.drawTarget = createNullRenderTarget(webgl.gl);
+        this.drawTarget = webgl.createDrawTarget();
         this.colorTarget = webgl.createRenderTarget(width, height, true, 'uint8', 'linear');
         this.transparentColorTarget = webgl.createRenderTarget(width, height, false, 'uint8', 'linear');
 
@@ -198,8 +198,10 @@ export class DrawPass {
                 const dpoitTextures = this.dpoit.bindDualDepthPeeling();
                 renderer.renderDpoitTransparent(scene.primitives, camera, this.depthTextureOpaque, dpoitTextures);
 
-                target.bind();
-                this.dpoit.renderBlendBack();
+                if (iterations > 1) {
+                    target.bind();
+                    this.dpoit.renderBlendBack();
+                }
                 if (isTimingMode) this.webgl.timer.markEnd('DpoitPass.layer');
             }
 
@@ -377,6 +379,7 @@ export class DrawPass {
         const antialiasingEnabled = AntialiasingPass.isEnabled(props.postprocessing);
         const markingEnabled = MarkingPass.isEnabled(props.marking);
         const dofEnabled = DofPass.isEnabled(props.postprocessing);
+        const bloomEnabled = BloomPass.isEnabled(props.postprocessing);
 
         const { x, y, width, height } = camera.viewport;
         renderer.setViewport(x, y, width, height);
@@ -446,7 +449,7 @@ export class DrawPass {
             needsTargetCopy = true;
         }
 
-        if (props.postprocessing.dof.name === 'on') {
+        if (dofEnabled && props.postprocessing.dof.name === 'on') {
             const input = AntialiasingPass.isEnabled(props.postprocessing)
                 ? this.antialiasing.target.texture
                 : PostprocessingPass.isEnabled(props.postprocessing)
@@ -469,7 +472,7 @@ export class DrawPass {
             }
         }
 
-        if (props.postprocessing.bloom.name === 'on') {
+        if (bloomEnabled && props.postprocessing.bloom.name === 'on') {
             const emissiveBloom = props.postprocessing.bloom.params.mode === 'emissive';
 
             if (emissiveBloom && scene.emissiveAverage > 0) {
@@ -493,7 +496,7 @@ export class DrawPass {
         const { renderer, camera, scene, helper } = ctx;
 
         this.postprocessing.setTransparentBackground(props.transparentBackground);
-        const transparentBackground = props.transparentBackground || this.postprocessing.background.isEnabled(props.postprocessing.background);
+        const transparentBackground = props.transparentBackground || this.postprocessing.background.isEnabled(props.postprocessing);
 
         renderer.setTransparentBackground(transparentBackground);
         renderer.setDrawingBufferSize(this.colorTarget.getWidth(), this.colorTarget.getHeight());

src/mol-canvas3d/passes/fxaa.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -88,7 +88,7 @@ export class FxaaPass {
         if (target) {
             target.bind();
         } else {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         }
         this.updateState(viewport);
         this.renderable.render();

src/mol-canvas3d/passes/hi-z.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -20,7 +20,7 @@ import { Camera } from '../camera';
 import { Viewport } from '../camera/util';
 import { DrawPass } from './draw';
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
-import { getBuffer } from '../../mol-gl/webgl/buffer';
+import { PixelPackBuffer } from '../../mol-gl/webgl/buffer';
 
 // avoiding namespace lookup improved performance in Chrome (Aug 2020)
 const v3transformMat4 = Vec3.transformMat4;
@@ -128,7 +128,7 @@ export class HiZPass {
 
     private readonly levelData: LevelData = [];
     private readonly fb: Framebuffer;
-    private readonly buf: WebGLBuffer;
+    private readonly buf: PixelPackBuffer;
     private readonly tex: Texture;
     private readonly renderable: HiZRenderable;
     private readonly supported: boolean;
@@ -221,10 +221,7 @@ export class HiZPass {
         const hw = this.tex.getWidth();
         const hh = this.tex.getHeight();
 
-        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.buf);
-        gl.bufferData(gl.PIXEL_PACK_BUFFER, this.buffer.byteLength, gl.STREAM_READ);
-        gl.readPixels(0, 0, hw, hh, gl.RED, gl.FLOAT, 0);
-        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        this.buf.read(0, 0, hw, hh);
 
         this.sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
         gl.flush();
@@ -249,9 +246,7 @@ export class HiZPass {
             this.frameLag += 1;
             // console.log(`waiting for buffer data for ${this.frameLag} frames`);
         } else {
-            gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.buf);
-            gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, this.buffer);
-            gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+            this.buf.getSubData(this.buffer);
             // console.log(`got buffer data after ${this.frameLag + 1} frames`);
             gl.deleteSync(this.sync);
             this.sync = null;
@@ -510,6 +505,16 @@ export class HiZPass {
 
     //
 
+    reset() {
+        this.sync = null;
+        this.ready = false;
+        this.frameLag = 0;
+        this.levelData.length = 0;
+
+        const { x, y, width, height } = this.viewport;
+        this.setViewport(x, y, width, height);
+    }
+
     dispose() {
         if (!this.supported) return;
 
@@ -517,7 +522,7 @@ export class HiZPass {
 
         this.fb.destroy();
         this.tex.destroy();
-        this.webgl.gl.deleteBuffer(this.buf);
+        this.buf.destroy();
         this.renderable.dispose();
 
         for (const td of this.levelData) {
@@ -527,6 +532,8 @@ export class HiZPass {
     }
 
     constructor(private webgl: WebGLContext, private drawPass: DrawPass, canvas: HTMLCanvasElement | undefined, props: Partial<HiZProps>) {
+        this.props = { ...PD.getDefaultValues(HiZParams), ...props };
+
         const { gl, extensions } = webgl;
         if (!isWebGL2(gl) || !extensions.colorBufferFloat) {
             if (isDebugMode) {
@@ -552,8 +559,7 @@ export class HiZPass {
         }
 
         this.supported = true;
-        this.props = { ...PD.getDefaultValues(HiZParams), ...props };
-        this.buf = getBuffer(gl);
+        this.buf = webgl.resources.pixelPack('alpha', 'float');
         this.renderable = createHiZRenderable(webgl, this.drawPass.depthTextureOpaque);
 
         if (isDebugMode && canvas) {

src/mol-canvas3d/passes/illumination.ts

@@ -33,6 +33,8 @@ import { JitterVectors, MultiSampleProps } from './multi-sample';
 import { compose_frag as multiSample_compose_frag } from '../../mol-gl/shader/compose.frag';
 import { clamp, lerp } from '../../mol-math/interpolate';
 import { SsaoProps } from './ssao';
+import { OutlinePass } from './outline';
+import { BloomPass } from './bloom';
 
 type Props = {
     transparentBackground: boolean;
@@ -169,13 +171,15 @@ export class IlluminationPass {
                 const dpoitTextures = this.drawPass.dpoit.bind();
                 renderer.renderDpoitTransparent(scene.primitives, camera, this.drawPass.depthTextureOpaque, dpoitTextures);
 
-                for (let i = 0, il = props.dpoitIterations; i < il; i++) {
+                for (let i = 0, iterations = props.dpoitIterations; i < iterations; i++) {
                     if (isTimingMode) this.webgl.timer.mark('DpoitPass.layer');
                     const dpoitTextures = this.drawPass.dpoit.bindDualDepthPeeling();
                     renderer.renderDpoitTransparent(scene.primitives, camera, this.drawPass.depthTextureOpaque, dpoitTextures);
 
-                    this.transparentTarget.bind();
-                    this.drawPass.dpoit.renderBlendBack();
+                    if (iterations > 1) {
+                        this.transparentTarget.bind();
+                        this.drawPass.dpoit.renderBlendBack();
+                    }
                     if (isTimingMode) this.webgl.timer.markEnd('DpoitPass.layer');
                 }
 
@@ -313,8 +317,11 @@ export class IlluminationPass {
 
         const orthographic = camera.state.mode === 'orthographic' ? 1 : 0;
 
-        const outlinesEnabled = props.postprocessing.outline.name === 'on' && !props.illumination.ignoreOutline;
+        const antialiasingEnabled = AntialiasingPass.isEnabled(props.postprocessing);
+        const outlinesEnabled = OutlinePass.isEnabled(props.postprocessing) && !props.illumination.ignoreOutline;
         const occlusionEnabled = PostprocessingPass.isTransparentSsaoEnabled(scene, props.postprocessing);
+        const bloomEnabled = BloomPass.isEnabled(props.postprocessing);
+        const dofEnabled = DofPass.isEnabled(props.postprocessing);
 
         const markingEnabled = MarkingPass.isEnabled(props.marking);
         const hasTransparent = scene.opacityAverage < 1;
@@ -327,7 +334,7 @@ export class IlluminationPass {
             ValueCell.update(this.composeRenderable.values.dOutlineEnable, outlinesEnabled);
         }
 
-        if (props.postprocessing.outline.name === 'on') {
+        if (outlinesEnabled && props.postprocessing.outline.name === 'on') {
             const { transparentOutline, outlineScale } = this.drawPass.postprocessing.outline.update(camera, props.postprocessing.outline.params, this.drawPass.depthTargetTransparent.texture, this.drawPass.depthTextureOpaque);
             this.drawPass.postprocessing.outline.render();
 
@@ -348,7 +355,7 @@ export class IlluminationPass {
             ValueCell.update(this.composeRenderable.values.dOcclusionEnable, occlusionEnabled);
         }
 
-        if (props.postprocessing.occlusion.name === 'on') {
+        if (occlusionEnabled && props.postprocessing.occlusion.name === 'on') {
             ValueCell.update(this.composeRenderable.values.uOcclusionColor, Color.toVec3Normalized(this.composeRenderable.values.uOcclusionColor.ref.value, props.postprocessing.occlusion.params.color));
         }
 
@@ -370,9 +377,9 @@ export class IlluminationPass {
 
         // background
 
-        const _toDrawingBuffer = toDrawingBuffer && !AntialiasingPass.isEnabled(props.postprocessing) && props.postprocessing.dof.name === 'off';
+        const _toDrawingBuffer = toDrawingBuffer && !antialiasingEnabled && !dofEnabled;
         if (_toDrawingBuffer) {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         } else {
             this.tracing.composeTarget.bind();
         }
@@ -384,7 +391,7 @@ export class IlluminationPass {
 
         // compose
 
-        ValueCell.updateIfChanged(this.composeRenderable.values.uTransparentBackground, props.transparentBackground || this.drawPass.postprocessing.background.isEnabled(props.postprocessing.background));
+        ValueCell.updateIfChanged(this.composeRenderable.values.uTransparentBackground, props.transparentBackground || this.drawPass.postprocessing.background.isEnabled(props.postprocessing));
         if (this.composeRenderable.values.dDenoise.ref.value !== props.illumination.denoise) {
             ValueCell.update(this.composeRenderable.values.dDenoise, props.illumination.denoise);
             needsUpdateCompose = true;
@@ -421,8 +428,8 @@ export class IlluminationPass {
         let targetIsDrawingbuffer = false;
         let swapTarget = this.outputTarget;
 
-        if (AntialiasingPass.isEnabled(props.postprocessing)) {
-            const _toDrawingBuffer = toDrawingBuffer && props.postprocessing.dof.name === 'off';
+        if (antialiasingEnabled) {
+            const _toDrawingBuffer = toDrawingBuffer && !dofEnabled;
             this.drawPass.antialiasing.render(camera, this.tracing.composeTarget.texture, _toDrawingBuffer ? true : this.outputTarget, props.postprocessing);
 
             if (_toDrawingBuffer) {
@@ -433,13 +440,13 @@ export class IlluminationPass {
             }
         }
 
-        if (props.postprocessing.bloom.name === 'on') {
-            const _toDrawingBuffer = (toDrawingBuffer && props.postprocessing.dof.name === 'off') || targetIsDrawingbuffer;
+        if (bloomEnabled && props.postprocessing.bloom.name === 'on') {
+            const _toDrawingBuffer = (toDrawingBuffer && !dofEnabled) || targetIsDrawingbuffer;
             this.drawPass.bloom.update(this.tracing.colorTextureOpaque, this.tracing.normalTextureOpaque, this.drawPass.depthTextureOpaque, props.postprocessing.bloom.params);
             this.drawPass.bloom.render(camera.viewport, _toDrawingBuffer ? undefined : this._colorTarget);
         }
 
-        if (props.postprocessing.dof.name === 'on') {
+        if (dofEnabled && props.postprocessing.dof.name === 'on') {
             const _toDrawingBuffer = toDrawingBuffer || targetIsDrawingbuffer;
             this.drawPass.dof.update(camera, this._colorTarget.texture, this.drawPass.depthTextureOpaque, this.drawPass.depthTargetTransparent.texture, props.postprocessing.dof.params, scene.boundingSphereVisible);
             this.drawPass.dof.render(camera.viewport, _toDrawingBuffer ? undefined : swapTarget);
@@ -530,7 +537,7 @@ export class IlluminationPass {
         this.prevSampleIndex = sampleIndex;
 
         if (toDrawingBuffer) {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         } else {
             this.multiSampleAccumulateTarget.bind();
         }

src/mol-canvas3d/passes/marking.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2021-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2021-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -121,17 +121,13 @@ export class MarkingPass {
         ValueCell.updateIfChanged(overlayValues.uSelectEdgeStrength, selectEdgeStrength);
     }
 
-    render(viewport: Viewport, target: RenderTarget | undefined) {
+    render(viewport: Viewport, target: RenderTarget) {
         if (isTimingMode) this.webgl.timer.mark('MarkingPass.render');
         this.edgesTarget.bind();
         this.setEdgeState(viewport);
         this.edge.render();
 
-        if (target) {
-            target.bind();
-        } else {
-            this.webgl.unbindFramebuffer();
-        }
+        target.bind();
         this.setOverlayState(viewport);
         this.overlay.render();
         if (isTimingMode) this.webgl.timer.markEnd('MarkingPass.render');

src/mol-canvas3d/passes/multi-sample.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -120,7 +120,7 @@ export class MultiSamplePass {
 
     private bindOutputTarget(toDrawingBuffer: boolean) {
         if (toDrawingBuffer) {
-            this.webgl.unbindFramebuffer();
+            this.webgl.bindDrawingBuffer();
         } else {
             this.colorTarget.bind();
         }