# Handoff 260209-1 — envelope-decay-fit (Matplotlib manual UI)

## Scope

This handoff **only** covers changes to the `envelope-decay-fit` package, specifically the **manual Matplotlib UI** used for point selection and envelope fitting.

Explicitly out of scope:

- Peak selection limits / `max_peaks` logic (owned by `wav-to-freq`, deferred)
- Any wav-to-freq CLI or workflow changes

---

## Context / Problem Statement

The current manual Matplotlib UI has several UX issues that affect usability and review confidence:

- Help text overlaps curves and legend unpredictably
- Help text is always visible and verbose
- Legend sometimes shows **text only**, without colored line samples
- Exit semantics are ambiguous ("quit" vs save)

These changes aim to make the UI:

- Deterministic
- Non-intrusive
- Reviewable (including by automated tests)

---

## Specs

This section defines the locked behavioral requirements for the manual Matplotlib UI.

### S-260209-1 — Help overlay default state

- Help overlay is **collapsed by default**
- Minimal hint is shown (e.g. `h: help`)

### S-260209-2 — Help overlay content

- Help overlay lists **interaction keys only**
- No workflow prose or explanations
- Rename action label from **"quit" → "save and quit"**

### S-260209-3 — Exit semantics

- Single exit path only
- `q` = **save and quit**
- No discard / cancel path in manual UI

### S-260209-4 — Help overlay placement logic

Placement order:

1. Attempt to place help overlay **under the legend**
2. If overlap with data exceeds tolerance → fallback to **bottom-right corner**

Priority rules:

- **Legend has priority** over help overlay
- Help overlay must move / fallback first

### S-260209-5 — Legend behavior

- Use **native Matplotlib legend**
- Legend must include **handles** (colored line samples + labels)
- Text-only legends are not acceptable

---

## Implementation

Implementation guidance for the agent:

- Changes are limited to the manual Matplotlib UI layer
- Prefer native Matplotlib mechanisms (legend handles, bounding boxes)
- Overlay placement logic should be deterministic
- Do **not** introduce new dependencies
- Do **not** modify fitting logic, data structures, or APIs

---

## Tests

### T-260209-1 — Automated UI placement verification

- Automated tests may save figures to PNG **for testing only**
- Image analysis may be used to validate:
  - Help overlay placement (under legend or bottom-right)
  - No excessive overlap with plotted data
  - Legend visibility and handles

Image analysis is **not** required at runtime.

---



## Non-Goals

- No redesign of fitting logic
- No change to data model or API
- No changes to peak selection, filtering, or upstream orchestration

---

## Definition of Done (DoD)

### DoD-260209-1 — Functional completion

- DoD-260209-1.1 Manual Matplotlib UI matches all Specs S-260209-x
- DoD-260209-1.2 Legend reliably shows handles for all plotted series
- DoD-260209-1.3 Help overlay behavior is deterministic and non-intrusive
- DoD-260209-1.4 Exit semantics are unambiguous and consistent
- DoD-260209-1.5 No wav-to-freq logic is modified as part of this change

---

## Follow-up

Next spec will cover **wav-to-freq**, including:

- Ownership and enforcement of `max_peaks`
- "run preprocess only" workflow

