renaming

CHANGELOG.md

@@ -26,7 +26,10 @@ Note that since we don't clearly distinguish between a public and private interf
   - Add easing support in camera transtion
 - Non-covalent interactions: water bridge support
 - Download Structure From AlphaFoldDB allows IDs with version suffix (version is ignored)
-- Add `loadUrl` method and GET params to Viewer app
+- Add `extensions/plugin` with several QoL improvements
+  - Standalone useful loading functions previously avaiable only in the `Viewer` class
+  - Standalong plugin interactivity helper function previously available only via the `Viewer` class
+  - View models (and hooks) for more straightforward usafe in React (and in other UI libraries)
 
 ## [v5.9.0] - 2026-05-03
 - Fix edge case when `PluginSpec.animations` is empty

src/apps/viewer/app.ts

@@ -7,53 +7,30 @@
  * @author Adam Midlik <midlik@gmail.com>
  */
 
-import { AssemblySymmetryConfig } from '../../extensions/assembly-symmetry';
-import { loadMVSData, loadMVSX } from '../../extensions/mvs/components/formats';
-import { loadMVS, MolstarLoadingExtension } from '../../extensions/mvs/load';
-import { MVSData } from '../../extensions/mvs/mvs-data';
-import { StringLike } from '../../mol-io/common/string-like';
-import { Structure, StructureElement } from '../../mol-model/structure';
+import { MolstarLoadingExtension } from '../../extensions/mvs/load';
+import { applyStructureInteractivity, StructureInteractivityOptions } from '../../extensions/plugin/interactivity';
+import * as loaders from '../../extensions/plugin/loaders';
 import { Volume } from '../../mol-model/volume';
-import { DownloadFile, OpenFiles } from '../../mol-plugin-state/actions/file';
-import { DownloadStructure, PdbDownloadProvider } from '../../mol-plugin-state/actions/structure';
-import { DownloadDensity } from '../../mol-plugin-state/actions/volume';
-import { PresetTrajectoryHierarchy } from '../../mol-plugin-state/builder/structure/hierarchy-preset';
-import { StructureRepresentationPresetProvider } from '../../mol-plugin-state/builder/structure/representation-preset';
 import { PluginComponent } from '../../mol-plugin-state/component';
-import { BuiltInCoordinatesFormat } from '../../mol-plugin-state/formats/coordinates';
-import { BuiltInTopologyFormat } from '../../mol-plugin-state/formats/topology';
 import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
 import { BuildInVolumeFormat } from '../../mol-plugin-state/formats/volume';
-import { createVolumeRepresentationParams } from '../../mol-plugin-state/helpers/volume-representation-params';
-import { PluginStateObject } from '../../mol-plugin-state/objects';
-import { StateTransforms } from '../../mol-plugin-state/transforms';
-import { TrajectoryFromModelAndCoordinates } from '../../mol-plugin-state/transforms/model';
 import { createPluginUI } from '../../mol-plugin-ui';
 import { PluginUIContext } from '../../mol-plugin-ui/context';
 import { renderReact18 } from '../../mol-plugin-ui/react18';
-import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
-import { PluginBehaviors } from '../../mol-plugin/behavior';
-import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginConfig } from '../../mol-plugin/config';
 import { PluginState } from '../../mol-plugin/state';
-import { MolScriptBuilder } from '../../mol-script/language/builder';
-import { Expression } from '../../mol-script/language/expression';
-import { StateObjectSelector } from '../../mol-state';
-import { Task } from '../../mol-task';
-import { Asset } from '../../mol-util/assets';
 import { Color } from '../../mol-util/color';
-import { ExtensionMap } from './extensions';
+import { decodeColor } from '../../mol-util/color/utils';
+import '../../mol-util/polyfill';
 import { DefaultViewerOptions, ViewerOptions } from './options';
+import { createViewerSpec } from './plugin-spec';
+import { ViewerAutoPreset } from './presets';
 
 export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
 export { consoleStats, isDebugMode, isProductionMode, isTimingMode, setDebugMode, setProductionMode, setTimingMode } from '../../mol-util/debug';
 
