@molstudio/core 0.0.0-stage → 0.1.0

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shuuul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/MolStudio.d.ts

@@ -0,0 +1,147 @@
+import type { BuiltInTrajectoryFormat } from "molstar/lib/mol-plugin-state/formats/trajectory";
+import { PluginContext } from "molstar/lib/mol-plugin/context";
+import type { MolStudioPlugin } from "./plugins";
+import type { AtomTable, ColorScheme, ImageExportOptions, ImageFraming, ImageLimits, OverridablePart, SequenceResidue, StructurePart, RepresentationKind, StudioSnapshot, VolumeGrid, VolumeHistogram, VolumeStyle } from "./types";
+export type StructureFormat = BuiltInTrajectoryFormat;
+export type VolumeFormat = "ccp4" | "dsn6" | "cube" | "dx" | "dscif";
+export interface LoadDataOptions<F extends string> {
+    data: string | Uint8Array<ArrayBuffer>;
+    label: string;
+    format: F;
+}
+/**
+ * Owns a UI-less Mol* plugin and exposes the viewer as a list of objects
+ * (structures, volumes) with a small set of display operations.
+ * Mol* state stays the single source of truth; snapshots are derived from it.
+ */
+export declare class MolStudio {
+    readonly plugin: PluginContext;
+    private snapshot;
+    private readonly plugins;
+    private readonly listeners;
+    private readonly subscriptions;
+    private rebuildScheduled;
+    /** Author-recommended contour levels (absolute) fetched from EMDB, keyed by volume ref. */
+    private readonly authorContours;
+    private readonly isoUpdates;
+    private readonly overrideCreations;
+    /** The view from before Mol*'s focus view began, so leaving focus can return to it. */
+    private cameraBeforeFocus;
+    private constructor();
+    static create(target: HTMLElement): Promise<MolStudio>;
+    dispose(): void;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => StudioSnapshot;
+    private publish;
+    private scheduleRebuild;
+    /** Registers a plugin and returns a function that unregisters it. */
+    registerPlugin(plugin: MolStudioPlugin): () => void;
+    private unregisterPlugin;
+    runAction(pluginId: string, actionId: string, objectId: string): Promise<void>;
+    private publishActions;
+    getAtoms(objectId: string): AtomTable;
+    /** The grid is shared with the viewer when its layout allows; treat `values` as read-only. */
+    getVolumeGrid(objectId: string): VolumeGrid;
+    loadStructure({ data, label, format }: LoadDataOptions<StructureFormat>): Promise<void>;
+    loadStructureFromUrl(url: string, label: string, format: StructureFormat, isBinary: boolean): Promise<void>;
+    loadPdb(id: string): Promise<void>;
+    loadAlphaFoldDb(uniprotId: string): Promise<void>;
+    /** Accepts `EMD-1832` or the bare number `1832`; the map opens at the author-recommended contour. */
+    loadEmdb(id: string): Promise<void>;
+    loadVolume({ data, label, format }: LoadDataOptions<VolumeFormat>): Promise<void>;
+    loadVolumeFromUrl(url: string, label: string, format: VolumeFormat, isBinary: boolean): Promise<void>;
+    private applyStructurePreset;
+    private applyVolumeVisuals;
+    setVisible(id: string, visible: boolean): void;
+    /**
+     * Structure display operations take a target: a structure id changes its main (polymer) component,
+     * a component ref (see `StructureObject.components`) changes that component alone.
+     */
+    setRepresentation(target: string, kind: RepresentationKind): Promise<void>;
+    setColorScheme(target: string, scheme: ColorScheme): Promise<void>;
+    /** Colors the target uniformly with `hex`. */
+    setColor(target: string, hex: string): Promise<void>;
+    /** A structure id changes every component; a component ref or volume id changes only that. */
+    setOpacity(target: string, opacity: number): Promise<void>;
+    /**
+     * Latest call wins: while an isosurface is being rebuilt, further levels for the same volume replace
+     * each other and only the last one is applied next. Live dragging therefore never queues up work.
+     * The returned promise settles once the surface matches the most recent level.
+     */
+    setIsoLevel(id: string, sigma: number): Promise<void>;
+    /** Fetches (once) and applies the EMDB author-recommended contour level. */
+    applyAuthorLevel(id: string): Promise<void>;
+    getVolumeHistogram(id: string): VolumeHistogram;
+    private fetchAuthorContour;
+    private requireVolumeData;
+    private volumeName;
+    setVolumeStyle(id: string, style: VolumeStyle): Promise<void>;
+    setVolumeColor(id: string, hex: string): Promise<void>;
+    /** Moves the camera to an object, or to one structure component by ref. */
+    focus(target: string): void;
+    remove(id: string): Promise<void>;
+    getSequence(objectId: string, chainIndex: number): SequenceResidue[];
+    /** Highlights a part in the 3D view the way pointer hover does; `null` clears the highlight. */
+    highlightPart(part: StructurePart | null): void;
+    /** Moves the camera to a part; a residue also gets Mol*'s focus view with its surroundings. */
+    focusPart(part: StructurePart): void;
+    /** Leaves Mol*'s focus view, removing its target and surroundings components, and returns to the earlier view. */
+    clearFocus(): void;
+    /**
+     * Hides or shows an entity, chain, or residue in every component by making it fully transparent,
+     * which also removes it from picking. Component visibility (`setVisible`) is independent of this.
+     */
+    setPartVisible(part: StructurePart, visible: boolean): Promise<void>;
+    /**
+     * Gives an entity or chain its own component, drawn like the structure until changed, and hides it in
+     * the other components. Returns the component ref (the existing one if the part already has it), which
+     * the display operations accept as their target.
+     */
+    overridePart(part: OverridablePart): Promise<string>;
+    private createOverride;
+    /** Removes a part's own component, so the part is drawn by the structure's components again. */
+    resetPart(part: OverridablePart): Promise<void>;
+    private overrideOf;
+    private componentPart;
+    /**
+     * Hides each override's part in the components it replaces: the structure's own components and, for
+     * a chain, an override of its entity, so the more specific display wins where parts overlap.
+     */
+    private maskOverrides;
+    private hiddenChainsOf;
+    /** Transparency layers of a component, read from state so they are current right after a commit. */
+    private transparencyLayers;
+    private partLoci;
+    private residueRef;
+    resetCamera(): void;
+    setSpinning(spinning: boolean): void;
+    setBackground(hex: string): void;
+    /**
+     * Keeps the orientation axes in the bottom-left corner of the canvas region that floating UI leaves
+     * uncovered; offsets are CSS pixels from the canvas's bottom-left corner.
+     */
+    setAxesInset(left: number, bottom: number): void;
+    imageLimits(): ImageLimits;
+    /** A quick, unsmoothed render of the framing as a PNG data URL, for previews. */
+    previewImage(framing: ImageFraming, maxDim?: number): Promise<string>;
+    /** Renders the image at full quality and encodes it with its print resolution. */
+    exportImage(options: ImageExportOptions): Promise<Blob>;
+    /** Points Mol*'s screenshot helper at the framing; white is composited later onto a transparent render. */
+    private prepareScreenshot;
+    private buildObjects;
+    private describeStructure;
+    private describeVolume;
+    private applicableSchemes;
+    private requireObject;
+    private requireStructure;
+    private requireStructureData;
+    private requireComponent;
+    /** Representations a structure display operation changes; see `setRepresentation`. */
+    private displayTarget;
+    private requireVolume;
+    private requireCanvas;
+    /** The top-level data node an object was created from (the loaded file or download). */
+    private rootRef;
+    private rootLabel;
+    private updateEach;
+}