sergeinikolenko/burette/mvs-story

MolViewSpec Story

Use Story as the primary agent-to-user explanation surface when a molecular task benefits from a sequence: overview, target or pocket, ligand pose, contacts, comparison, and conclusion. A Story is not a list of viewer clicks. It is a reproducible MolViewSpec object with kind: "multiple" and one complete scene tree per snapshot.

Workflow

For Burette docking Stories, keep the viewer on standard Automatic representation and preserve its chosen Appearance. Do not author a second docking-specific color/opacity style, residue labels, or distance primitives by default. When a step has an explicit nonempty residue selection, give its MVS component ref: "burette-environment"; Burette uses the stock Mol* focus/surroundings behavior for it. Keep computed contacts and scores in the description. Steps without that selection must not acquire an invented environment. Verify the first step and forward/back after loading, not only the toolbar's Auto label.

1. Call burette.list_story_templates. Reuse the closest installed scaffold

when its scientific purpose matches; otherwise write a short storyboard before generating JSON. Give every step one scientific purpose and one user-facing conclusion.

1. For a matching scaffold, call burette.create_story_from_template with all

required variables and local resources. Treat the result as a starting point: replace generic prose with observed evidence and preserve its scientific caveats.

1. For nodes or features not already demonstrated by the template, read

the bundled authoring reference, then call burette.get_mvs_authoring_reference for the scene or animation overview and each unfamiliar node. This returns the exact contract from the Mol* version installed with Burette instead of relying on recalled syntax.

1. Build or customize a complete root scene for every snapshot. Keep selectors,

representations, colors, labels, primitives, and camera settings inside the snapshot so any step can be loaded independently.

1. Give every snapshot a unique stable key, concise title, markdown

description, linger_duration_ms, and transition_duration_ms.

1. When authoring without a template, call burette.create_story with the Story and an output ending in .mvsj

or .mvsx. For local or relative resources, pass a resources mapping and use .mvsx; do not hand off a broken standalone .mvsj.

1. Call burette.validate_story on the resulting file.
2. Open it with burette.open_workspace, open the returned Browser URL when

required, and wait for workspace readiness.

1. Call burette.observe_story. Confirm the title, step count, current key,

description, and playback state.

1. Exercise burette.control_story with at least next and previous; use

goto, play, and pause when the user asked for them.

1. Run Browser visual QA on the first step and one transitioned step. A valid

JSON file alone does not prove that structures, labels, or resources render.

Documentation boundary

The bundled reference covers every main upstream MolViewSpec documentation area and links to the official pages. The reference tool is the version-matched source of truth for supported nodes and parameters. Upstream tutorials and demos remain external and should be consulted only when the task needs their prose or runnable examples; do not inject the full website into every agent turn.

Installed Templates

• structure-overview: global fold to ligand context.
• binding-site-tour: overview, pocket focus, and evidence-qualified interpretation.
• docking-pose-comparison: receptor, two poses with required computed key-interaction

primitive layers, matching endpoint-residue annotations, compact default-colored ball-and-stick ligands, and a consistently encoded overlay.

• aligned-structure-comparison: reference, candidate, and overlay; inputs must

already share a coordinate frame.

The template catalog declares variables, storyboard purpose/evidence, and caveats. Templates do not compute contacts, docking confidence, affinity, alignment, RMSD, or trajectory metrics. The docking comparison refuses to package without explicit interaction resources, endpoint-residue annotations, and evidence summaries for both poses, but those inputs still must come from a named calculation with method status, units, and uncertainty in the step text.

Authoring Shape

burette.create_story accepts either a standard MolViewSpec multi-state object or a compact authoring object:

{
  "title": "Binding-site tour",
  "description": "Protein-ligand interaction walkthrough",
  "steps": [
    {
      "key": "overview",
      "title": "Complex overview",
      "description": "# Overview\nProtein and ligand in context.",
      "root": {
        "kind": "root",
        "children": []
      },
      "lingerDurationMs": 8000,
      "transitionDurationMs": 1000
    }
  ]
}

The tool normalizes this into:

{
  "kind": "multiple",
  "metadata": {
    "title": "Binding-site tour",
    "timestamp": "...",
    "version": "1"
  },
  "snapshots": []
}

Resource Rules

• Use only absolute HTTP(S) or data URLs in portable .mvsj files.
• Prefer .mvsx for local PDB, mmCIF, SDF, volume, annotation, or other

sidecar resources.

• Resource keys in resources must exactly match relative download.url

values in the scene trees; a leading ./ is normalized for compatibility with Mol* exports.

• External resources may use HTTP(S) or bounded data URLs. file: URLs and

absolute filesystem paths are rejected; package those files in MVSX.

• Archive paths cannot be absolute, empty, contain backslashes, or traverse

with . or ...

• Creation refuses to overwrite an existing output unless the user explicitly

requests replacement.

Story Controls

Use burette.observe_story for typed state. Use burette.control_story with:

• next or previous;
• goto plus index, key, or snapshot id;
• play with optional restart;
• pause.

The Burette Story dock mirrors the current Mol* snapshot and exposes visible Previous, Play/Pause, and Next controls. Do not substitute DOM clicks when the typed tools are available.

Completion Gate

Complete only when:

• validation returns ok: true;
• every relative resource is present in MVSX;
• the workspace and viewer report ready;
• observe_story.available is true and stepCount matches the storyboard;
• next/previous returns the expected step metadata;
• Browser shows a nonblank molecular scene for at least two steps.