# Handoff 2026-02-02 — Manual Segmentation UI/UX Refinement (Matplotlib)

## Purpose
Refine the **manual segmentation interactive UI** to make it precise, safe, and efficient for large-scale manual review of decay records.

This handoff focuses **only on UX/UI behavior**, not fitting logic or segmentation semantics.

The goal is to make the manual workflow:
- fast to operate
- hard to misuse
- self-documenting on screen

---

## Scope and Constraints

- Matplotlib interactive window only (no Textual / Qt / web UI)
- Keyboard-driven interaction preferred
- Existing fitting and segmentation logic remains unchanged
- Manual segmentation is authoritative (human-in-the-loop)

---

## Core Interaction Model (Locked)

### Cursor-Based, Key-Driven Actions

- Mouse movement tracks the **current cursor x-position** continuously
- **Mouse clicks do NOT add points**
- All boundary operations are triggered via keyboard commands at the current cursor x

This avoids accidental boundary creation during zoom/pan.

---

## Boundary Interaction Commands

### Add Boundary
- Key: `a`
- Action:
  - read current cursor x-position (`x_cursor`)
  - snap to nearest time sample: `i = argmin(|t - x_cursor|)`
  - add boundary at `t[i]`
  - deduplicate and sort boundaries
  - recompute piecewise fits (see performance note)

### Delete Nearest Boundary
- Key: `x`
- Action:
  - find boundary whose time is closest to `x_cursor`
  - remove it
  - recompute fits

### Clear All Boundaries
- Key: `c`
- Action:
  - remove all boundaries
  - clear all piecewise fits

---

## Navigation and Display Commands

### Toggle Y-Scale (Linear / Log)
- Key: `l`
- Action:
  - toggle y-axis scale between `linear` and `log`
  - boundary markers MUST persist
  - boundary values MUST NOT be recomputed or altered

### Quit Interactive Session
- Key: `q`
- Action:
  - close figure
  - persist current manual segmentation state (if enabled)

---

## Zoom / Pan Safety Rules

- Zooming and panning are done using the Matplotlib toolbar
- Adding or deleting boundaries via keys is **disabled while toolbar mode is active**

Behavior:
- Detect toolbar mode (PAN / ZOOM)
- If active:
  - ignore `a` / `x`
  - update on-screen status to `MODE = ZOOM` or `MODE = PAN`

---

## On-Screen Help Overlay (Required)

### Help Panel

A persistent, semi-transparent help panel must be visible by default.

Contents:
```
MODE: ADD

Keys:
  a  add boundary at cursor
  x  delete nearest boundary
  c  clear all boundaries
  l  toggle lin/log scale
  h  toggle help
  q  quit
```

- Location: bottom-left or bottom-right (must not obscure data)
- Toggle visibility with key: `h`

---

## Selection and State Info Panel (Required)

A second on-screen info block must display **current state** at all times.

Minimum required fields:
- number of boundaries: `k`
- number of pieces: `max(k-1, 0)`
- boundary times (snapped): `[t0, t1, ...]`
- last action feedback (e.g. `Added boundary at t=0.09322 s`)

Location:
- top-left or top-right
- must not overlap legend

---

## Computed Fit Metrics Display

### Minimal In-Plot Summary (Required)

For each fitted piece, display:
- piece index
- ζ (damping ratio)
- R²
- A0 (initial amplitude)

Format may be compact, e.g.:
```
Piece 0: ζ=0.00040 | R²=0.998 | A0=...
Piece 1: ζ=0.00390 | R²=0.997 | A0=...
```

This summary updates after each recompute.

---

## Legend Placement (Required)

- Legend must NOT obscure the data region
- Preferred options:
  - `loc="upper right"`
  - or outside axes using `bbox_to_anchor`

Decision left to implementer based on available figure width.

---

## Recompute Behavior

### Default
- Recompute fits immediately after any boundary add/delete/clear

### Performance Fallback
If recomputation becomes too slow:
- show status: `Pending recompute`
- allow explicit recompute via key: `r`

Default expectation: **instant recompute** for typical record sizes.

---

## Persistence

On exit (`q`) or explicit save (if later added):

Persist in metadata:
- `manual_segmentation.enabled = true`
- `manual_segmentation.boundaries_time_s = [...]`
- `manual_segmentation.boundaries_index = [...]`
- per-piece fitted parameters

This ensures reproducibility of manual decisions.

---

## Explicit Non-Goals

This UI refinement does NOT:
- change fitting algorithms
- introduce automatic segmentation logic
- add boundary optimization or wiggle fitting
- attempt to replace future batch automation

---

## Success Criteria

After implementation:
- user can zoom/pan freely without accidental boundary creation
- boundary placement is precise and intentional
- all relevant commands are discoverable on-screen
- computed fit parameters are visible without inspecting logs
- the tool supports rapid manual review across many CSV files

---

## Status

- UI/UX behavior: **locked**
- Ready for OpenCode implementation

