# handoff_260203_1.md

## Scope

This handoff covers **UX/UI and API refinements** for the `envelope-decay-fit` manual segmentation tool, targeting a **human‑QA‑driven MVP**. The intent is to lock a *definition of done* so changes converge cleanly and do not regress interaction quality while batch‑processing many files.

---

## Specs

### S-260203-1.1 — Display active natural frequency (fₙ)
- The UI **must always indicate** which natural frequency `f_n` (Hz) is used for damping ratio (ζ) calculations.
- The indication must be visible **without user interaction** (no hover, no key press).
- `f_n` must appear:
  - In a persistent UI state/info area, and
  - In the figure itself (so screenshots are self‑contained).

**Rationale:** Prevents ambiguity during manual QA and when sharing figures.

---

### S-260203-1.2 — Log‑scale y‑axis by default
- The plot must **start in log(y)** scale on first render.
- A keyboard toggle (`l`) may switch between linear and log.
- The current scale state must be reflected in the UI state indicator.

**Rationale:** Envelope decay interpretation and curve fitting are primarily log‑space tasks.

---

### S-260203-1.3 — Plot title control via API
- The plotting API must allow the caller to **append and/or replace** the plot title.
- This must be optional and non‑breaking.
- Typical use case: batch processing context such as
  - filename,
  - hit index / progress,
  - dataset or campaign identifier.

**Rationale:** Gives external callers (e.g. batch pipelines) contextual feedback without UI hacks.

---

### S-260203-1.4 — Editing allowed while zooming/panning
- Keyboard editing actions (`a` add boundary, `x` delete boundary) **must remain enabled** while zoom or pan tools are active.
- Zoom/pan must be treated as **view transforms only**, not editing modes.
- No artificial blocking of edit keys based on toolbar state.

**Rationale:** Previous blocking was tied to mouse‑click editing. With keyboard‑only edits, the constraint is legacy and unnecessary.

---

### S-260203-1.5 — Increased UI font sizes
- All visible matplotlib text elements must be **approximately 2× larger** than current defaults:
  - title
  - axis labels
  - tick labels
  - legend
  - on‑screen help / state overlays
- The legend must not obscure the data region.

**Rationale:** Manual QA sessions are long; readability directly impacts accuracy and fatigue.

---

## Implementation Notes

### I-260203-1.1 — fₙ propagation and display
- Ensure `fn_hz` is passed end‑to‑end:
  - API → plotting function → UI overlay.
- Render `f_n` in:
  - a fixed text overlay (e.g. top‑right state block), and
  - a concise in‑figure annotation or subtitle.

---

### I-260203-1.2 — Default log scale
- Set `ax.set_yscale("log")` during initial figure creation.
- Ensure the scale toggle updates both axes and UI state text.

---

### I-260203-1.3 — Title API extension
- Extend plotting function signature with optional parameters, e.g.:
  - `title: Optional[str] = None`
  - `title_mode: Literal["append", "replace"] = "append"`
- If no title is provided, preserve current behavior.

---

### I-260203-1.4 — Remove zoom/edit coupling
- Remove any conditional logic that disables `a` / `x` based on toolbar zoom/pan state.
- Cursor‑based boundary placement must always use **current data coordinates**, regardless of zoom.

---

### I-260203-1.5 — Font scaling strategy
- Apply font size increases locally to the figure/UI layer:
  - avoid global `matplotlib.rcParams` side effects where possible.
- Explicitly set font sizes for overlays created via `ax.text()`.

---

## Tests

### T-260203-1.1 — Launch sanity test
- A minimal launch test must exist to ensure the manual UI can be instantiated without errors.
- The test may:
  - launch the plotting/UI entry point headlessly (non-interactive backend), or
  - validate figure creation without blocking on `plt.show()`.
- Purpose is **regression detection**, not visual validation.

---

### T-260203-1.2 — API-level pytest coverage
- Lightweight `pytest` tests must be added for non-interactive logic, at minimum:
  - default y-scale is log,
  - title append / replace behavior,
  - propagation of `fn_hz` into returned figure metadata (e.g. title or annotations).
- Tests must not require manual interaction or GUI focus.

**Note:** Full UI interaction testing is explicitly out of scope; these tests exist to guard against accidental breakage during refactors.

---

## Definition of Done

The work is considered **done** when all of the following are true:

- On launch, the plot:
  - starts in **log(y)** scale,
  - visibly displays `f_n = … Hz`.
- Pressing `a` or `x`:
  - works identically whether zoom/pan is active or not.
- The caller can inject contextual title information via the API without modifying UI code.
- All text in the matplotlib window is clearly readable at a glance on a standard laptop display.
- A full manual pass through multiple files can be performed **without ambiguity about fₙ, scale, or edit mode**.

---

## Non‑Goals / Explicit Exclusions
- No changes to ζ mathematics or fitting algorithms.
- No automation or batch orchestration logic.
- No persistence of UI state between sessions.

---

## Status

This handoff locks **UX and API behavior only** and is intended to unblock final human QA before broader integration.

