Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(feat) Piano roll: vertical zoom and Fit to notes (#43) (#98)
Egor Khindikaynend724fb5170e8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6fd1f808..4019cbf4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,15 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.## [Unreleased]+### Added+- **Piano roll vertical zoom** (nota-daw/nota#43): make rows taller to hit notes precisely,+ or shorter to see the whole keyboard (6–36 px; at the smallest, all 88 keys fit in about+ 530 px). Zoom with ⌘⌥ + wheel (Ctrl + Alt on Windows and Linux), by dragging on the keys+ (down taller, up shorter), or with ⌥ + pinch on a trackpad. The pitch under the pointer+ stays put. **Fit to notes** (⇧F, the "Fit" button in the clip editor header, or the+ command palette) zooms and scrolls so every note of the clip is in view. Each clip+ remembers its own zoom.+### Fixed- **Notes no longer cut off at the loop seam** (nota-daw/nota#29): when the loop jumpsback to its start, a key you're holding keeps sounding and release tails (pads, strings)diff --git a/FEATURES.md b/FEATURES.mdindex af732581..7fadba4d 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -233,7 +233,13 @@ track count and closes with Escape.- **Remove out of scale** (next to the Scale key and mode) deletes every note outside thescale in one undo step.- Zoomed out, the area past the clip's end is darkened and marked with a line.- - Scroll and zoom are remembered per clip; a new clip centres on its own notes.+ - **Vertical zoom**: rows from 6 to 36 px (all 88 keys fit at the smallest) with+ ⌘⌥ + wheel (Ctrl + Alt on Windows / Linux), a drag on the keys (down taller, up+ shorter) or ⌥ + pinch on a trackpad, keeping the pitch under the pointer in place.+ **Fit to notes** (⇧F, the **Fit** button in the clip editor header, or the command+ palette) sizes and scrolls the rows so every note of the clip is in view.+ - Scroll and both zooms are remembered per clip; a new clip opens at the default row+ height, centred on its own notes.- A MIDI clip trimmed in the arrangement mutes note tails at its boundary.- Live edits (moving a note, changing its length) reach the engine immediately, and awhole drag is a single undo step.diff --git a/specs/019-piano-roll-vertical-zoom/checklists/requirements.md b/specs/019-piano-roll-vertical-zoom/checklists/requirements.mdnew file mode 100644index 00000000..3e120e87--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/checklists/requirements.md@@ -0,0 +1,36 @@+# Specification Quality Checklist: Piano roll vertical zoom++**Purpose**: Validate specification completeness and quality before proceeding to planning+**Created**: 2026-10-16+**Feature**: [spec.md](../spec.md)++## Content Quality++- [x] No implementation details (languages, frameworks, APIs)+- [x] Focused on user value and business needs+- [x] Written for non-technical stakeholders+- [x] All mandatory sections completed++## Requirement Completeness++- [x] No [NEEDS CLARIFICATION] markers remain+- [x] Requirements are testable and unambiguous+- [x] Success criteria are measurable+- [x] Success criteria are technology-agnostic (no implementation details)+- [x] All acceptance scenarios are defined+- [x] Edge cases are identified+- [x] Scope is clearly bounded+- [x] Dependencies and assumptions identified++## Feature Readiness++- [x] All functional requirements have clear acceptance criteria+- [x] User scenarios cover primary flows+- [x] Feature meets measurable outcomes defined in Success Criteria+- [x] No implementation details leak into specification++## Notes++- The only code reference (`RowH = 12`, `PianoRollView.cs`) is in the quoted Input line, kept verbatim from the issue.+- Pixel bounds (6 / 12 / 36 px), keys-column drag direction and the ⇧F shortcut were confirmed in `/speckit-clarify` (Session 2026-10-16).+- No [NEEDS CLARIFICATION] markers: all open choices had reasonable defaults (fit = vertical only, all notes; persistence = per clip, session-only).diff --git a/specs/019-piano-roll-vertical-zoom/contracts/ui-gestures.md b/specs/019-piano-roll-vertical-zoom/contracts/ui-gestures.mdnew file mode 100644index 00000000..9dfc9ec2--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/contracts/ui-gestures.md@@ -0,0 +1,44 @@+# UI contract: piano roll vertical zoom++The user-facing surface this feature adds. ⌘ = Ctrl and ⌥ = Alt on Windows/Linux.++## Gestures++| Where | Input | Effect | Anchor |+|-------|-------|--------|--------|+| Note grid, keys column | ⌘⌥ + wheel / two-finger scroll | Rows taller (scroll up) / shorter (scroll down), factor 1.2 per notch | Pitch under the pointer |+| Keys column | Press + drag vertically | Down = taller, up = shorter, ~2.7× per 100 px; X ignored; no note created or played | Key pressed, held at the press height |+| Note grid (macOS trackpad) | ⌥ + pinch | Pinch out = taller, in = shorter | Pitch under the pointer |+| Note grid (focused) | ⇧F | Fit to notes | — |++Unchanged: wheel = vertical scroll, ⌘ + wheel = horizontal zoom, ⇧ + wheel / horizontal+swipe = horizontal scroll, pinch without ⌥ = no effect (as today).++Zoom input is ignored while a note move, resize or box selection is in progress.++## Limits++Row height 6–36 px, default 12 px. Zooming past a limit is a no-op.++## Command++| Id | Title | Category | Gesture | Aliases | Available when |+|----|-------|----------|---------|---------|----------------|+| `roll.fitNotes` | Fit to notes | Piano roll | ⇧F | zoom vertical rows height | A MIDI clip is open ("Open a MIDI clip first") |++Behaviour: all clip notes visible with one row of margin above and below, row height+clamped to the limits and the range centred; an empty clip returns to 12 px around C5.++## Header control++A neutral "Fit" chip (same style as the header's "Tools" chip) in the clip editor+header's right group, before the snap chip; tooltip "Fit to notes (⇧F)"; runs Fit to notes.++## Preferences → Shortcuts ("Piano roll" section)++| Keys | Description |+|------|-------------|+| ⌘⌥ + wheel | Zoom rows (vertical zoom) |+| Drag on the keys | Zoom rows · down taller, up shorter |+| ⌥ + pinch | Zoom rows (trackpad) |+| ⇧F | Fit to notes |diff --git a/specs/019-piano-roll-vertical-zoom/data-model.md b/specs/019-piano-roll-vertical-zoom/data-model.mdnew file mode 100644index 00000000..bb17b69e--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/data-model.md@@ -0,0 +1,32 @@+# Data model: Piano roll vertical zoom++View state only. Nothing is added to the project document, the engine or the C ABI.++## Piano roll view state (per clip)++Existing in-memory record in `PianoRollView`, keyed by the clip identity+`(int, int)` set through `SetClipIdentity`, living in a static dictionary for the app+session.++| Field | Type | Status | Rule |+|-------|------|--------|------|+| `Ppb` | double | existing | horizontal zoom, pixels per beat, 6–400 |+| `Scroll` | double | existing | horizontal scroll, beats ≥ 0 |+| `VOffset` | double | existing | vertical scroll offset, px ≥ 0 |+| `HasV` | bool | existing | state was saved after layout |+| `RowH` | double | **new** | row height, px, clamped to 6–36; absent/first open → 12 |++### Rules++- Written on every zoom, scroll and fit (same `SaveView` call sites, plus the new zoom+ paths).+- Restored in `SetNotes` before the first layout; out-of-range values are clamped.+- One entry per clip; zooming one clip never changes another clip's entry+ (clarification Q1).+- Not undoable, does not mark the project modified, not persisted to disk.++## Derived values++- Total grid height = 88 × `RowH` (A0..C8).+- Max vertical offset = max(0, 88 × `RowH` − viewport height).+- Fit-to-notes row height = clamp(viewport height ÷ (note span + 2), 6, 36).diff --git a/specs/019-piano-roll-vertical-zoom/plan.md b/specs/019-piano-roll-vertical-zoom/plan.mdnew file mode 100644index 00000000..9c322f8a--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/plan.md@@ -0,0 +1,124 @@+# Implementation Plan: Piano roll vertical zoom++**Branch**: `019-piano-roll-vertical-zoom` | **Date**: 2026-10-16 | **Spec**: [spec.md](spec.md)++**Input**: Feature specification from `/specs/019-piano-roll-vertical-zoom/spec.md`++## Summary++Make the piano roll's row height variable (6–36 px, default 12) and drive it with+⌘⌥ + wheel, a vertical drag on the keys column and ⌥ + trackpad pinch, all anchored on+the pitch under the pointer, plus a **Fit to notes** command (⇧F, header button, command+palette). The fixed `RowH` constant in `PianoRollView` becomes instance state saved in the+existing per-clip view state. UI-only: no engine, ABI or project-format change.++## Nota: Read Before Planning++- **UI work** → [`DESIGN.md`](../../DESIGN.md) (Studio) and the `nota-design` skill — the+ Fit button is a neutral header control, not accent.+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md).+- Engine / instrument / build docs: not touched.++## Technical Context++**Language/Version**: C# / .NET 10 (managed app only)++**Primary Dependencies**: Avalonia 12.0.3 (existing) — uses+`InputElement.PointerTouchPadGestureMagnifyEvent`; no new dependency++**Storage**: N/A — per-clip view state stays in memory for the app session++**Audio-Thread Impact**: None: UI-only change; no engine calls added++**Testing**: Smoke test unchanged (no engine change); feature verified with the headless+Avalonia harness and manual scenarios in [quickstart.md](quickstart.md)++**Target Platform**: macOS, Windows, Linux desktop (pinch: wherever Avalonia raises the+touchpad magnify event — macOS)++**Project Type**: desktop app++**Performance Goals**: Zoom follows the wheel/drag at display rate; the grid already+redraws all 88 rows per frame, unchanged in cost++**Constraints**: Existing wheel meanings unchanged; ⇧F must not sound a note while the+grid has focus; zoom ignored mid note-gesture++**Scale/Scope**: ~4 files edited, no new source files++## Constitution Check++*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*++| Principle | Status | Note |+|-----------|--------|------|+| I. Real-time audio safety | ✅ Pass | No audio-thread code touched |+| II. Boundary discipline | ✅ Pass | No ABI change, no JUCE |+| III. Licensing hygiene | ✅ Pass | No new files expected; any new file gets the SPDX header; no dependency |+| IV. Verification gate | ✅ Pass | `scripts/build.sh` must stay green; no engine behaviour change → no smoke-test extension |+| V. One logical change per PR | ✅ Pass | One feature, one PR |+| VI. Docs in sync | ✅ Planned | CHANGELOG `[Unreleased]` Added entry; `nota-features`, `nota-docs`, `nota-shortcuts` skills |+| VII. Spec-first | ✅ Pass | spec → clarify → plan done |+| VIII. Safety rules not weakened | ✅ Pass | — |++**Post-design re-check**: still all pass — the design (research R1–R10) stays inside+`Nota.App` and `Nota.Application/Palette`.++## Design++See [research.md](research.md) for decisions and alternatives. In short:++1. **Row height as state** (R1): `RowH` → instance property; `MinRowH/DefaultRowH/MaxRowH`+ = 6/12/36; `RangeH`, `PitchToY`, `YToPitch` become instance members; nested+ `KeysColumn` / `NoteGrid` read `_o.RowH`.+2. **Anchored zoom** (R2): `ZoomRowsAt(factor, viewportY)` and `SetRowHeightAt(h,+ viewportY)` resize `_keys` / `_gridControl` and queue the anchored offset via the+ existing `_pendingVOffset` / `ApplyPendingVOffset` path; `SaveView`.+3. **Inputs** (R3–R6): ⌘⌥ branch first in `NoteGrid.OnPointerWheelChanged` + new+ `KeysColumn.OnPointerWheelChanged`; keys-column press/drag/release with capture+ (exponential 0.01/px); ⌥ + `PointerTouchPadGestureMagnify` on the grid; all ignored+ while `_drag != Mode.None`.+4. **Fit to notes** (R7): `FitToNotes()` on the view; ⇧F in `NoteGrid.OnKeyDown`+ (handled, so the window's note map never sees it); `roll.fitNotes` in+ `CommandCatalog` + `MainWindow.Commands`; a Fit icon button in `ClipEditorView`'s header.+5. **Persistence** (R8): `ViewState` gains `RowH`; restored and clamped in `SetNotes`;+ default 12 for new clips.+6. **Shortcuts list**: four rows in `PreferencesWindow`'s "Piano roll" section+ ([contract](contracts/ui-gestures.md)).++## Project Structure++### Documentation (this feature)++```text+specs/019-piano-roll-vertical-zoom/+├── plan.md # this file+├── research.md # Phase 0+├── data-model.md # Phase 1+├── quickstart.md # Phase 1+├── contracts/+│ └── ui-gestures.md # Phase 1: gestures, command, header control, shortcuts rows+└── tasks.md # Phase 2 (/speckit-tasks)+```++### Source Code (repository root)++```text+src/managed/+├── Nota.App/+│ ├── PianoRollView.cs # RowH state, zoom/fit, wheel/drag/pinch/⇧F, view state+│ ├── ClipEditorView.cs # header Fit button+│ ├── MainWindow.Commands.cs # bind roll.fitNotes+│ └── PreferencesWindow.cs # Shortcuts rows+└── Nota.Application/+ └── Palette/CommandCatalog.cs # roll.fitNotes entry++CHANGELOG.md, FEATURES.md # docs; ../nota-docs via the nota-docs skill+```++**Structure Decision**: Presentation-only change inside the existing `Nota.App` piano+roll and the palette catalog in `Nota.Application`; no new projects or files.++## Complexity Tracking++No constitution violations — nothing to justify.diff --git a/specs/019-piano-roll-vertical-zoom/quickstart.md b/specs/019-piano-roll-vertical-zoom/quickstart.mdnew file mode 100644index 00000000..481d2a2a--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/quickstart.md@@ -0,0 +1,42 @@+# Quickstart: validating piano roll vertical zoom++## Prerequisites++- `scripts/build.sh` passes (builds native + managed, runs the smoke test — unaffected:+ no engine change).+- Isolate app data with `NOTA_DATA_DIR=<tmp dir>` for UI runs (`HOME` does not isolate+ JUCE).+- Test clips: A) notes C3..C5; B) one note E4; C) empty; D) notes A0 and C8.++## Scenarios++Gestures and limits: [contracts/ui-gestures.md](contracts/ui-gestures.md). State rules:+[data-model.md](data-model.md).++| # | Steps | Expected |+|---|-------|----------|+| 1 | Open clip A, ⌘⌥-scroll up over E4 | Rows grow, E4 stays under the pointer (US1-1) |+| 2 | Keep zooming in / out past the limits | Stops at 36 px / 6 px, no jump (US1-2/3) |+| 3 | At 6 px and 36 px: click to add, drag, resize, box-select notes | The pitch edited is the one under the pointer (SC-004) |+| 4 | Plain wheel, ⌘-wheel, ⇧-wheel | Vertical scroll, horizontal zoom, horizontal scroll — as before |+| 5 | At 6 px with a panel ≥ 540 px tall | All 88 keys visible, range pinned to the top (SC-001) |+| 6 | Press C4 on the keys, drag down then up | Taller then shorter, C4 stays at press height, no note sounds (US3) |+| 7 | ⌥ + pinch on a Mac trackpad | Rows zoom anchored at the pointer (US4) |+| 8 | Clip A zoomed elsewhere, press ⇧F in the grid | C3..C5 fill the view with one row margin; no note F plays (US2-1) |+| 9 | Clip D, Fit; clip B, Fit; clip C, Fit | Min height centred; ≤ 36 px centred on E4; 12 px around C5 (US2-2/3/4) |+| 10 | Select two notes in clip A, Fit | Fits all notes, not the selection (US2-5) |+| 11 | Header "Fit" button; palette "Fit to notes" | Same as ⇧F |+| 12 | Zoom clip A, open clip B, back to A | A restores its zoom and position; B opens at 12 px (SC-005, Q1) |+| 13 | Zoom, then ⌘Z | Undo does not touch the zoom; project not marked modified (FR-010) |+| 14 | Start a note drag and ⌘⌥-scroll mid-drag | Zoom ignored until release |+| 15 | Hold keys / record MIDI while zoomed | Held-key highlights match the row height |+| 16 | Preferences → Shortcuts → Piano roll | Lists the four new rows |+| 17 | ⇧F with focus outside the piano roll | Behaves as before |++## Headless capture++Use the recipe in agent memory `nota-ui-verify`: a throwaway console project referencing+`Nota.App.csproj` with `Avalonia.Headless` + `Avalonia.Skia` 12.0.3, host a+`PianoRollView` in a `Window`, seed the clips above with `SetClipIdentity` + `SetNotes`,+raise synthetic `PointerWheelEventArgs` / pointer press-move-release on the grid and keys+column, and `CaptureRenderedFrame()` at 6 / 12 / 36 px and after Fit.diff --git a/specs/019-piano-roll-vertical-zoom/research.md b/specs/019-piano-roll-vertical-zoom/research.mdnew file mode 100644index 00000000..6f8d3d85--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/research.md@@ -0,0 +1,116 @@+# Research: Piano roll vertical zoom++Findings from reading the current piano roll (`src/managed/Nota.App/PianoRollView.cs`,+`ClipEditorView.cs`, `MainWindow.Input.cs`, `MainWindow.Commands.cs`,+`Nota.Application/Palette/CommandCatalog.cs`, `PreferencesWindow.cs`) and the Avalonia+12.0.3 API.++## R1 — Where the row height lives++- **Decision**: Replace `private const double RowH = 12` with an instance property+ `RowH` backed by `_rowH`, plus `MinRowH = 6`, `DefaultRowH = 12`, `MaxRowH = 36`.+ `RangeH`, `PitchToY` and `YToPitch` (static today) become instance members; the nested+ controls (`KeysColumn`, `NoteGrid`) read `_o.RowH`.+- **Rationale**: Every row-dependent draw and hit-test already goes through `RowH`+ (~40 uses, all in `PianoRollView.cs`; `PianoRollView.Expression.cs` uses none), so one+ source of truth covers FR-008 without touching the drawing logic.+- **Alternatives considered**: A `ScaleTransform` on the body — rejected: it would scale+ note text, pens and the keys column width too, and hit-testing would still be in+ unscaled rows.++## R2 — Anchored zoom math++- **Decision**: One method `ZoomRowsAt(double factor, double viewportY)`. With+ `off` = current vertical offset and `h0`/`h1` the old/new row heights, the content+ position under the pointer is `c = off + viewportY`; the new offset is+ `c * h1 / h0 - viewportY`, clamped to `[0, max(0, 88·h1 − viewportHeight)]`. The new+ `Height` is set on `_keys` / `_gridControl`, and the offset goes through the existing+ `_pendingVOffset` → `ApplyPendingVOffset` path, because the ScrollViewer's extent only+ grows after the next layout pass.+- **Rationale**: The same anchor formula `ZoomAt` uses horizontally; reusing the pending+ offset path avoids a clamp against the stale extent (which would make zoom-in near the+ bottom jump).+- **Alternatives considered**: Setting `Offset` synchronously after `UpdateLayout()` —+ works but forces a layout per wheel event; the pending path is already there.++## R3 — Wheel gesture++- **Decision**: In `NoteGrid.OnPointerWheelChanged`, test **(⌘ or Ctrl) and ⌥** first →+ `ZoomRowsAt(WheelInput.ZoomFactor(e.Delta.Y, 1.2), y-in-viewport)`; the existing+ branches (⌘/Ctrl = horizontal zoom, Shift, horizontal swipe) follow unchanged. Add the+ same ⌘⌥ branch to a new `KeysColumn.OnPointerWheelChanged` (plain wheel there stays with+ the ScrollViewer).+- **Rationale**: FR-002/FR-003. Today ⌘⌥+wheel falls into the ⌘ branch (horizontal zoom),+ so checking ⌥ first is the only change to existing meaning — a combination nobody+ relies on.+- **Note**: `ClipEditorView`'s `RouteWheel` (ruler / lane rows) keeps horizontal only —+ vertical zoom is about rows, which those rows don't show.++## R4 — Keys-column drag++- **Decision**: `KeysColumn` gets `OnPointerPressed` (left button → capture, remember the+ press Y in `_bodyScroll` viewport coordinates and the row height at press),+ `OnPointerMoved` while captured (`h = clamp(h0 · exp(dy · 0.01))`, applied via a+ `SetRowHeightAt(h, pressViewportY)` sibling of R2), `OnPointerReleased` /+ `OnPointerCaptureLost` end it. Down (positive dy) = taller. X is ignored.+- **Rationale**: The keys column has no press handling today (only hover), so there is no+ conflict and nothing auditions (FR-004). Exponential mapping makes equal drags equal+ zoom ratios; 0.01/px gives ~2.7× per 100 px, which covers 6→36 px in ~180 px.+- **Alternatives considered**: Linear px→px mapping — feels sluggish at small heights and+ jumpy at large ones.++## R5 — Trackpad pinch++- **Decision**: `AddHandler(InputElement.PointerTouchPadGestureMagnifyEvent, …)` on the+ note grid; when ⌥ is held, `ZoomRowsAt(1 + e.Delta.X, y)` and mark handled.+- **Rationale**: Avalonia 12 exposes `PointerTouchPadGestureMagnify`+ (`PointerDeltaEventArgs`, "two contact points moving apart on a touchpad"); it is raised+ by the macOS backend. On platforms that never raise it nothing changes (US4 scenario 2).+- **Alternatives considered**: `Gestures.PinchEvent` — that is the touchscreen pinch+ recogniser, not the touchpad.++## R6 — Zoom during a note gesture++- **Decision**: Ignore vertical-zoom input while `NoteGrid._drag != Mode.None` (move,+ resize, marquee in progress).+- **Rationale**: Simplest way to guarantee SC-004; the drag state stores grab offsets in+ pixels, and re-deriving them mid-gesture is risk with no user value.++## R7 — Fit to notes and ⇧F++- **Decision**: `PianoRollView.FitToNotes()`: empty clip → `DefaultRowH` and the existing+ `CenterOffsetForNotes()` C5 fallback; otherwise `span = maxP − minP + 1 + 2` (one margin+ row each side), `h = clamp(viewportHeight / span, MinRowH, MaxRowH)`, then centre on the+ notes (the existing centring helper, which now uses the instance `RowH`). Uses all notes+ regardless of selection.+- **Shortcut**: handle `Key.F` with exactly Shift in `NoteGrid.OnKeyDown`, set `Handled`.+ Because the grid is the focused source, the event never reaches `MainWindow.OnKeyDown`+ (a class handler that skips handled events), so the note map's Shift-agnostic `F`+ (`mod` excludes Shift) does not sound a note. Outside the grid, ⇧F is untouched.+- **Palette**: `C("roll.fitNotes", "Fit to notes", "Piano roll", "⇧F", "zoom vertical rows+ height")` in `CommandCatalog`, bound with the existing `Roll` availability in+ `MainWindow.Commands`.+- **Header**: a "Fit" chip (the header's existing `chip` style, like "Tools") in+ `ClipEditorView`'s right header group, before the snap chip, tooltip "Fit to notes (⇧F)" —+ per DESIGN.md, neutral, not accent.++## R8 — Persistence++- **Decision**: Add `RowH` to the per-clip `ViewState` record; `SaveView` writes it,+ `SetNotes` restores it (clamped); a clip without saved state gets `DefaultRowH`+ (clarification 1 and 2). Not undoable, not saved to the project (FR-009/FR-010).+- **Rationale**: Same scope and lifetime as horizontal zoom and scroll today.++## R9 — Key labels at small/large rows++- **Decision**: Keep labelling only C rows (plus the hovered/held key, as today). The+ label is centred on its row and may overflow a short row; with C rows ≥ 72 px apart at+ the 6 px minimum, labels never collide.+- **Rationale**: FR-011 is already met by the sparse labelling; no thinning logic needed.++## R10 — Verification++- **Decision**: No managed unit-test project exists; the smoke test covers the engine and+ is unaffected (no engine change). Verify with the headless Avalonia harness (agent memory+ `nota-ui-verify`): host `PianoRollView` in a `Window`, seed notes, drive zoom through+ synthetic wheel/pointer events and capture frames at 6 / 12 / 36 px and after Fit.diff --git a/specs/019-piano-roll-vertical-zoom/spec.md b/specs/019-piano-roll-vertical-zoom/spec.mdnew file mode 100644index 00000000..05ee2c0c--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/spec.md@@ -0,0 +1,182 @@+# Feature Specification: Piano roll vertical zoom++**Feature Branch**: `019-piano-roll-vertical-zoom`++**Created**: 2026-10-16++**Status**: Clarified++**Input**: User description: "Piano roll: vertical zoom (GitHub issue nota-daw/nota#43). Users want to edit notes comfortably in the clip editor (piano roll): see more of the keyboard range at once, or make rows taller to hit notes precisely. Add vertical zoom to the piano roll — e.g. Cmd/Ctrl + Alt + mouse wheel, a trackpad zoom gesture, or dragging on the keys column — plus a \"fit to notes\" option. Today the row height is fixed (RowH = 12 in PianoRollView.cs); only horizontal zoom exists."++## Nota Context *(fill in — drives plan and tasks)*++**Feature area** *(pick the main one)*:++- [ ] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table+- [ ] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation+- [x] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed+- [ ] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`+- [ ] Docs only++**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),+[`FEATURES.md`](../../FEATURES.md).++## Clarifications++### Session 2026-10-16++- Q: When you zoom rows vertically in one clip, should that row height apply only to that clip, or to every clip you open? → A: Per clip — each clip remembers its own row height; a clip never opened before starts at the default (12 px).+- Q: When you open a clip for the first time, should the piano roll automatically fit the view to its notes, or keep today's behaviour? → A: Keep today's behaviour — default row height (12 px), centred on the clip's notes; Fit to notes runs only when the user invokes it.+- Q: When you press on the keys column and drag, what should the drag do? → A: A vertical drag zooms: down makes rows taller, up makes them shorter, and the pressed key stays where it was; a horizontal drag does nothing.+- Q: Which keyboard shortcut should trigger "Fit to notes" in the piano roll? → A: ⇧F (Shift+F) — it must take priority over the computer-keyboard note map (which today also fires on Shift+F) while the piano roll has focus, so it fits without playing a note; elsewhere Shift+F is unchanged.+- Q: What row-height limits should vertical zoom have (min / default / max, at 100% UI scale)? → A: 6 / 12 / 36 px.++## User Scenarios & Testing *(mandatory)*++### User Story 1 - Zoom rows with the wheel (Priority: P1)++A user editing a clip in the piano roll holds ⌘ + ⌥ (Ctrl + Alt on Windows/Linux) and turns+the mouse wheel (or scrolls on a trackpad). Rows get taller or shorter, and the pitch under+the pointer stays under the pointer, so they can zoom into a dense chord or out to see a+wide melodic range without losing their place.++**Why this priority**: This is the core of the request — without a way to change row height+nothing else matters. It mirrors the existing ⌘/Ctrl + wheel horizontal zoom, so it is the+gesture users will try first.++**Independent Test**: Open a clip, ⌘⌥-scroll over a note: rows change height, the note stays+under the pointer, the keys column, note grid and all note-height-dependent drawing (notes,+held-key highlights, scale tints, expression curves) stay aligned.++**Acceptance Scenarios**:++1. **Given** a clip open in the piano roll at default row height, **When** the user ⌘⌥-scrolls up over pitch E4, **Then** rows get taller and E4 stays under the pointer.+2. **Given** rows at the maximum height, **When** the user ⌘⌥-scrolls to zoom in further, **Then** nothing changes (no jump, no error).+3. **Given** rows at the minimum height, **When** the user ⌘⌥-scrolls to zoom out further, **Then** nothing changes.+4. **Given** any vertical zoom level, **When** the user clicks, drags, resizes, draws or box-selects notes, **Then** the pitch picked is the one visibly under the pointer.+5. **Given** a zoomed view, **When** the user plain-wheel scrolls / ⌘-wheel zooms / Shift-wheel scrolls, **Then** those keep their current meanings (vertical scroll, horizontal zoom, horizontal scroll).++---++### User Story 2 - Fit to notes (Priority: P2)++A user opens a clip whose notes span two octaves somewhere in the middle of the keyboard.+They invoke **Fit to notes** and the piano roll sets the row height and vertical scroll so+that every note in the clip is visible, with a little margin above and below.++**Why this priority**: Explicitly requested; gives a one-step way back to a useful view+after zooming around, and makes the most of the screen for any clip.++**Independent Test**: Open a clip with notes from C3 to C5, zoom in somewhere else, invoke+Fit to notes: C3..C5 are all visible and fill most of the visible height.++**Acceptance Scenarios**:++1. **Given** a clip with notes spanning C3..C5 and the view zoomed in on C6, **When** the user invokes Fit to notes, **Then** all notes C3..C5 are visible and the range fills the visible height (within the row-height limits) with about one row of margin above and below.+2. **Given** a clip whose note span is too wide to fit even at minimum row height, **When** the user invokes Fit to notes, **Then** rows go to minimum height and the view is centred on the notes.+3. **Given** a clip with a single note (or one pitch), **When** the user invokes Fit to notes, **Then** rows go no taller than the maximum and the note is centred.+4. **Given** an empty clip, **When** the user invokes Fit to notes, **Then** the view returns to the default row height centred around C5 (the existing empty-clip default).+5. **Given** some notes are selected, **When** the user invokes Fit to notes, **Then** the fit uses all notes in the clip, not just the selection.++---++### User Story 3 - Drag on the keys column (Priority: P3)++A user presses on the keys column at the left of the piano roll and drags vertically. Dragging+one way makes rows taller, the other way shorter, anchored on the key where the drag started.++**Why this priority**: A discoverable mouse-only alternative for users without a wheel or who+don't know the modifier gesture; familiar from other DAWs. Nice to have once US1 exists.++**Independent Test**: Press on the keys column and drag up/down: rows zoom, the key pressed+stays under the pointer's start height; releasing ends the zoom.++**Acceptance Scenarios**:++1. **Given** the default view, **When** the user presses on the C4 key and drags downward, **Then** rows get taller and C4 stays at the press height.+2. **Given** the default view, **When** the user presses on the keys column and drags upward, **Then** rows get shorter.+3. **Given** a drag on the keys column, **When** the user releases, **Then** the zoom stays as it was at release and no note is created, changed or played.++---++### User Story 4 - Pinch on the trackpad (Priority: P3)++On a trackpad that reports a pinch/magnify gesture, the user pinches over the note grid+with ⌥ held and rows zoom, anchored at the pointer.++**Why this priority**: Requested as an option; useful for laptop users, but the ⌘⌥ + two-finger+scroll of US1 already covers trackpads, so this is the least critical path.++**Independent Test**: On a macOS trackpad, ⌥ + pinch over the grid changes row height anchored+at the pointer; without ⌥ the pinch does whatever it does today.++**Acceptance Scenarios**:++1. **Given** a clip open on a Mac with a trackpad, **When** the user holds ⌥ and pinches out over the grid, **Then** rows get taller anchored at the pointer.+2. **Given** a platform/device that reports no pinch gesture, **When** the user pinches, **Then** nothing breaks; US1–US3 still work.++---++### Edge Cases++- Zoom out until the whole 88-key range is shorter than the visible area: the range stays pinned to the top (no empty gap above A0..C8 jumping around) and scrolling does nothing.+- Zoom while a note drag / resize / box selection is in progress: the zoom is ignored until the gesture ends, or the gesture stays consistent with the new row height — never a note landing on a pitch the user didn't point at.+- Live MIDI recording / held-key highlights while zoomed: highlights follow the new row height.+- Pitch labels in the keys column at small row heights: labels that would not fit are thinned (e.g. only C-notes labelled) rather than overlapping.+- Re-opening a clip: its last vertical zoom comes back together with its scroll and horizontal zoom.+- Opening a clip never edited before: default row height, centred on its notes (today's behaviour) — no automatic Fit to notes.+- Window/panel resize: row height stays; only the visible range changes.+- Vertical zoom does not touch the velocity lane or the ruler heights.++## Requirements *(mandatory)*++### Functional Requirements++- **FR-001**: The piano roll MUST support a variable row height of 6 px minimum to 36 px maximum, with 12 px as the default (at 100 % UI scale).+- **FR-002**: ⌘ + ⌥ + wheel (Ctrl + Alt + wheel on Windows/Linux) over the note grid or keys column MUST zoom rows vertically, anchored on the pitch under the pointer.+- **FR-003**: Existing wheel meanings MUST NOT change: plain wheel scrolls vertically, ⌘/Ctrl + wheel zooms horizontally, Shift + wheel and horizontal wheel scroll horizontally.+- **FR-004**: Pressing and dragging vertically on the keys column MUST zoom rows, anchored on the key pressed (it stays at the press height); down = taller, up = shorter; horizontal movement is ignored. The drag MUST NOT create, edit or audition notes.+- **FR-005**: Where the platform reports a trackpad pinch/magnify gesture, ⌥ + pinch over the grid MUST zoom rows anchored at the pointer.+- **FR-006**: A **Fit to notes** command MUST set the row height and vertical scroll so all of the clip's notes are visible with about one row of margin above and below, limited by FR-001's bounds; an empty clip returns to the default height centred around C5. Fit to notes runs only when the user invokes it, never automatically on opening a clip.+- **FR-007**: Fit to notes MUST be reachable from the piano roll (a control in its header/toolbar area) and from the command palette, and MUST be bound to ⇧F (Shift+F) while the piano roll has focus. Pressing ⇧F there MUST fit without also playing a note through the computer-keyboard note map; outside the piano roll, Shift+F keeps its current behaviour.+- **FR-008**: Everything drawn or hit-tested per row (keys, lanes, scale tints, octave lines, notes, note edges, held-key highlights, expression curves, box selection, scroll-to-note behaviour) MUST follow the current row height.+- **FR-009**: The vertical zoom MUST be remembered per clip alongside the existing per-clip scroll and horizontal zoom, for the lifetime of the app session (same scope as those today). It is never shared between clips: zooming one clip leaves every other clip's row height unchanged, and a clip opened for the first time starts at the default row height.+- **FR-010**: Vertical zoom MUST NOT be an undoable edit and MUST NOT mark the project as modified.+- **FR-011**: Keys-column labels MUST stay legible at every row height (thin out labels when rows are too short to fit them).+- **FR-012**: The Preferences → Shortcuts list MUST show the new vertical-zoom gestures and the Fit to notes shortcut.++### Key Entities++- **Piano roll view state (per clip)**: horizontal zoom, horizontal scroll, vertical scroll, and now row height. View-only; not part of the project document.++## Success Criteria *(mandatory)*++### Measurable Outcomes++- **SC-001**: A user can see the full 88-key range at once at minimum zoom on a piano roll at least 540 px tall (88 × 6 px = 528 px).+- **SC-002**: At maximum zoom, rows are 3× the current default height, so a single pitch is three times easier to hit.+- **SC-003**: Fit to notes brings every note of a clip into view in one action, for any clip whose span fits at minimum row height.+- **SC-004**: In 100 % of pointer edits at any zoom level, the edited pitch is the one visibly under the pointer (no off-by-one-row hits).+- **SC-005**: Re-opening a clip shows the same vertical zoom and position the user left it at.++## Assumptions++- Fit to notes is vertical only; horizontal "fit to clip length" already happens on first open and is out of scope.+- Fit to notes considers all notes in the clip, ignoring the selection (a "fit to selection" variant is out of scope).+- Persistence of vertical zoom follows today's per-clip view state: in memory for the session, not saved into the project file.+- The pinch gesture (US4) depends on what the UI toolkit reports per platform; on platforms without it, US1–US3 suffice.+- No engine, ABI or audio-thread change; the feature is entirely in the piano-roll UI.++## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*++- [x] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)+- [x] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned+- [x] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5) — UI-only, no audio-thread involvement+- [x] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/` — no crossings added+- [x] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest` — no engine change; no smoke-test extension needed+- [ ] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them)+- [ ] UI change → follows `DESIGN.md` (Studio design language)diff --git a/specs/019-piano-roll-vertical-zoom/tasks.md b/specs/019-piano-roll-vertical-zoom/tasks.mdnew file mode 100644index 00000000..ef892469--- /dev/null+++ b/specs/019-piano-roll-vertical-zoom/tasks.md@@ -0,0 +1,175 @@+---++description: "Task list for piano roll vertical zoom"+---++# Tasks: Piano roll vertical zoom++**Input**: Design documents from `/specs/019-piano-roll-vertical-zoom/`++**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [contracts/ui-gestures.md](contracts/ui-gestures.md), [quickstart.md](quickstart.md)++**Tests**: Not requested in the spec. There is no managed unit-test project, and the engine is untouched, so the smoke test needs no extension. Verification is the headless capture plus the quickstart scenarios (Phase 7).++**Organization**: Tasks are grouped by user story so each one can be implemented and tested on its own.++## Format: `[ID] [P?] [Story] Description`++- **[P]**: Can run in parallel (different files, no dependencies)+- **[Story]**: Which user story this task belongs to (US1–US4)++Abbreviation: `PRV` = `src/managed/Nota.App/PianoRollView.cs`.++---++## Phase 1: Setup++**Purpose**: None needed. There are no new projects, packages or files (plan § Technical Context). Work starts at Phase 2.++---++## Phase 2: Foundational (Blocking Prerequisites)++**Purpose**: Turn the fixed row height into state that all zoom inputs and Fit share (research R1, R2, R8).++**⚠️ CRITICAL**: Every user story depends on this phase.++- [X] T001 Replace `private const double RowH = 12` with constants `MinRowH = 6`, `DefaultRowH = 12`, `MaxRowH = 36` and an instance field `_rowH = DefaultRowH` exposed as `internal double RowH => _rowH`. Make `RangeH` an instance property (`88 × RowH`). In `PRV`, make `NoteGrid.PitchToY` / `YToPitch` and the keys column's pitch-from-Y non-static and reading `_o.RowH`. Do the same for every `RowH` use in `KeysColumn.Render` / `DrawKeyLabel` (make `DrawKeyLabel` take the row height), `NoteGrid` rendering, hit-testing, marquee, expression curves (`v * RowH`), `CenterOffsetForNotes` (`12 * RowH` fallback), scroll-to-pitch (`EnsurePitchVisible`, ~line 836) and drag auto-scroll. Build and confirm the editor looks identical at 12 px.+- [X] T002 Add a `RowH` field to the `ViewState` record in `PRV` ("row height, px, clamped to 6–36; absent/first open → 12"). `SaveView` writes `_rowH`. `SetNotes` restores `Math.Clamp(vs.RowH, MinRowH, MaxRowH)` when saved state exists and sets `DefaultRowH` otherwise. `_keys.Height` / `_gridControl.Height = RangeH` must be applied **after** `_rowH` is set. Zooming one clip must never change another clip's entry (clarification Q1).+- [X] T003 Add `SetRowHeightAt(double h, double viewportY)` and `ZoomRowsAt(double factor, double viewportY) => SetRowHeightAt(_rowH * factor, viewportY)` to `PRV`, per research R2:+ - Clamp h to `[MinRowH, MaxRowH]`; return if unchanged.+ - Compute `c = _bodyScroll.Offset.Y + viewportY` and set the new offset to `c * h1 / h0 - viewportY`.+ - Set `_rowH`, then `_keys.Height` / `_gridControl.Height = RangeH`.+ - Queue the offset through `_pendingVOffset` and call `ApplyPendingVOffset()`. Its clamp against the extent pins the range to the top when 88 rows are shorter than the viewport.+ - Finish with `Invalidate()` and `SaveView()`.+ - Do nothing while a note gesture is active: expose `NoteGrid`'s `_drag != Mode.None` as `internal bool Dragging` and check it here (R6).+- [X] T004 Make `ApplyPendingVOffset` in `PRV` still run when the ScrollViewer extent hasn't caught up with the new `RangeH` yet. Retry on `LayoutUpdated` until `_bodyScroll.Extent.Height` ≥ `RangeH`, or clamp against `RangeH − viewport` directly. Otherwise zooming in near the bottom clamps against the old, smaller extent.++**Checkpoint**: Row height is per-clip state, and one method zooms it with an anchor. Nothing calls it yet.++---++## Phase 3: User Story 1 — Zoom rows with the wheel (Priority: P1) 🎯 MVP++**Goal**: ⌘⌥ + wheel (Ctrl + Alt on Windows/Linux) over the grid or the keys zooms rows, anchored at the pointer. All other wheel meanings stay the same.++**Independent Test**: Quickstart rows 1–5 and 15. At 6 / 12 / 36 px, edit notes and confirm the pitch under the pointer is the one edited.++- [X] T005 [US1] In `NoteGrid.OnPointerWheelChanged` (`PRV`, ~line 1507), add a first branch: when `(mods & (Control|Meta)) != 0 && (mods & Alt) != 0`, call `_o.ZoomRowsAt(WheelInput.ZoomFactor(e.Delta.Y, 1.2), e.GetPosition(_o._bodyScroll).Y)` and set `e.Handled = true`. The existing ⌘ (horizontal zoom), Shift and horizontal-swipe branches follow unchanged (FR-003).+- [X] T006 [US1] Add `OnPointerWheelChanged` to `KeysColumn` in `PRV` with the same ⌘⌥ branch, anchored at `e.GetPosition(_o._bodyScroll).Y`. Any other wheel input stays unhandled, so the ScrollViewer keeps scrolling.+- [X] T007 [US1] Update the header comments in `PRV` (file header, the horizontal zoom block, and the wheel handler comment) to describe vertical zoom and the ⌘⌥ gesture.++**Checkpoint**: The MVP is in place. Rows zoom with the wheel and nothing else changes.++---++## Phase 4: User Story 2 — Fit to notes (Priority: P2)++**Goal**: One action fits all of the clip's notes vertically. It's available as ⇧F in the grid, a header button and a palette command.++**Independent Test**: Quickstart rows 8–11 and 17.++- [X] T008 [US2] Add `public void FitToNotes()` to `PRV` (research R7):+ - Empty clip: `_rowH = DefaultRowH` and centre with the existing C5 fallback.+ - Otherwise, over **all** notes (ignore the selection): `span = maxP − minP + 1 + 2`, `h = clamp(viewportHeight / span, 6, 36)`.+ - Apply h, resize, then centre via `_pendingCenter = true; ApplyPendingVOffset()`.+ - Finish with `SaveView()` and `Invalidate()`. It is not undoable and doesn't mark the project modified (FR-010).+- [X] T009 [US2] In `NoteGrid.OnKeyDown` in `PRV`, handle `Key.F` when the modifiers are exactly Shift: call `_o.FitToNotes()` and set `e.Handled = true`. Handling it here means `MainWindow.OnKeyDown`'s note map never sees it, so no note F sounds. Put it before the selection-nudge block.+- [X] T010 [P] [US2] Add `C("roll.fitNotes", "Fit to notes", "Piano roll", "⇧F", "zoom vertical rows height")` after `roll.removeOutOfScale` in `src/managed/Nota.Application/Palette/CommandCatalog.cs`.+- [X] T011 [US2] Bind it in `src/managed/Nota.App/MainWindow.Commands.cs`: `B("roll.fitNotes", () => _editorRoll?.FitToNotes(), Roll);` next to the other `roll.*` bindings. Depends on T008 and T010.+- [X] T012 [P] [US2] Add a neutral "Fit" chip (header `chip` style, like "Tools") to the right header group in `ClipEditorView`, before `SnapControl(roll)` in `src/managed/Nota.App/ClipEditorView.cs`, then a `HeaderDivider()`. Give it the tooltip "Fit to notes (⇧F)" and make it call `roll.FitToNotes()`. Follow DESIGN.md / the `nota-design` skill: reuse the header's existing icon-button style (as `_toolsToggle` does) and no accent colour.++**Checkpoint**: US1 and US2 both work on their own.++---++## Phase 5: User Story 3 — Drag on the keys column (Priority: P3)++**Goal**: A vertical drag on the keys zooms rows. Dragging down makes them taller, and the pressed key stays where it was.++**Independent Test**: Quickstart row 6.++- [X] T013 [US3] In `KeysColumn` in `PRV`, add drag zoom (research R4):+ - `OnPointerPressed`, left button only: capture the pointer and store `_pressY = e.GetPosition(_o._bodyScroll).Y` and `_pressRowH = _o.RowH`. Mark it handled, and audition or create nothing.+ - `OnPointerMoved` while captured: `_o.SetRowHeightAt(_pressRowH * Math.Exp((y - _pressY) * 0.01), _pressY)`. Ignore X.+ - `OnPointerReleased` and `OnPointerCaptureLost`: release and clear the state.+ - Show the resize-vertical cursor while dragging. Keep the hover highlight working when not dragging.++**Checkpoint**: The mouse-only zoom works without the wheel.++---++## Phase 6: User Story 4 — Pinch on the trackpad (Priority: P3)++**Goal**: ⌥ + pinch on a trackpad zooms rows, anchored at the pointer.++**Independent Test**: Quickstart row 7, on a Mac trackpad.++- [X] T014 [US4] In the `NoteGrid` constructor in `PRV`, add `AddHandler(InputElement.PointerTouchPadGestureMagnifyEvent, OnMagnify)`. When `(e.KeyModifiers & Alt) != 0`, call `_o.ZoomRowsAt(1 + e.Delta.X, e.GetPosition(_o._bodyScroll).Y)` and set handled. Without ⌥, leave the event alone (research R5).++**Checkpoint**: All four stories work.++---++## Phase 7: Polish & Cross-Cutting Concerns++- [X] T015 [P] Add four rows to the "Piano roll" section of `src/managed/Nota.App/PreferencesWindow.cs`, using the exact text from [contracts/ui-gestures.md](contracts/ui-gestures.md): `⌘⌥ + wheel`, `Drag on the keys`, `⌥ + pinch`, `⇧F`. Run the `nota-shortcuts` skill to check them (FR-012).+- [X] T016 Verify headlessly following the [quickstart](quickstart.md) § Headless capture. Use a throwaway harness in the scratchpad with `NOTA_DATA_DIR` set. Seed clips A–D. Drive ⌘⌥-wheel, keys drag and ⇧F with synthetic events, then capture frames at 6 / 12 / 36 px and after Fit. Check the anchor pitch, that the range is pinned at 6 px, and that clips restore. Delete the harness afterwards.+- [X] T017 Walk through quickstart scenarios 1–17 and note any that couldn't be run headlessly (pinch, for example).++### Nota closing tasks *(the PR gates)*++- [X] T018 Run `scripts/build.sh` until native, managed and the smoke test are green.+- [X] T019 SPDX header on every new source file. N/A, no new files planned; re-check if any were added.+- [X] T020 New dependency: N/A (Avalonia already present).+- [X] T021 Add a `CHANGELOG.md` `[Unreleased]` → Added entry: piano roll vertical zoom (⌘⌥ + wheel, drag on the keys, ⌥ + pinch) and Fit to notes (⇧F), referencing #43.+- [X] T022 Update FEATURES.md via the `nota-features` skill and the user manual (EN + RU) via the `nota-docs` skill.+- [X] T023 Engine behaviour change → smoke test: N/A (UI only).++---++## Dependencies & Execution Order++### Phase Dependencies++- **Foundational (Phase 2)**: T001 → T002 → T003 → T004 run in order, all in `PRV`. It blocks every story.+- **US1 (Phase 3)**: Depends on Phase 2.+- **US2 (Phase 4)**: Depends on Phase 2 only, not on US1. T011 needs T008 and T010.+- **US3 / US4 (Phases 5–6)**: Depend on Phase 2 only.+- **Polish (Phase 7)**: After the stories you intend to ship. T015 can start any time.++### Within a story++Most tasks edit `PRV`, so tasks touching it run one at a time. Only the tasks in other files (T010, T012, T015) carry [P].++### Parallel Opportunities++- T010 (`CommandCatalog.cs`), T012 (`ClipEditorView.cs`) and T015 (`PreferencesWindow.cs`) can run alongside the `PRV` work.++## Parallel Example: User Story 2++```bash+# While T008/T009 edit PianoRollView.cs:+Task: "Add roll.fitNotes to src/managed/Nota.Application/Palette/CommandCatalog.cs" # T010+Task: "Add the Fit header button in src/managed/Nota.App/ClipEditorView.cs" # T012+```++---++## Implementation Strategy++### MVP First (User Story 1 only)++1. Phase 2 (T001–T004). Check that nothing looks different at 12 px.+2. Phase 3 (T005–T007). ⌘⌥ + wheel works. **Stop and validate** with quickstart rows 1–5.++### Incremental Delivery++1. Add US2 (Fit to notes). Validate with rows 8–11 and 17.+2. Add US3 (keys drag), then US4 (pinch).+3. Phase 7: shortcuts list, verification, docs and the build gate. The feature ships as a single PR (constitution V).++## Notes++- Spec traceability: FR-001 → T001–T003 · FR-002/003 → T005–T006 · FR-004 → T013 · FR-005 → T014 · FR-006/007 → T008–T012 · FR-008 → T001 · FR-009 → T002 · FR-010 → T003/T008 · FR-011 → T001 (research R9: only C rows are labelled, so no thinning is needed) · FR-012 → T015.+- Don't commit. The user reviews and commits the changes.diff --git a/src/managed/Nota.App/ClipEditorView.cs b/src/managed/Nota.App/ClipEditorView.csindex 3168d643..a3db78ae 100644--- a/src/managed/Nota.App/ClipEditorView.cs+++ b/src/managed/Nota.App/ClipEditorView.cs@@ -61,13 +61,22 @@ public sealed class ClipEditorView : UserControlvar right = new StackPanel{Orientation = Orientation.Horizontal, Spacing = 12,- Children = { SnapControl(roll), HeaderDivider(), ScaleControls(), HeaderDivider(), _toolsToggle },+ Children = { FitControl(roll), SnapControl(roll), HeaderDivider(), ScaleControls(), HeaderDivider(), _toolsToggle },};var header = Header(roll.TrackBrush, clipName, "MIDI", tabs, null, right);DockPanel.SetDock(header, Dock.Top);Content = new DockPanel { Background = NotaPalette.Gutter, Children = { header, grid } };}+ // Fit to notes (⇧F): rows zoom so every note of the clip is in view.+ private static Control FitControl(PianoRollView roll)+ {+ var b = new Button { Content = "Fit", Padding = new Thickness(10, 0), Classes = { "chip" } };+ ToolTip.SetTip(b, "Fit to notes (⇧F)");+ b.Click += (_, _) => roll.FitToNotes();+ return b;+ }+// The piano roll's snap chip: "Auto · 1/16", live with the roll's zoom; click for the grid menu.private static Control SnapControl(PianoRollView roll){diff --git a/src/managed/Nota.App/MainWindow.Commands.cs b/src/managed/Nota.App/MainWindow.Commands.csindex 546f866c..8f01f5e3 100644--- a/src/managed/Nota.App/MainWindow.Commands.cs+++ b/src/managed/Nota.App/MainWindow.Commands.cs@@ -125,6 +125,7 @@ public partial class MainWindowB("roll.quantize", () => { if (_editorRoll is { } roll) { roll.Quantize(1.0); if (_vm is not null) _vm.StatusText = "Quantized notes"; } }, Roll);B("roll.octaveUp", () => _editorRoll?.TransposeBy(12), Roll);B("roll.octaveDown", () => _editorRoll?.TransposeBy(-12), Roll);+ B("roll.fitNotes", () => _editorRoll?.FitToNotes(), Roll);B("roll.removeOutOfScale", () => _editorRoll?.RemoveOutOfScaleNotes(),c => Need(c.HasOpenMidiClip && _editorRoll?.HasOutOfScaleNotes == true, "No notes outside the scale"));diff --git a/src/managed/Nota.App/PianoRollView.cs b/src/managed/Nota.App/PianoRollView.csindex a7aaae55..f3b6a115 100644--- a/src/managed/Nota.App/PianoRollView.cs+++ b/src/managed/Nota.App/PianoRollView.cs@@ -8,6 +8,8 @@// share one time axis. Notes render in the track colour with opacity encoding// velocity; the selected note fills accent-bright. The control owns the note// list; every edit invokes Commit so the window pushes the set to the engine.+// Rows zoom vertically (⌘⌥+wheel, drag on the keys, ⌥+pinch, ⇧F = Fit to notes);+// the row height is per-clip view state like the horizontal zoom.using System;using System.Collections.Generic;@@ -68,19 +70,26 @@ public sealed partial class PianoRollView : UserControlprivate DispatcherTimer? _heldTimer;// --- per-clip view persistence (scroll/zoom don't reset when you re-enter a clip) ------- private readonly record struct ViewState(double Ppb, double Scroll, double VOffset, bool HasV);+ private readonly record struct ViewState(double Ppb, double Scroll, double VOffset, bool HasV, double RowH);private static readonly Dictionary<(int, int), ViewState> s_view = new();private (int, int) _clipKey = (int.MinValue, int.MinValue);private double? _pendingVOffset; // absolute vertical offset to apply once the body is laid outprivate bool _pendingCenter; // instead: centre on the clip's notes once laid outprivate bool _restoringView; // suppress view-saves while we programmatically restore+ private bool _saveAfterApply; // a zoom/fit queued the offset: save it once applied/// <summary>Identifies the edited clip so its scroll/zoom/vertical position persist across/// re-opens. Call before <see cref="SetNotes"/>.</summary>public void SetClipIdentity(int a, int b) => _clipKey = (a, b);private const int MinPitch = 21, MaxPitch = 108; // A0..C8 (88 keys)- private const double KeysW = 48, RowH = 12, RulerH = 24, VelH = 72;+ private const double KeysW = 48, RulerH = 24, VelH = 72;++ // Vertical zoom (specs/019-piano-roll-vertical-zoom): the row height is per-clip view+ // state, driven by ⌘⌥+wheel, a drag on the keys, ⌥+pinch and Fit to notes.+ private const double MinRowH = 6, DefaultRowH = 12, MaxRowH = 36;+ private double _rowH = DefaultRowH;+ internal double RowH => _rowH;private readonly List<NotaNote> _notes = new();private double _lengthBeats = 4;@@ -252,7 +261,7 @@ public sealed partial class PianoRollView : UserControlprivate static readonly IBrush PressureShade = NotaPalette.Wash(NotaPalette.SurfaceAbyss, 0x66);private static readonly Typeface Mono = NotaFonts.Mono;- private static double RangeH => (MaxPitch - MinPitch + 1) * RowH;+ private double RangeH => (MaxPitch - MinPitch + 1) * RowH;public PianoRollView(){@@ -266,13 +275,15 @@ public sealed partial class PianoRollView : UserControl_velHost = new Border { BorderBrush = Divider, BorderThickness = new Thickness(0, 1, 0, 0), Child = _vel };// Body: keys pinned left, grid fills; both scroll vertically together.- var body = new Grid { ColumnDefinitions = new ColumnDefinitions($"{KeysW},*") };+ // Top-aligned: zoomed out past the viewport, the 88 rows stay pinned to the top.+ var body = new Grid { ColumnDefinitions = new ColumnDefinitions($"{KeysW},*"), VerticalAlignment = VerticalAlignment.Top };body.Children.Add(_keys);Avalonia.Controls.Grid.SetColumn(_gridControl, 1);body.Children.Add(_gridControl);_bodyScroll = new ScrollViewer{Content = body,+ Background = Bg, // the well below the rows when they don't fill the viewportHorizontalScrollBarVisibility = ScrollBarVisibility.Disabled,VerticalScrollBarVisibility = ScrollBarVisibility.Auto,};@@ -354,19 +365,72 @@ public sealed partial class PianoRollView : UserControlprivate void SaveView(){if (_clipKey.Item1 == int.MinValue || _pixelsPerBeat <= 0) return;- s_view[_clipKey] = new ViewState(_pixelsPerBeat, _scrollBeats, _bodyScroll.Offset.Y, true);+ s_view[_clipKey] = new ViewState(_pixelsPerBeat, _scrollBeats, _bodyScroll.Offset.Y, true, _rowH);}private void ApplyPendingVOffset(){if (_pendingVOffset is null && !_pendingCenter) return;if (_bodyScroll.Viewport.Height <= 0) return; // not laid out yet; LayoutUpdated retries+ // After a vertical zoom-in the extent only grows on the next layout pass; an offset+ // set before that would be clamped to the old, shorter range.+ if (_bodyScroll.Extent.Height < RangeH - 0.5) return;double vy = _pendingCenter ? CenterOffsetForNotes() : _pendingVOffset!.Value;_pendingVOffset = null; _pendingCenter = false;- double maxY = Math.Max(0, _bodyScroll.Extent.Height - _bodyScroll.Viewport.Height);+ double maxY = Math.Max(0, RangeH - _bodyScroll.Viewport.Height);_restoringView = true;_bodyScroll.Offset = new Vector(_bodyScroll.Offset.X, Math.Clamp(vy, 0, maxY));_restoringView = false;+ if (_saveAfterApply) { _saveAfterApply = false; SaveView(); }+ }++ /// <summary>Sets the row height, keeping the pitch at <paramref name="viewportY"/> (in+ /// the body viewport) where it is. Clamped to 6–36 px; ignored mid note-gesture so a+ /// drag never lands on a pitch the user didn't point at. View state only — no undo.</summary>+ internal void SetRowHeightAt(double h, double viewportY)+ {+ if (_gridControl.Dragging) return;+ double h0 = _rowH, h1 = Math.Clamp(h, MinRowH, MaxRowH);+ if (Math.Abs(h1 - h0) < 1e-9) return;+ double c = (_pendingVOffset ?? _bodyScroll.Offset.Y) + viewportY;+ _rowH = h1;+ _keys.Height = RangeH;+ _gridControl.Height = RangeH;+ _pendingCenter = false;+ _pendingVOffset = c * h1 / h0 - viewportY;+ _saveAfterApply = true;+ ApplyPendingVOffset(); // now if the extent already fits; LayoutUpdated otherwise+ Invalidate();+ SaveView();+ }++ internal void ZoomRowsAt(double factor, double viewportY) => SetRowHeightAt(_rowH * factor, viewportY);++ /// <summary>⌘⌥ (Ctrl+Alt) + wheel: the vertical-zoom wheel, checked before ⌘ + wheel.</summary>+ private static bool IsRowZoomWheel(KeyModifiers m)+ => (m & (KeyModifiers.Control | KeyModifiers.Meta)) != 0 && (m & KeyModifiers.Alt) != 0;++ /// <summary>Fit to notes (⇧F): every note of the clip in view, one row of margin above+ /// and below, centred; an empty clip goes back to the default height around C5.</summary>+ public void FitToNotes()+ {+ if (_gridControl.Dragging) return;+ double vh = _bodyScroll.Viewport.Height;+ double h = DefaultRowH;+ if (_notes.Count > 0 && vh > 0)+ {+ int minP = int.MaxValue, maxP = int.MinValue;+ foreach (var n in _notes) { if (n.Pitch < minP) minP = n.Pitch; if (n.Pitch > maxP) maxP = n.Pitch; }+ h = vh / (maxP - minP + 1 + 2);+ }+ _rowH = Math.Clamp(h, MinRowH, MaxRowH);+ _keys.Height = RangeH;+ _gridControl.Height = RangeH;+ _pendingVOffset = null; _pendingCenter = true;+ _saveAfterApply = true;+ ApplyPendingVOffset();+ Invalidate();+ SaveView();}public double LengthBeats => _lengthBeats;@@ -413,12 +477,16 @@ public sealed partial class PianoRollView : UserControl_notes.AddRange(notes);_lengthBeats = Math.Max(1, lengthBeats);_selection.Clear();- _keys.Height = RangeH;- _gridControl.Height = RangeH;+ _saveAfterApply = false; // a zoom queued on the previous clip must not save onto this one// Restore this clip's saved scroll/zoom if we've edited it before; otherwise fit the- // length horizontally and centre vertically on the clip's own notes.- if (s_view.TryGetValue(_clipKey, out var vs) && vs.HasV)+ // length horizontally and centre vertically on the clip's own notes at the default+ // row height. Row heights are per clip: zooming one never changes another.+ bool saved = s_view.TryGetValue(_clipKey, out var vs) && vs.HasV;+ _rowH = saved ? Math.Clamp(vs.RowH, MinRowH, MaxRowH) : DefaultRowH;+ _keys.Height = RangeH;+ _gridControl.Height = RangeH;+ if (saved){_pixelsPerBeat = Math.Clamp(vs.Ppb, MinPpb, MaxPpb);_scrollBeats = Math.Max(0, vs.Scroll);@@ -996,9 +1064,60 @@ public sealed partial class PianoRollView : UserControlprivate readonly PianoRollView _o;private int _hover = -1;public KeysColumn(PianoRollView o) { _o = o; }+ private double RowH => _o.RowH;++ // Drag zoom: press a key and drag vertically — down taller, up shorter — with the+ // pressed key held at the press height. Nothing is played or created.+ private static readonly Cursor ZoomCursor = new(StandardCursorType.SizeNorthSouth);+ private bool _zooming;+ private double _pressY, _pressRowH;++ protected override void OnPointerPressed(PointerPressedEventArgs e)+ {+ if (!e.GetCurrentPoint(this).Properties.IsLeftButtonPressed || _o._gridControl.Dragging) return;+ _zooming = true;+ _pressY = e.GetPosition(_o._bodyScroll).Y;+ _pressRowH = RowH;+ Cursor = ZoomCursor;+ e.Pointer.Capture(this);+ e.Handled = true;+ }++ protected override void OnPointerReleased(PointerReleasedEventArgs e)+ {+ if (!_zooming) return;+ e.Pointer.Capture(null);+ EndZoom();+ e.Handled = true;+ }++ protected override void OnPointerCaptureLost(PointerCaptureLostEventArgs e) => EndZoom();++ private void EndZoom()+ {+ if (!_zooming) return;+ _zooming = false;+ Cursor = null;+ }++ // ⌘⌥+wheel zooms rows here too; any other wheel is left to the body ScrollViewer.+ protected override void OnPointerWheelChanged(PointerWheelEventArgs e)+ {+ if (IsRowZoomWheel(e.KeyModifiers))+ {+ _o.ZoomRowsAt(WheelInput.ZoomFactor(e.Delta.Y, 1.2), e.GetPosition(_o._bodyScroll).Y);+ e.Handled = true;+ }+ }protected override void OnPointerMoved(PointerEventArgs e){+ if (_zooming)+ {+ double dy = e.GetPosition(_o._bodyScroll).Y - _pressY;+ _o.SetRowHeightAt(_pressRowH * Math.Exp(dy * 0.01), _pressY);+ return;+ }int p = (int)Math.Clamp(MaxPitch - Math.Floor(e.GetPosition(this).Y / RowH), MinPitch, MaxPitch);if (p != _hover) { _hover = p; InvalidateVisual(); }}@@ -1042,7 +1161,7 @@ public sealed partial class PianoRollView : UserControl}}- private static void DrawKeyLabel(DrawingContext ctx, int pitch, double y, double w, IBrush ink)+ private void DrawKeyLabel(DrawingContext ctx, int pitch, double y, double w, IBrush ink){var ft = new FormattedText(NoteName(pitch), CultureInfo.InvariantCulture, FlowDirection.LeftToRight, Mono, 8, ink);ctx.DrawText(ft, new Point(w - ft.Width - 5, y + (RowH - ft.Height) / 2));@@ -1055,6 +1174,8 @@ public sealed partial class PianoRollView : UserControlprivate readonly PianoRollView _o;private enum Mode { None, Move, Resize, ResizeLeft, Marquee }private Mode _drag = Mode.None;+ /// <summary>A note move / resize / box selection is in progress.</summary>+ internal bool Dragging => _drag != Mode.None;private bool _dragMoved;// Move/resize: each selected note's state at grab time + the primary grabbed.@@ -1096,12 +1217,20 @@ public sealed partial class PianoRollView : UserControlFocusable = true;// Leaving the grid (another panel, another clip, a dialog) lets the placement go.LostFocus += (_, _) => _o.SettlePlacement();+ // ⌥+pinch on a trackpad zooms rows (raised by the macOS backend; elsewhere never).+ AddHandler(PointerTouchPadGestureMagnifyEvent, (_, e) =>+ {+ if ((e.KeyModifiers & KeyModifiers.Alt) == 0) return;+ _o.ZoomRowsAt(1 + e.Delta.X, e.GetPosition(_o._bodyScroll).Y);+ e.Handled = true;+ });}private double Ppb => _o.PixelsPerBeat;private double BeatToX(double b) => _o.BeatToX(b);private double XToBeat(double x) => _o.XToBeat(x);- private static double PitchToY(int p) => (MaxPitch - p) * RowH;+ private double RowH => _o.RowH;+ private double PitchToY(int p) => (MaxPitch - p) * RowH;private int YToPitch(double y) => (int)Math.Clamp(MaxPitch - Math.Floor(y / RowH), MinPitch, MaxPitch);// Alt held during the gesture positions freely, as in the arrangement (FR-009).private bool _free;@@ -1502,12 +1631,18 @@ public sealed partial class PianoRollView : UserControl_o.Changed?.Invoke();}- // ⌘/Ctrl+wheel zooms toward the cursor; Shift+wheel scrolls horizontally;- // plain wheel is left to the body ScrollViewer for vertical key navigation.+ // ⌘⌥/Ctrl+Alt+wheel zooms rows around the pitch under the cursor; ⌘/Ctrl+wheel zooms+ // time toward the cursor; Shift+wheel scrolls horizontally; plain wheel is left to+ // the body ScrollViewer for vertical key navigation.protected override void OnPointerWheelChanged(PointerWheelEventArgs e){var mods = e.KeyModifiers;- if ((mods & (KeyModifiers.Control | KeyModifiers.Meta)) != 0)+ if (IsRowZoomWheel(mods))+ {+ _o.ZoomRowsAt(WheelInput.ZoomFactor(e.Delta.Y, 1.2), e.GetPosition(_o._bodyScroll).Y);+ e.Handled = true;+ }+ else if ((mods & (KeyModifiers.Control | KeyModifiers.Meta)) != 0){_o.ZoomAt(WheelInput.ZoomFactor(e.Delta.Y, 1.2), XToBeat(e.GetPosition(this).X));e.Handled = true;@@ -1567,6 +1702,9 @@ public sealed partial class PianoRollView : UserControlbool meta = (e.KeyModifiers & (KeyModifiers.Meta | KeyModifiers.Control)) != 0;bool shift = (e.KeyModifiers & KeyModifiers.Shift) != 0;if (!meta && (e.Key == Key.Delete || e.Key == Key.Back)) { if (_o.DeleteSelection()) e.Handled = true; return; }+ // ⇧F: Fit to notes. Handled here, the window's computer-keyboard note map never+ // sees it, so no F sounds.+ if (e.Key == Key.F && e.KeyModifiers == KeyModifiers.Shift) { _o.FitToNotes(); e.Handled = true; return; }if (!meta && e.Key == Key.Escape && _o._selection.Count > 0){_o.SettlePlacement();diff --git a/src/managed/Nota.App/PreferencesWindow.cs b/src/managed/Nota.App/PreferencesWindow.csindex 72c0bbf1..a2ab10dd 100644--- a/src/managed/Nota.App/PreferencesWindow.cs+++ b/src/managed/Nota.App/PreferencesWindow.cs@@ -1169,6 +1169,10 @@ public sealed partial class PreferencesWindow : NotaWindow("Drag velocity stem", "Set velocity · selected notes move together · ⇧ adds a note"),("Drag in the Bend / Pres / Slide lane", "Draw the selected note's MPE curve · ⌥ draws a straight line · drag a point to move it"),("Double-click in an MPE lane", "Add a point · on a point, delete it · right-click to clear the curve"),+ ("⌘⌥ + wheel", "Zoom rows (vertical zoom)"),+ ("Drag on the keys", "Zoom rows · down taller, up shorter"),+ ("⌥ + pinch", "Zoom rows (trackpad)"),+ ("⇧F", "Fit to notes"),}),("Play notes (computer keyboard)", new[]{diff --git a/src/managed/Nota.Application/Palette/CommandCatalog.cs b/src/managed/Nota.Application/Palette/CommandCatalog.csindex 748f1a94..02b02baa 100644--- a/src/managed/Nota.Application/Palette/CommandCatalog.cs+++ b/src/managed/Nota.Application/Palette/CommandCatalog.cs@@ -92,6 +92,7 @@ public static class CommandCatalogC("roll.octaveUp", "Transpose notes up an octave", "Piano roll", "", "pitch shift"),C("roll.octaveDown", "Transpose notes down an octave", "Piano roll", "", "pitch shift"),C("roll.removeOutOfScale", "Remove out-of-scale notes", "Piano roll", "", "key fix"),+ C("roll.fitNotes", "Fit to notes", "Piano roll", "⇧F", "zoom vertical rows height"),// ---- Grid (the arrangement or the piano roll — whichever was used last) -----------C("grid.narrower", "Narrow grid", "Grid", "⌘1", "finer smaller snap"),