@gcszhn/mol4agent-core 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/select.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /** Selector compilation: protocol selectors to Mol* schemas/queries. @module @gcszhn/mol4agent-core/select */
2
- import { StructureSelectionQueries } from 'molstar/lib/mol-plugin-state/helpers/structure-selection-query';
2
+ import { StructureElement } from 'molstar/lib/mol-model/structure.js';
3
+ import { StructureSelectionQueries } from 'molstar/lib/mol-plugin-state/helpers/structure-selection-query.js';
3
4
  /**
4
5
  * Compile one agent selector.
5
6
  *
@@ -56,6 +57,45 @@ export function selectorSchema(selector) {
56
57
  const compiled = compileSelector(selector);
57
58
  return 'elements' in compiled ? compiled.elements : undefined;
58
59
  }
60
+ /** The Mol* expression equivalent of a selector, for direct Loci lookups. */
61
+ export function selectorExpression(selector) {
62
+ const compiled = compileSelector(selector);
63
+ return 'elements' in compiled
64
+ ? StructureElement.Schema.toExpression(compiled.elements)
65
+ : compiled.expression(undefined);
66
+ }
67
+ /**
68
+ * Stable component key for one selection.
69
+ *
70
+ * Repeated targeted styles of the same selection reuse one Mol* cell; each
71
+ * `replace: false` command adds its own representation there, so cartoon +
72
+ * stick + line overlays do not fragment into sibling components.
73
+ */
74
+ export function selectionKey(selector) {
75
+ let hash = 2166136261;
76
+ for (const char of JSON.stringify(selector)) {
77
+ hash ^= char.charCodeAt(0);
78
+ hash = Math.imul(hash, 16777619);
79
+ }
80
+ return `mol4agent-sel-${(hash >>> 0).toString(36)}`;
81
+ }
82
+ /** Short human label for a selector, used in tool and inspection output. */
83
+ export function describeSelector(selector) {
84
+ switch (selector.kind) {
85
+ case 'all': return 'whole structure';
86
+ case 'polymer': return 'polymer';
87
+ case 'protein': return 'protein';
88
+ case 'nucleic': return 'nucleic acid';
89
+ case 'ligand': return 'ligand';
90
+ case 'water': return 'water';
91
+ case 'ion': return 'ion';
92
+ case 'chain': return `chain ${selector.chain}`;
93
+ case 'residue': return `residue ${selector.chain ?? ''}${selector.index}`;
94
+ case 'residues': return `residues ${selector.chain ?? ''}${selector.start}-${selector.end}`;
95
+ case 'comp': return `comp ${selector.compId}`;
96
+ case 'schema': return 'custom schema';
97
+ }
98
+ }
59
99
  function query(selection) {
60
100
  return { expression: () => selection.expression };
61
101
  }
package/lib/viewer.d.ts CHANGED
@@ -1,8 +1,8 @@
1
- import { type CaptureOptions, type CommandResult, type MolCommand, type StructureData, type StructureSummary } from './protocol.ts';
1
+ import { type CaptureOptions, type CommandResult, type LoadedStructure, type InspectRequest, type InspectResult, type MolCommand, type StructureData, type StructureSummary, type TmScoreRequest, type TmScoreResult } from './protocol.ts';
2
2
  export interface MolViewerOptions {
3
3
  readonly container: HTMLElement;
4
4
  readonly theme?: 'light' | 'dark';
5
- readonly background?: string;
5
+ readonly background?: string | number;
6
6
  }
7
7
  export interface ViewerDiagnostics {
8
8
  readonly canvas: {
@@ -23,13 +23,50 @@ export interface ViewerDiagnostics {
23
23
  export interface MolViewer {
24
24
  /** Snapshot of layout and Mol* hierarchy counts, for diagnostics. */
25
25
  diagnostics(): ViewerDiagnostics;
26
- /** Replace the displayed structure with adapter-supplied bytes. */
26
+ /**
27
+ * Replace the displayed scene with adapter-supplied bytes.
28
+ *
29
+ * The previous structures, their components, and measurements are cleared.
30
+ * `options.id` sets the id of the new (primary) structure; it defaults to
31
+ * `structure`.
32
+ */
27
33
  load(data: StructureData, options?: {
28
34
  preset?: string;
35
+ id?: string;
29
36
  }): Promise<StructureSummary>;
37
+ /**
38
+ * Add another structure to the current scene without clearing existing ones.
39
+ *
40
+ * Returns the stable id and summary. `options.id` must be unique within the
41
+ * scene; a generated id (`structure-2`, `structure-3`, ...) is used when it
42
+ * is omitted.
43
+ */
44
+ addStructure(data: StructureData, options?: {
45
+ preset?: string;
46
+ id?: string;
47
+ }): Promise<LoadedStructure>;
48
+ /** Remove one structure (and its components) from the scene. */
49
+ removeStructure(id: string): Promise<void>;
50
+ /** Structures currently loaded in this scene, in load order. */
51
+ listStructures(): readonly LoadedStructure[];
30
52
  /** Current summary, when a structure is loaded. */
31
53
  summary(): StructureSummary | undefined;
32
- /** Execute one command against the loaded structure. */
54
+ /**
55
+ * Read the loaded structure and the way Mol* currently draws it.
56
+ *
57
+ * Read-only: unlike {@link MolViewer.execute} it changes nothing, and its
58
+ * answers include human-driven viewer state (clicked selection, panel
59
+ * styles) that never passed through the adapter's command log.
60
+ */
61
+ inspect(request?: InspectRequest): InspectResult;
62
+ /**
63
+ * Compute TM-align metrics for two selections without moving either one.
64
+ *
65
+ * Read-only, like {@link MolViewer.inspect}; RMSD is measured after optimal
66
+ * superposition of the aligned polymer-trace atoms, not in the current frame.
67
+ */
68
+ tmScore(request: TmScoreRequest): TmScoreResult;
69
+ /** Execute one command against the loaded structures. */
33
70
  execute(command: MolCommand): Promise<CommandResult>;
34
71
  /** Execute commands in order, returning per-command results. */
35
72
  apply(commands: readonly MolCommand[]): Promise<readonly CommandResult[]>;