-import { decodeColor } from '../../mol-util/color/utils';
-import '../../mol-util/polyfill';
-import { ViewerAutoPreset } from './presets';
-import { CameraFocusLociOptions } from '../../mol-plugin-state/manager/camera';
-import { PluginSpec } from '../../mol-plugin/spec';
-import { NoPrimaryFocusLociBindings } from '../../mol-plugin/behavior/dynamic/camera';
+// re-export for backwards compatibility, but these should ideally be imported from the plugin extension directly
+// TODO: consider removing these in v6.0
+export type { LoadStructureOptions, LoadTrajectoryParams, VolumeIsovalueInfo } from '../../extensions/plugin/loaders';
 
 export class Viewer {
     private _events = new PluginComponent();
@@ -64,102 +41,7 @@ export class Viewer {
     }
 
     static async create(elementOrId: string | HTMLElement, options: Partial<ViewerOptions> = {}) {
-        const definedOptions = {} as any;
-        // filter for defined properies only so the default values
-        // are property applied
-        for (const p of Object.keys(options) as (keyof ViewerOptions)[]) {
-            if (options[p] !== void 0) definedOptions[p] = options[p];
-        }
-
-        const o: ViewerOptions = { ...DefaultViewerOptions, ...definedOptions };
-        const defaultSpec = DefaultPluginUISpec();
-
-        const disabledExtension = new Set(o.disabledExtensions ?? []);
-        let baseBehaviors = defaultSpec.behaviors;
-
-        if (o.viewportFocusBehavior === 'disabled') {
-            baseBehaviors = baseBehaviors.filter(b =>
-                b.transformer !== PluginBehaviors.Camera.FocusLoci
-                && b.transformer !== PluginBehaviors.Representation.FocusLoci
-            );
-        } else if (o.viewportFocusBehavior === 'secondary-zoom') {
-            baseBehaviors = baseBehaviors.filter(b =>
-                b.transformer !== PluginBehaviors.Camera.FocusLoci
-                && b.transformer !== PluginBehaviors.Representation.FocusLoci
-            );
-
-            baseBehaviors.push(PluginSpec.Behavior(PluginBehaviors.Camera.FocusLoci, {
-                bindings: NoPrimaryFocusLociBindings
-            }));
-        }
-
-        const spec: PluginUISpec = {
-            canvas3d: {
-                ...defaultSpec.canvas3d,
-            },
-            actions: defaultSpec.actions,
-            behaviors: [
-                ...baseBehaviors,
-                ...o.extensions.filter(e => !disabledExtension.has(e)).map(e => ExtensionMap[e]),
-            ],
-            animations: [...defaultSpec.animations || []],
-            customParamEditors: defaultSpec.customParamEditors,
-            customFormats: o?.customFormats,
-            layout: {
-                initial: {
-                    isExpanded: o.layoutIsExpanded,
-                    showControls: o.layoutShowControls,
-                    controlsDisplay: o.layoutControlsDisplay,
-                    regionState: {
-                        bottom: 'full',
-                        left: o.collapseLeftPanel ? 'collapsed' : 'full',
-                        right: o.collapseRightPanel ? 'hidden' : 'full',
-                        top: 'full',
-                    }
-                },
-            },
-            components: {
-                ...defaultSpec.components,
-                controls: {
-                    ...defaultSpec.components?.controls,
-                    top: o.layoutShowSequence ? undefined : 'none',
-                    bottom: o.layoutShowLog ? undefined : 'none',
-                    left: o.layoutShowLeftPanel ? undefined : 'none',
-                },
-                remoteState: o.layoutShowRemoteState ? 'default' : 'none',
-            },
-            config: [
-                [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
-                [PluginConfig.General.PixelScale, o.pixelScale],
-                [PluginConfig.General.PickScale, o.pickScale],
-                [PluginConfig.General.Transparency, o.transparency],
-                [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
-                [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
-                [PluginConfig.General.PowerPreference, o.powerPreference],
-                [PluginConfig.General.ResolutionMode, o.resolutionMode],
-                [PluginConfig.Viewport.ShowReset, o.viewportShowReset],
-                [PluginConfig.Viewport.ShowScreenshotControls, o.viewportShowScreenshotControls],
-                [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
-                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
-                [PluginConfig.Viewport.ShowToggleFullscreen, o.viewportShowToggleFullscreen],
-                [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
-                [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
-                [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],
-                [PluginConfig.Viewport.ShowTrajectoryControls, o.viewportShowTrajectoryControls],
-                [PluginConfig.State.DefaultServer, o.pluginStateServer],
-                [PluginConfig.State.CurrentServer, o.pluginStateServer],
-                [PluginConfig.VolumeStreaming.DefaultServer, o.volumeStreamingServer],
-                [PluginConfig.VolumeStreaming.Enabled, !o.volumeStreamingDisabled],
-                [PluginConfig.Download.DefaultPdbProvider, o.pdbProvider],
-                [PluginConfig.Download.DefaultEmdbProvider, o.emdbProvider],
-                [PluginConfig.Structure.DefaultRepresentationPreset, ViewerAutoPreset.id],
-                [PluginConfig.Structure.SaccharideCompIdMapType, o.saccharideCompIdMapType],
-                [AssemblySymmetryConfig.DefaultServerType, o.rcsbAssemblySymmetryDefaultServerType],
-                [AssemblySymmetryConfig.DefaultServerUrl, o.rcsbAssemblySymmetryDefaultServerUrl],
-                [AssemblySymmetryConfig.ApplyColors, o.rcsbAssemblySymmetryApplyColors],
-                ...(o.config ?? []),
-            ]
-        };
+        const spec = createViewerSpec(options);
 
         const element = typeof elementOrId === 'string'
             ? document.getElementById(elementOrId)
@@ -176,9 +58,9 @@ export class Viewer {
             }
         });
 
-        plugin.canvas3d?.setProps({ illumination: { enabled: o.illumination } });
-        if (o.viewportBackgroundColor) {
-            const backgroundColor = decodeColor(o.viewportBackgroundColor);
+        plugin.canvas3d?.setProps({ illumination: { enabled: options.illumination ?? DefaultViewerOptions.illumination } });
+        if (options.viewportBackgroundColor ?? DefaultViewerOptions.viewportBackgroundColor) {
+            const backgroundColor = decodeColor(options.viewportBackgroundColor ?? DefaultViewerOptions.viewportBackgroundColor);
             if (typeof backgroundColor === 'number') {
                 plugin.canvas3d?.setProps({ renderer: { backgroundColor } });
             }
@@ -193,63 +75,27 @@ export class Viewer {
     subscribe = this._events.subscribe.bind(this._events);
 
     setRemoteSnapshot(id: string) {
-        const url = `${this.plugin.config.get(PluginConfig.State.CurrentServer)}/get/${id}`;
-        return PluginCommands.State.Snapshots.Fetch(this.plugin, { url });
+        return loaders.setRemoteSnapshot(this.plugin, id);
     }
 
     loadSnapshotFromUrl(url: string, type: PluginState.SnapshotType) {
-        return PluginCommands.State.Snapshots.OpenUrl(this.plugin, { url, type });
+        return loaders.loadSnapshotFromUrl(this.plugin, url, type);
     }
 
-    loadStructureFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions & { label?: string }) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'url',
-                params: {
-                    url: Asset.Url(url),
-                    format: format as any,
-                    isBinary,
-                    label: options?.label,
-                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
-                }
-            }
-        }));
+    loadStructureFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: loaders.LoadStructureOptions & { label?: string }) {
+        return loaders.loadStructureFromUrl(this.plugin, url, format, isBinary, options);
     }
 
-    async loadAllModelsOrAssemblyFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
-        const plugin = this.plugin;
-
-        const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
-        const trajectory = await plugin.builders.structure.parseTrajectory(data, format);
-
-        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'all-models', { useDefaultIfSingleModel: true, representationPresetParams: options?.representationParams });
+    loadAllModelsOrAssemblyFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: loaders.LoadStructureOptions) {
+        return loaders.loadAllModelsOrAssemblyFromUrl(this.plugin, url, format, isBinary, options);
     }
 
-    async loadStructureFromData(data: string | number[], format: BuiltInTrajectoryFormat, options?: { dataLabel?: string }) {
-        const _data = await this.plugin.builders.data.rawData({ data, label: options?.dataLabel });
-        const trajectory = await this.plugin.builders.structure.parseTrajectory(_data, format);
-        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+    loadStructureFromData(data: string | number[], format: BuiltInTrajectoryFormat, options?: { dataLabel?: string }) {
+        return loaders.loadStructureFromData(this.plugin, data, format, options);
     }
 
-    loadPdb(pdb: string, options?: LoadStructureOptions) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        const provider = this.plugin.config.get(PluginConfig.Download.DefaultPdbProvider)!;
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'pdb' as const,
-                params: {
-                    provider: {
-                        id: pdb,
-                        server: {
-                            name: provider,
-                            params: PdbDownloadProvider[provider].defaultValue as any
-                        }
-                    },
-                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
-                }
-            }
-        }));
+    loadPdb(pdb: string, options?: loaders.LoadStructureOptions) {
+        return loaders.loadPdb(this.plugin, pdb, options);
     }
 
     /**
@@ -260,67 +106,19 @@ export class Viewer {
     }
 
     loadPdbIhm(pdbIhm: string) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'pdb-ihm' as const,
-                params: {
-                    provider: {
-                        id: pdbIhm,
-                        encoding: 'bcif',
-                    },
-                    options: params.source.params.options,
-                }
-            }
-        }));
+        return loaders.loadPdbIhm(this.plugin, pdbIhm);
     }
 
     loadEmdb(emdb: string, options?: { detail?: number }) {
-        const provider = this.plugin.config.get(PluginConfig.Download.DefaultEmdbProvider)!;
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadDensity, {
-            source: {
-                name: 'pdb-emd-ds' as const,
-                params: {
-                    provider: {
-                        id: emdb,
-                        server: provider,
-                    },
-                    detail: options?.detail ?? 3,
-                }
-            }
-        }));
+        return loaders.loadEmdb(this.plugin, emdb, options);
     }
 
     loadAlphaFoldDb(afdb: string) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'alphafolddb' as const,
-                params: {
-                    provider: {
-                        id: afdb,
-                        encoding: 'bcif'
-                    },
-                    options: {
-                        ...params.source.params.options,
-                        representation: 'preset-structure-representation-ma-quality-assessment-plddt'
-                    },
-                }
-            }
-        }));
+        return loaders.loadAlphaFoldDb(this.plugin, afdb);
     }
 
     loadModelArchive(id: string) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'modelarchive' as const,
-                params: {
-                    id,
-                    options: params.source.params.options,
-                }
-            }
-        }));
+        return loaders.loadModelArchive(this.plugin, id);
     }
 
     /**
@@ -362,76 +160,12 @@ export class Viewer {
             isLazy: true
         });
      */
