molstar-structure-editor-debug

name	molstar-structure-editor-debug
description	Use when the molstar-structure-editor plugin has broken gizmo picking, dragging that rotates the camera instead, stale structure rendering, selection resolution failures, or commit/cancel state issues.

Molstar Structure Editor Debug

Overview

Most bugs in this plugin fall into one of four buckets: selection resolution, pointer routing, projection math, or coordinate-backed structure rendering.

Debug Order

1. Confirm a session exists.
2. Confirm the gizmo is projected where it is actually drawn.
3. Confirm pointer input reaches the controller only when gizmo handles are hit.
4. Confirm coordinate updates target ModelWithCoordinates.
5. Confirm the visible structure branch comes from the coordinate-backed model.

Symptom to Cause Map

• Move or Rotate does nothing Likely no valid session, no effective selection, or missed gizmo hit.
• Dragging rotates the camera instead of moving atoms Pointer did not hit a gizmo handle, or hit thresholds are too small.
• Dragging updates internal coordinates but the view does not change The visible structure branch is still the original structure, not the edited one.
• Mouse feels offset from the gizmo Screen projection math is wrong, commonly a viewport-to-client Y inversion bug.
• Commit keeps strange stale state Source/preview structure refs were not swapped or cleaned up correctly.

What to Inspect

• Controller state in src/behavior.ts Check state, session, dragOperation, pointerHost, sourceStructureRef, previewStructureRef.
• Selection resolution in src/selection-target.ts Confirm only one structure is selected.
• Coordinate bridge in src/coordinate-updater.ts Confirm updates go through ModelWithCoordinates.
• Projection and picking in src/behavior.ts plus src/gizmo-hit-test.ts Confirm rendered scale and hit scale match.

Browser Checks

• Open the example viewer and select a small atomic target.
• Prefer Spacefill during debugging; Cartoon can hide local movement.
• In edit mode:
  • dragging empty space should move the camera
  • dragging a handle should move or rotate only the selected atoms
• If the gizmo feels offset, verify projected handle points against the rendered gizmo before changing thresholds.

Fix Strategy

• Fix root cause first, then widen thresholds only if needed.
• Do not compensate for projection bugs by endlessly inflating hit areas.
• Do not update the source structure branch directly during live drag; keep the coordinate-backed branch as the visible edited structure.

Useful Commands

cd /home/ylj/应用/molstar/molstar-structure-editor
npm run dev:example
npm test
npm run typecheck
npm run build