-    async loadVolumeFromUrl({ url, format, isBinary }: { url: string, format: BuildInVolumeFormat, isBinary: boolean }, isovalues: VolumeIsovalueInfo[], options?: { entryId?: string | string[], isLazy?: boolean }) {
-        const plugin = this.plugin;
-
-        if (!plugin.dataFormats.get(format)) {
-            throw new Error(`Unknown density format: ${format}`);
-        }
-
-        if (options?.isLazy) {
-            const update = this.plugin.build();
-            update.toRoot().apply(StateTransforms.Data.LazyVolume, {
-                url,
-                format,
-                entryId: options?.entryId,
-                isBinary,
-                isovalues: isovalues.map(v => ({ alpha: 1, volumeIndex: 0, ...v }))
-            });
-            return update.commit();
-        }
-
-        return plugin.dataTransaction(async () => {
-            const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
-
-            const parsed = await plugin.dataFormats.get(format)!.parse(plugin, data, { entryId: options?.entryId });
-            const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
-            if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
-
-            const repr = plugin.build();
-            for (const iso of isovalues) {
-                const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[iso.volumeIndex ?? 0] ?? parsed.volume;
-                const volumeData = volume.cell!.obj!.data;
-                repr
-                    .to(volume)
-                    .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
-                        type: 'isosurface',
-                        typeParams: { alpha: iso.alpha ?? 1, isoValue: Volume.adjustedIsoValue(volumeData, iso.value, iso.type) },
-                        color: 'uniform',
-                        colorParams: { value: iso.color }
-                    }));
-            }
-
-            await repr.commit();
-        });
+    loadVolumeFromUrl({ url, format, isBinary }: { url: string, format: BuildInVolumeFormat, isBinary: boolean }, isovalues: loaders.VolumeIsovalueInfo[], options?: { entryId?: string | string[], isLazy?: boolean }) {
+        return loaders.loadVolumeFromUrl(this.plugin, { url, format, isBinary }, isovalues, options);
     }
 
     loadFullResolutionEMDBMap(emdbId: string, options: { isoValue: Volume.IsoValue, color?: Color }) {
-        const plugin = this.plugin;
-        const numericId = parseInt(emdbId.toUpperCase().replace('EMD-', ''));
-        const url = `https://ftp.ebi.ac.uk/pub/databases/emdb/structures/EMD-${numericId}/map/emd_${numericId}.map.gz`;
-
-        return plugin.dataTransaction(async () => {
-            const data = await plugin.build().toRoot()
-                .apply(StateTransforms.Data.Download, { url, isBinary: true, label: emdbId }, { state: { isGhost: true } })
-                .apply(StateTransforms.Data.DeflateData)
-                .commit();
-
-            const parsed = await plugin.dataFormats.get('ccp4')!.parse(plugin, data, { entryId: emdbId });
-            const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
-            if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
-
-            const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[0] ?? parsed.volume;
-            await plugin.build()
-                .to(volume)
-                .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
-                    type: 'isosurface',
-                    typeParams: { alpha: 1, isoValue: options.isoValue },
-                    color: 'uniform',
-                    colorParams: { value: options.color ?? Color(0x33BB33) }
-                }))
-                .commit();
-        });
+        return loaders.loadFullResolutionEMDBMap(this.plugin, emdbId, options);
     }
 
     /**
@@ -442,96 +176,23 @@ export class Viewer {
      *      preset: 'all-models' // or 'default'
      *  });
      */
-    async loadTrajectory(params: LoadTrajectoryParams) {
-        const plugin = this.plugin;
-
-        let model: StateObjectSelector;
-
-        if (params.model.kind === 'model-data' || params.model.kind === 'model-url') {
-            const data = params.model.kind === 'model-data'
-                ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
-                : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
-
-            const trajectory = await plugin.builders.structure.parseTrajectory(data, params.model.format ?? 'mmcif');
-            model = await plugin.builders.structure.createModel(trajectory);
-        } else {
-            const data = params.model.kind === 'topology-data'
-                ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
-                : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
-
-            const provider = plugin.dataFormats.get(params.model.format);
-            const parsed = await provider!.parse(plugin, data);
-            model = parsed.topology;
-        }
-
-        const data = params.coordinates.kind === 'coordinates-data'
-            ? await plugin.builders.data.rawData({ data: params.coordinates.data, label: params.coordinatesLabel })
-            : await plugin.builders.data.download({ url: params.coordinates.url, isBinary: params.coordinates.isBinary, label: params.coordinatesLabel });
-
-        const provider = plugin.dataFormats.get(params.coordinates.format);
-        const coords = await provider!.parse(plugin, data);
-
-        const trajectory = await plugin.build().toRoot()
-            .apply(TrajectoryFromModelAndCoordinates, {
-                modelRef: model.ref,
-                coordinatesRef: coords.ref
-            }, { dependsOn: [model.ref, coords.ref] })
-            .commit();
-
-        const preset = await plugin.builders.structure.hierarchy.applyPreset(trajectory, params.preset ?? 'default');
-
-        return { model, coords, preset };
+    loadTrajectory(params: loaders.LoadTrajectoryParams) {
+        return loaders.loadTrajectory(this.plugin, params);
     }
 
-    async loadMvsFromUrl(url: string, format: 'mvsj' | 'mvsx', options?: { appendSnapshots?: boolean, keepCamera?: boolean, keepCameraOrientation?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
-        if (format === 'mvsj') {
-            const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'string' }));
-            const mvsData = MVSData.fromMVSJ(StringLike.toString(data));
-            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: url, ...options });
-        } else if (format === 'mvsx') {
-            const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'binary' }));
-            await this.plugin.runTask(Task.create('Load MVSX file', async ctx => {
-                const parsed = await loadMVSX(this.plugin, ctx, data, { doNotClearAssets: options?.appendSnapshots });
-                await loadMVS(this.plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
-            }));
-        } else {
-            throw new Error(`Unknown MolViewSpec format: ${format}`);
-        }
+    loadMvsFromUrl(url: string, format: 'mvsj' | 'mvsx', options?: { appendSnapshots?: boolean, keepCamera?: boolean, keepCameraOrientation?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+        return loaders.loadMvsFromUrl(this.plugin, url, format, options);
     }
 
     /** Load MolViewSpec from `data`.
      * If `format` is 'mvsj', `data` must be a string or a Uint8Array containing a UTF8-encoded string.
      * If `format` is 'mvsx', `data` must be a Uint8Array or a string containing base64-encoded binary data prefixed with 'base64,'. */
     loadMvsData(data: string | Uint8Array<ArrayBuffer>, format: 'mvsj' | 'mvsx', options?: { appendSnapshots?: boolean, keepCamera?: boolean, keepCameraOrientation?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
-        return loadMVSData(this.plugin, data, format, options);
+        return loaders.loadMvsData(this.plugin, data, format, options);
     }
 
     loadFiles(files: File[]) {
-        const sessions = files.filter(f => {
-            const fn = f.name.toLowerCase();
-            return fn.endsWith('.molx') || fn.endsWith('.molj');
-        });
-
-        if (sessions.length > 0) {
-            return PluginCommands.State.Snapshots.OpenFile(this.plugin, { file: sessions[0] });
-        } else {
-            return this.plugin.runTask(this.plugin.state.data.applyAction(OpenFiles, {
-                files: files.map(f => Asset.File(f)),
-                format: { name: 'auto', params: {} },
-                visuals: true
-            }));
-        }
-    }
-
-    loadUrl(url: string, format: string, isBinary = false) {
-        return this.plugin.runTask(Task.create('Load URL', async taskCtx => {
-            await this.plugin.state.data.applyAction(DownloadFile, {
-                url: Asset.Url(url),
-                format,
-                isBinary,
-                visuals: true
-            }).runInContext(taskCtx);
-        }));
+        return loaders.loadFiles(this.plugin, files);
     }
 
     handleResize() {
@@ -546,82 +207,12 @@ export class Viewer {
      * If neither `expression` nor `elements` are provided, all selections/highlights
      * will be cleared based on the specified `action`.
      */
-    structureInteractivity({ expression, elements, action: action_, applyGranularity = false, filterStructure, focusOptions }: {
-        expression?: (queryBuilder: typeof MolScriptBuilder) => Expression,
-        elements?: StructureElement.Schema,
-        action: 'highlight' | 'select' | 'focus' | ('highlight' | 'select' | 'focus')[],
-        applyGranularity?: boolean,
-        filterStructure?: (structure: Structure) => boolean,
-        focusOptions?: Partial<CameraFocusLociOptions>
-    }) {
-        const plugin = this.plugin;
-        const actions = Array.isArray(action_) ? action_ : [action_];
-
-        if (!expression && !elements) {
-            if (actions.includes('select')) {
-                plugin.managers.interactivity.lociSelects.deselectAll();
-            }
-            if (actions.includes('highlight')) {
-                plugin.managers.interactivity.lociHighlights.clearHighlights();
-            }
-            return;
-        }
-
-        if (actions.includes('select')) {
-            plugin.managers.interactivity.lociSelects.deselectAll();
-        }
-
-        const structures = this.plugin.state.data.selectQ(Q => Q.rootsOfType(PluginStateObject.Molecule.Structure));
-        let focused = false;
-        for (const s of structures) {
-            if (!s.obj?.data) continue;
-
-            if (filterStructure && !filterStructure(s.obj.data)) continue;
-
-            const loci = expression
-                ? StructureElement.Loci.fromExpression(s.obj.data, expression)
-                : StructureElement.Loci.fromSchema(s.obj.data, elements!);
-
-            for (const action of actions) {
-                if (action === 'select') {
-                    plugin.managers.interactivity.lociSelects.select({ loci }, applyGranularity);
-                } else if (action === 'highlight') {
-                    plugin.managers.interactivity.lociHighlights.highlight({ loci }, applyGranularity);
-                } else if (action === 'focus' && !StructureElement.Loci.isEmpty(loci) && !focused) {
-                    plugin.managers.camera.focusLoci(loci, focusOptions);
-                    focused = true;
-                    if (actions.length === 1) return; // if only focusing, focus the first matching structure and return immediately
-                }
-            }
-        }
+    structureInteractivity(options: StructureInteractivityOptions) {
+        return applyStructureInteractivity(this.plugin, options);
     }
 
     dispose() {
         this._events.dispose();
         this.plugin.dispose();
     }
-}
-
-export interface LoadStructureOptions {
-    representationParams?: StructureRepresentationPresetProvider.CommonParams
-}
-
-export interface VolumeIsovalueInfo {
-    type: 'absolute' | 'relative',
-    value: number,
-    color: Color,
-    alpha?: number,
-    volumeIndex?: number
-}
-
-export interface LoadTrajectoryParams {
-    model: { kind: 'model-url', url: string, format?: BuiltInTrajectoryFormat /* mmcif */, isBinary?: boolean }
-    | { kind: 'model-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format?: BuiltInTrajectoryFormat /* mmcif */ }
-    | { kind: 'topology-url', url: string, format: BuiltInTopologyFormat, isBinary?: boolean }
-    | { kind: 'topology-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format: BuiltInTopologyFormat },
-    modelLabel?: string,
-    coordinates: { kind: 'coordinates-url', url: string, format: BuiltInCoordinatesFormat, isBinary?: boolean }
-    | { kind: 'coordinates-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format: BuiltInCoordinatesFormat },
-    coordinatesLabel?: string,
-    preset?: keyof PresetTrajectoryHierarchy
 }

src/apps/viewer/extensions.ts

@@ -30,6 +30,10 @@ import { PluginSpec } from '../../mol-plugin/spec';
 import { MVSData } from '../../extensions/mvs/mvs-data';
 import * as MVSUtil from '../../extensions/mvs/util';
 import { KinemageExtension } from '../../extensions/kinemage/behavior';
+import * as interactivity from '../../extensions/plugin/interactivity';
+import * as loaders from '../../extensions/plugin/loaders';
+import { PluginViewModel } from '../../extensions/plugin/view-model';
+import { PluginUIViewModel } from '../../extensions/plugin/ui-view-model';
 
 export const ExtensionMap = {
     // Mol* built-in extensions
@@ -70,5 +74,13 @@ export const PluginExtensions = {
         qualityAssessment: {
             config: MAQualityAssessmentConfig
         }
-    }
+    },
+    plugin: {
+        interactivity,
+        loaders,
+        models: {
+            PluginViewModel,
+            PluginUIViewModel,
+        },
+    },
 };

src/apps/viewer/index.html

@@ -129,11 +129,6 @@
                 var modelArchive = getParam('model-archive', '[^&]+').trim();
                 if (modelArchive) viewer.loadModelArchive(modelArchive);
 
-                var url = getParam('url', '[^&]+').trim();
-                var urlFormat = getParam('url-format', '[^&]+').trim() || undefined;
-                var urlIsBinary = getParam('url-is-binary', '[^&]+').trim() === '1';
-                if (url && urlFormat) viewer.loadUrl(url, urlFormat, urlIsBinary);
-
                 window.addEventListener('unload', () => {
                     // to aid GC
                     viewer.dispose();

src/apps/viewer/lib.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2025 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2025-2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
@@ -10,6 +10,7 @@ import { Volume } from '../../mol-model/volume';
 import { Shape, ShapeGroup } from '../../mol-model/shape';
 import * as LinearAlgebra3D from '../../mol-math/linear-algebra/3d';
 import { PluginContext } from '../../mol-plugin/context';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
 import { PluginConfig } from '../../mol-plugin/config';
 import { PluginBehavior } from '../../mol-plugin/behavior';
 import { DefaultPluginSpec, PluginSpec } from '../../mol-plugin/spec';
@@ -42,6 +43,7 @@ export const lib = {
     },
     plugin: {
         PluginContext,
+        PluginUIContext,
         PluginConfig,
         PluginBehavior,
         PluginSpec,

src/apps/viewer/plugin-spec.ts

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { AssemblySymmetryConfig } from '../../extensions/assembly-symmetry';
+import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
+import { PluginBehaviors } from '../../mol-plugin/behavior';
+import { PluginConfig } from '../../mol-plugin/config';
+import { ExtensionMap } from './extensions';
+import { DefaultViewerOptions, ViewerOptions } from './options';
+import { NoPrimaryFocusLociBindings } from '../../mol-plugin/behavior/dynamic/camera';
+import { PluginSpec } from '../../mol-plugin/spec';
+import { ViewerAutoPreset } from './presets';
+
+export function createViewerSpec(options: Partial<ViewerOptions> = {}): PluginUISpec {
+    const definedOptions = {} as any;
+    // filter for defined properies only so the default values
+    // are property applied
+    for (const p of Object.keys(options) as (keyof ViewerOptions)[]) {
+        if (options[p] !== void 0) definedOptions[p] = options[p];
+    }
+
+    const o: ViewerOptions = { ...DefaultViewerOptions, ...definedOptions };
+    const defaultSpec = DefaultPluginUISpec();
+
+    const disabledExtension = new Set(o.disabledExtensions ?? []);
+    let baseBehaviors = defaultSpec.behaviors;
+
+    if (o.viewportFocusBehavior === 'disabled') {
+        baseBehaviors = baseBehaviors.filter(b =>
+            b.transformer !== PluginBehaviors.Camera.FocusLoci
+            && b.transformer !== PluginBehaviors.Representation.FocusLoci
+        );
+    } else if (o.viewportFocusBehavior === 'secondary-zoom') {
+        baseBehaviors = baseBehaviors.filter(b =>
+            b.transformer !== PluginBehaviors.Camera.FocusLoci
+            && b.transformer !== PluginBehaviors.Representation.FocusLoci
+        );
+
+        baseBehaviors.push(PluginSpec.Behavior(PluginBehaviors.Camera.FocusLoci, {
+            bindings: NoPrimaryFocusLociBindings
+        }));
+    }
+
+    const spec: PluginUISpec = {
+        canvas3d: {
+            ...defaultSpec.canvas3d,
+        },
+        actions: defaultSpec.actions,
+        behaviors: [
+            ...baseBehaviors,
+            ...o.extensions.filter(e => !disabledExtension.has(e)).map(e => ExtensionMap[e]),
+        ],
+        animations: [...defaultSpec.animations || []],
+        customParamEditors: defaultSpec.customParamEditors,
+        customFormats: o?.customFormats,
+        layout: {
+            initial: {
+                isExpanded: o.layoutIsExpanded,
+                showControls: o.layoutShowControls,
+                controlsDisplay: o.layoutControlsDisplay,
+                regionState: {
+                    bottom: 'full',
+                    left: o.collapseLeftPanel ? 'collapsed' : 'full',
+                    right: o.collapseRightPanel ? 'hidden' : 'full',
+                    top: 'full',
+                }
+            },
+        },
+        components: {
+            ...defaultSpec.components,
+            controls: {
+                ...defaultSpec.components?.controls,
+                top: o.layoutShowSequence ? undefined : 'none',
+                bottom: o.layoutShowLog ? undefined : 'none',
+                left: o.layoutShowLeftPanel ? undefined : 'none',
+            },
+            remoteState: o.layoutShowRemoteState ? 'default' : 'none',
+        },
+        config: [
+            [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
+            [PluginConfig.General.PixelScale, o.pixelScale],
+            [PluginConfig.General.PickScale, o.pickScale],
+            [PluginConfig.General.Transparency, o.transparency],
+            [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
+            [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
+            [PluginConfig.General.PowerPreference, o.powerPreference],
+            [PluginConfig.General.ResolutionMode, o.resolutionMode],
+            [PluginConfig.Viewport.ShowReset, o.viewportShowReset],
+            [PluginConfig.Viewport.ShowScreenshotControls, o.viewportShowScreenshotControls],
+            [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
+            [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
+            [PluginConfig.Viewport.ShowToggleFullscreen, o.viewportShowToggleFullscreen],
+            [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
+            [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
+            [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],
+            [PluginConfig.Viewport.ShowTrajectoryControls, o.viewportShowTrajectoryControls],
+            [PluginConfig.State.DefaultServer, o.pluginStateServer],
+            [PluginConfig.State.CurrentServer, o.pluginStateServer],
+            [PluginConfig.VolumeStreaming.DefaultServer, o.volumeStreamingServer],
+            [PluginConfig.VolumeStreaming.Enabled, !o.volumeStreamingDisabled],
+            [PluginConfig.Download.DefaultPdbProvider, o.pdbProvider],
+            [PluginConfig.Download.DefaultEmdbProvider, o.emdbProvider],
+            [PluginConfig.Structure.DefaultRepresentationPreset, ViewerAutoPreset.id],
+            [PluginConfig.Structure.SaccharideCompIdMapType, o.saccharideCompIdMapType],
+            [AssemblySymmetryConfig.DefaultServerType, o.rcsbAssemblySymmetryDefaultServerType],
+            [AssemblySymmetryConfig.DefaultServerUrl, o.rcsbAssemblySymmetryDefaultServerUrl],
+            [AssemblySymmetryConfig.ApplyColors, o.rcsbAssemblySymmetryApplyColors],
+            ...(o.config ?? []),
+        ]
+    };
+
+    return spec;
+}

src/extensions/plugin/hooks/use-ui-view-model.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { useRef } from 'react';
+import { DefaultPluginUISpec, PluginUISpec } from '../../../mol-plugin-ui/spec';
+import { PluginUIViewModel } from '../ui-view-model';
+
+export function useCreatePluginUIViewModel(options?: { spec?: PluginUISpec | ((defaultSpec?: PluginUISpec) => PluginUISpec) }): PluginUIViewModel {
+    const model = useRef<PluginUIViewModel>();
+    if (!model.current) {
+        model.current = new PluginUIViewModel({
+            spec: options?.spec
+                ? (typeof options.spec === 'function' ? options.spec(DefaultPluginUISpec()) : options.spec)
+                : options?.spec as PluginUISpec
+        });
+    }
+    return model.current;
+}

src/extensions/plugin/hooks/use-view-model.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { MutableRefObject, useEffect, useRef } from 'react';
+import { DefaultPluginSpec, PluginSpec } from '../../../mol-plugin/spec';
+import { PluginViewModel } from '../view-model';
+
+export function useCreatePluginViewModel(options?: { spec?: PluginSpec | ((defaultSpec?: PluginSpec) => PluginSpec) }): PluginViewModel {
+    const model = useRef<PluginViewModel>();
+    if (!model.current) {
+        model.current = new PluginViewModel({
+            spec: options?.spec
+                ? (typeof options.spec === 'function' ? options.spec(DefaultPluginSpec()) : options.spec)
+                : options?.spec as PluginSpec
+        });
+    }
+    return model.current;
+}
+
+export function usePluginViewModel(view: PluginViewModel, parent: MutableRefObject<HTMLElement | null>) {
+    useEffect(() => {
+        if (!parent.current) return;
+        view.mount(parent.current);
+        return () => view.unmount();
+    }, [view]);
+}

src/extensions/plugin/interactivity.ts

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { Structure, StructureElement } from '../../mol-model/structure';
+import { PluginStateObject } from '../../mol-plugin-state/objects';
+import { MolScriptBuilder } from '../../mol-script/language/builder';
+import { Expression } from '../../mol-script/language/expression';
+import { CameraFocusLociOptions } from '../../mol-plugin-state/manager/camera';
+import { PluginContext } from '../../mol-plugin/context';
+
+export interface StructureInteractivityOptions {
+    expression?: (queryBuilder: typeof MolScriptBuilder) => Expression,
+    elements?: StructureElement.Schema,
+    action: 'highlight' | 'select' | 'focus' | ('highlight' | 'select' | 'focus')[],
+    applyGranularity?: boolean,
+    filterStructure?: (structure: Structure) => boolean,
+    focusOptions?: Partial<CameraFocusLociOptions>
+}
+
+/**
+ * Triggers structure element selection or highlighting based on the provided
+ * MolScript expression or StructureElement schema. Focus action will only apply to the
+ * first structure that matches the criteria.
+ *
+ * If neither `expression` nor `elements` are provided, all selections/highlights
+ * will be cleared based on the specified `action`.
+ */
+export function applyStructureInteractivity(plugin: PluginContext, { expression, elements, action: action_, applyGranularity = false, filterStructure, focusOptions }: StructureInteractivityOptions) {
+    const actions = Array.isArray(action_) ? action_ : [action_];
+
+    if (!expression && !elements) {
+        if (actions.includes('select')) {
+            plugin.managers.interactivity.lociSelects.deselectAll();
+        }
+        if (actions.includes('highlight')) {
+            plugin.managers.interactivity.lociHighlights.clearHighlights();
+        }
+        return;
+    }
+
+    if (actions.includes('select')) {
+        plugin.managers.interactivity.lociSelects.deselectAll();
+    }
+
+    const structures = plugin.state.data.selectQ(Q => Q.rootsOfType(PluginStateObject.Molecule.Structure));
+    let focused = false;
+    for (const s of structures) {
+        if (!s.obj?.data) continue;
+
+        if (filterStructure && !filterStructure(s.obj.data)) continue;
+
+        const loci = expression
+            ? StructureElement.Loci.fromExpression(s.obj.data, expression)
+            : StructureElement.Loci.fromSchema(s.obj.data, elements!);
+
+        for (const action of actions) {
+            if (action === 'select') {
+                plugin.managers.interactivity.lociSelects.select({ loci }, applyGranularity);
+            } else if (action === 'highlight') {
+                plugin.managers.interactivity.lociHighlights.highlight({ loci }, applyGranularity);
+            } else if (action === 'focus' && !StructureElement.Loci.isEmpty(loci) && !focused) {
+                plugin.managers.camera.focusLoci(loci, focusOptions);
+                focused = true;
+                if (actions.length === 1) return; // if only focusing, focus the first matching structure and return immediately
+            }
+        }
+    }
+}

src/extensions/plugin/loaders.ts

@@ -0,0 +1,373 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { StringLike } from '../../mol-io/common/string-like';
+import { Volume } from '../../mol-model/volume';
+import { OpenFiles } from '../../mol-plugin-state/actions/file';
+import { DownloadStructure, PdbDownloadProvider } from '../../mol-plugin-state/actions/structure';
+import { DownloadDensity } from '../../mol-plugin-state/actions/volume';
+import { PresetTrajectoryHierarchy } from '../../mol-plugin-state/builder/structure/hierarchy-preset';
+import { StructureRepresentationPresetProvider } from '../../mol-plugin-state/builder/structure/representation-preset';
+import { BuiltInCoordinatesFormat } from '../../mol-plugin-state/formats/coordinates';
+import { BuiltInTopologyFormat } from '../../mol-plugin-state/formats/topology';
+import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
+import { BuildInVolumeFormat } from '../../mol-plugin-state/formats/volume';
+import { createVolumeRepresentationParams } from '../../mol-plugin-state/helpers/volume-representation-params';
+import { PluginStateObject } from '../../mol-plugin-state/objects';
+import { StateTransforms } from '../../mol-plugin-state/transforms';
+import { TrajectoryFromModelAndCoordinates } from '../../mol-plugin-state/transforms/model';
+import { PluginCommands } from '../../mol-plugin/commands';
+import { PluginConfig } from '../../mol-plugin/config';
+import { PluginContext } from '../../mol-plugin/context';
+import { PluginState } from '../../mol-plugin/state';
+import { StateObjectSelector } from '../../mol-state';
+import { Task } from '../../mol-task';
+import { Asset } from '../../mol-util/assets';
+import { Color } from '../../mol-util/color';
+import { loadMVSData, loadMVSX } from '../mvs/components/formats';
+import { loadMVS, MolstarLoadingExtension } from '../mvs/load';
+import { MVSData } from '../mvs/mvs-data';
+
+export function setRemoteSnapshot(plugin: PluginContext, id: string) {
+    const url = `${plugin.config.get(PluginConfig.State.CurrentServer)}/get/${id}`;
+    return PluginCommands.State.Snapshots.Fetch(plugin, { url });
+}
+
+export function loadSnapshotFromUrl(plugin: PluginContext, url: string, type: PluginState.SnapshotType) {
+    return PluginCommands.State.Snapshots.OpenUrl(plugin, { url, type });
+}
+
+export function loadStructureFromUrl(plugin: PluginContext, url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions & { label?: string }) {
+    const params = DownloadStructure.createDefaultParams(plugin.state.data.root.obj!, plugin);
+    return plugin.runTask(plugin.state.data.applyAction(DownloadStructure, {
+        source: {
+            name: 'url',
+            params: {
+                url: Asset.Url(url),
+                format: format as any,
+                isBinary,
+                label: options?.label,
+                options: { ...params.source.params.options, representationParams: options?.representationParams as any },
+            }
+        }
+    }));
+}
+
+export async function loadAllModelsOrAssemblyFromUrl(plugin: PluginContext, url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
+    const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
+    const trajectory = await plugin.builders.structure.parseTrajectory(data, format);
+
+    await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'all-models', { useDefaultIfSingleModel: true, representationPresetParams: options?.representationParams });
+}
+
+export async function loadStructureFromData(plugin: PluginContext, data: string | number[], format: BuiltInTrajectoryFormat, options?: { dataLabel?: string }) {
+    const _data = await plugin.builders.data.rawData({ data, label: options?.dataLabel });
+    const trajectory = await plugin.builders.structure.parseTrajectory(_data, format);
+    await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+}
+
+export function loadPdb(plugin: PluginContext, pdb: string, options?: LoadStructureOptions) {
+    const params = DownloadStructure.createDefaultParams(plugin.state.data.root.obj!, plugin);
+    const provider = plugin.config.get(PluginConfig.Download.DefaultPdbProvider)!;
+    return plugin.runTask(plugin.state.data.applyAction(DownloadStructure, {
+        source: {
+            name: 'pdb' as const,
+            params: {
+                provider: {
+                    id: pdb,
+                    server: {
+                        name: provider,
+                        params: PdbDownloadProvider[provider].defaultValue as any
+                    }
+                },
+                options: { ...params.source.params.options, representationParams: options?.representationParams as any },
+            }
+        }
+    }));
+}
+
+export function loadPdbIhm(plugin: PluginContext, pdbIhm: string) {
+    const params = DownloadStructure.createDefaultParams(plugin.state.data.root.obj!, plugin);
+    return plugin.runTask(plugin.state.data.applyAction(DownloadStructure, {
+        source: {
+            name: 'pdb-ihm' as const,
+            params: {
+                provider: {
+                    id: pdbIhm,
+                    encoding: 'bcif',
+                },
+                options: params.source.params.options,
+            }
+        }
+    }));
+}
+
+export function loadEmdb(plugin: PluginContext, emdb: string, options?: { detail?: number }) {
+    const provider = plugin.config.get(PluginConfig.Download.DefaultEmdbProvider)!;
+    return plugin.runTask(plugin.state.data.applyAction(DownloadDensity, {
+        source: {
+            name: 'pdb-emd-ds' as const,
+            params: {
+                provider: {
+                    id: emdb,
+                    server: provider,
+                },
+                detail: options?.detail ?? 3,
+            }
+        }
+    }));
+}
+
+export function loadAlphaFoldDb(plugin: PluginContext, afdb: string) {
+    const params = DownloadStructure.createDefaultParams(plugin.state.data.root.obj!, plugin);
+    return plugin.runTask(plugin.state.data.applyAction(DownloadStructure, {
+        source: {
+            name: 'alphafolddb' as const,
+            params: {
+                provider: {
+                    id: afdb,
+                    encoding: 'bcif'
+                },
+                options: {
+                    ...params.source.params.options,
+                    representation: 'preset-structure-representation-ma-quality-assessment-plddt'
+                },
+            }
+        }
+    }));
+}
+
+export function loadModelArchive(plugin: PluginContext, id: string) {
+    const params = DownloadStructure.createDefaultParams(plugin.state.data.root.obj!, plugin);
+    return plugin.runTask(plugin.state.data.applyAction(DownloadStructure, {
+        source: {
+            name: 'modelarchive' as const,
+            params: {
+                id,
+                options: params.source.params.options,
+            }
+        }
+    }));
+}
+
+/**
+ * @example Load X-ray density from volume server
+    viewer.loadVolumeFromUrl({
+        url: 'https://www.ebi.ac.uk/pdbe/densities/x-ray/1tqn/cell?detail=3',
+        format: 'dscif',
+        isBinary: true
+    }, [{
+        type: 'relative',
+        value: 1.5,
+        color: 0x3362B2
+    }, {
+        type: 'relative',
+        value: 3,
+        color: 0x33BB33,
+        volumeIndex: 1
+    }, {
+        type: 'relative',
+        value: -3,
+        color: 0xBB3333,
+        volumeIndex: 1
+    }], {
+        entryId: ['2FO-FC', 'FO-FC'],
+        isLazy: true
+    });
+ * *********************
+ * @example Load EM density from volume server
+    viewer.loadVolumeFromUrl({
+        url: 'https://maps.rcsb.org/em/emd-30210/cell?detail=6',
+        format: 'dscif',
+        isBinary: true
+    }, [{
+        type: 'relative',
+        value: 1,
+        color: 0x3377aa
+    }], {
+        entryId: 'EMD-30210',
+        isLazy: true
+    });
+ */
+export async function loadVolumeFromUrl(plugin: PluginContext, { url, format, isBinary }: { url: string, format: BuildInVolumeFormat, isBinary: boolean }, isovalues: VolumeIsovalueInfo[], options?: { entryId?: string | string[], isLazy?: boolean }) {
+    if (!plugin.dataFormats.get(format)) {
+        throw new Error(`Unknown density format: ${format}`);
+    }
+
+    if (options?.isLazy) {
+        const update = plugin.build();
+        update.toRoot().apply(StateTransforms.Data.LazyVolume, {
+            url,
+            format,
+            entryId: options?.entryId,
+            isBinary,
+            isovalues: isovalues.map(v => ({ alpha: 1, volumeIndex: 0, ...v }))
+        });
+        return update.commit();
+    }
+
+    return plugin.dataTransaction(async () => {
+        const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
+
+        const parsed = await plugin.dataFormats.get(format)!.parse(plugin, data, { entryId: options?.entryId });
+        const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
+        if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
+
+        const repr = plugin.build();
+        for (const iso of isovalues) {
+            const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[iso.volumeIndex ?? 0] ?? parsed.volume;
+            const volumeData = volume.cell!.obj!.data;
+            repr
+                .to(volume)
+                .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(plugin, firstVolume.data!, {
+                    type: 'isosurface',
+                    typeParams: { alpha: iso.alpha ?? 1, isoValue: Volume.adjustedIsoValue(volumeData, iso.value, iso.type) },
+                    color: 'uniform',
+                    colorParams: { value: iso.color }
+                }));
+        }
+
+        await repr.commit();
+    });
+}
+
+export function loadFullResolutionEMDBMap(plugin: PluginContext, emdbId: string, options: { isoValue: Volume.IsoValue, color?: Color }) {
+    const numericId = parseInt(emdbId.toUpperCase().replace('EMD-', ''));
+    const url = `https://ftp.ebi.ac.uk/pub/databases/emdb/structures/EMD-${numericId}/map/emd_${numericId}.map.gz`;
+
+    return plugin.dataTransaction(async () => {
+        const data = await plugin.build().toRoot()
+            .apply(StateTransforms.Data.Download, { url, isBinary: true, label: emdbId }, { state: { isGhost: true } })
+            .apply(StateTransforms.Data.DeflateData)
+            .commit();
+
+        const parsed = await plugin.dataFormats.get('ccp4')!.parse(plugin, data, { entryId: emdbId });
+        const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
+        if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
+
+        const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[0] ?? parsed.volume;
+        await plugin.build()
+            .to(volume)
+            .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(plugin, firstVolume.data!, {
+                type: 'isosurface',
+                typeParams: { alpha: 1, isoValue: options.isoValue },
+                color: 'uniform',
+                colorParams: { value: options.color ?? Color(0x33BB33) }
+            }))
+            .commit();
+    });
+}
+
+/**
+ * @example
+ *  viewer.loadTrajectory({
+ *      model: { kind: 'model-url', url: 'villin.gro', format: 'gro' },
+ *      coordinates: { kind: 'coordinates-url', url: 'villin.xtc', format: 'xtc', isBinary: true },
+ *      preset: 'all-models' // or 'default'
+ *  });
+ */
+export async function loadTrajectory(plugin: PluginContext, params: LoadTrajectoryParams) {
+    let model: StateObjectSelector;
+
+    if (params.model.kind === 'model-data' || params.model.kind === 'model-url') {
+        const data = params.model.kind === 'model-data'
+            ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
+            : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
+
+        const trajectory = await plugin.builders.structure.parseTrajectory(data, params.model.format ?? 'mmcif');
+        model = await plugin.builders.structure.createModel(trajectory);
+    } else {
+        const data = params.model.kind === 'topology-data'
+            ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
+            : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
+
+        const provider = plugin.dataFormats.get(params.model.format);
+        const parsed = await provider!.parse(plugin, data);
+        model = parsed.topology;
+    }
+
+    const data = params.coordinates.kind === 'coordinates-data'
+        ? await plugin.builders.data.rawData({ data: params.coordinates.data, label: params.coordinatesLabel })
+        : await plugin.builders.data.download({ url: params.coordinates.url, isBinary: params.coordinates.isBinary, label: params.coordinatesLabel });
+
+    const provider = plugin.dataFormats.get(params.coordinates.format);
+    const coords = await provider!.parse(plugin, data);
+
+    const trajectory = await plugin.build().toRoot()
+        .apply(TrajectoryFromModelAndCoordinates, {
+            modelRef: model.ref,
+            coordinatesRef: coords.ref
+        }, { dependsOn: [model.ref, coords.ref] })
+        .commit();
+
+    const preset = await plugin.builders.structure.hierarchy.applyPreset(trajectory, params.preset ?? 'default');
+
+    return { model, coords, preset };
+}
+
+export async function loadMvsFromUrl(plugin: PluginContext, url: string, format: 'mvsj' | 'mvsx', options?: { appendSnapshots?: boolean, keepCamera?: boolean, keepCameraOrientation?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+    if (format === 'mvsj') {
+        const data = await plugin.runTask(plugin.fetch({ url, type: 'string' }));
+        const mvsData = MVSData.fromMVSJ(StringLike.toString(data));
+        await loadMVS(plugin, mvsData, { sanityChecks: true, sourceUrl: url, ...options });
+    } else if (format === 'mvsx') {
+        const data = await plugin.runTask(plugin.fetch({ url, type: 'binary' }));
+        await plugin.runTask(Task.create('Load MVSX file', async ctx => {
+            const parsed = await loadMVSX(plugin, ctx, data, { doNotClearAssets: options?.appendSnapshots });
+            await loadMVS(plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+        }));
+    } else {
+        throw new Error(`Unknown MolViewSpec format: ${format}`);
+    }
+}
+
+/** Load MolViewSpec from `data`.
+ * If `format` is 'mvsj', `data` must be a string or a Uint8Array containing a UTF8-encoded string.
+ * If `format` is 'mvsx', `data` must be a Uint8Array or a string containing base64-encoded binary data prefixed with 'base64,'. */
+export function loadMvsData(plugin: PluginContext, data: string | Uint8Array<ArrayBuffer>, format: 'mvsj' | 'mvsx', options?: { appendSnapshots?: boolean, keepCamera?: boolean, keepCameraOrientation?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+    return loadMVSData(plugin, data, format, options);
+}
+
+export function loadFiles(plugin: PluginContext, files: File[]) {
+    const sessions = files.filter(f => {
+        const fn = f.name.toLowerCase();
+        return fn.endsWith('.molx') || fn.endsWith('.molj');
+    });
+
+    if (sessions.length > 0) {
+        return PluginCommands.State.Snapshots.OpenFile(plugin, { file: sessions[0] });
+    } else {
+        return plugin.runTask(plugin.state.data.applyAction(OpenFiles, {
+            files: files.map(f => Asset.File(f)),
+            format: { name: 'auto', params: {} },
+            visuals: true
+        }));
+    }
+}
+
+export interface LoadStructureOptions {
+    representationParams?: StructureRepresentationPresetProvider.CommonParams
+}
+
+export interface VolumeIsovalueInfo {
+    type: 'absolute' | 'relative',
+    value: number,
+    color: Color,
+    alpha?: number,
+    volumeIndex?: number
+}
+
+export interface LoadTrajectoryParams {
+    model: { kind: 'model-url', url: string, format?: BuiltInTrajectoryFormat /* mmcif */, isBinary?: boolean }
+    | { kind: 'model-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format?: BuiltInTrajectoryFormat /* mmcif */ }
+    | { kind: 'topology-url', url: string, format: BuiltInTopologyFormat, isBinary?: boolean }
+    | { kind: 'topology-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format: BuiltInTopologyFormat },
+    modelLabel?: string,
+    coordinates: { kind: 'coordinates-url', url: string, format: BuiltInCoordinatesFormat, isBinary?: boolean }
+    | { kind: 'coordinates-data', data: string | number[] | ArrayBuffer | Uint8Array<ArrayBuffer>, format: BuiltInCoordinatesFormat },
+    coordinatesLabel?: string,
+    preset?: keyof PresetTrajectoryHierarchy
+}

src/extensions/plugin/react.tsx

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { type CSSProperties, useRef } from 'react';
+import type { PluginViewModel } from './view-model';
+import { usePluginViewModel } from './hooks/use-view-model';
+
+export function PluginCanvas({ model, style, className }: { model: PluginViewModel, style?: CSSProperties, className?: string }) {
+    const root = useRef<HTMLDivElement>(null);
+    usePluginViewModel(model, root);
+    return <div ref={root} style={style} className={className} />;
+}

src/extensions/plugin/ui-view-model.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+
+export class PluginUIViewModel {
+    readonly plugin: PluginUIContext;
+
+    get initialized() {
+        return this.plugin.initialized;
+    }
+
+    private async init() {
+        await this.plugin.init();
+    }
+
+    constructor(options?: { spec?: PluginUISpec }) {
+        const spec = options?.spec ?? DefaultPluginUISpec();
+        this.plugin = new PluginUIContext(spec);
+        this.init();
+    }
+}

src/extensions/plugin/view-model.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { DefaultPluginSpec, PluginSpec } from '../../mol-plugin/spec';
+import { PluginContext } from '../../mol-plugin/context';
+import { SingleAsyncQueue } from '../../mol-util/single-async-queue';
+
+export class PluginViewModel {
+    private mountQueue = new SingleAsyncQueue();
+    readonly plugin: PluginContext;
+
+    get initialized() {
+        return this.plugin.initialized;
+    }
+
+    private async init() {
+        await this.plugin.init();
+    }
+
+    mount(root: HTMLElement) {
+        this.mountQueue.enqueue(() => this.plugin.mountAsync(root));
+    }
+
+    unmount() {
+        this.mountQueue.enqueue(() => this.plugin.unmount());
+    }
+
+    constructor(options?: { spec?: PluginSpec }) {
+        const spec = options?.spec ?? DefaultPluginSpec();
+        this.plugin = new PluginContext(spec);
+        this.init();
+    }
+}