From 3329166262119b930133adb17976a2459bf15bea Mon Sep 17 00:00:00 2001
From: Patricio Rivera Alfaro <patricio.rivera@continuumhq.com>
Date: Sun, 12 Jul 2026 23:24:13 -0400
Subject: [PATCH] fix: play the selected cell's expected pitch from the piano
 keyboard and note picker

PianoKeyboard and NotePicker each owned useAudio and called playNote directly
with a bare pitch class, which always defaults to octave 4. Extracted the
octave-computation math from MatrixGrid's noteForColumnPlayback into a shared
computePlaybackNote helper, had both input components emit note-click instead
of playing sound themselves, and had PlayingView compute the correct
octave-qualified note for the active cell before playing it.

Fixes #122
---
 src/components/MatrixGrid.vue                 |  16 +--
 src/components/NotePicker.vue                 |  13 +-
 src/components/PianoKeyboard.vue              |   9 +-
 src/components/PlayingView.vue                |  22 ++-
 src/components/__tests__/NotePicker.spec.ts   |  32 +++++
 .../__tests__/PianoKeyboard.spec.ts           |  26 ++++
 src/components/__tests__/PlayingView.spec.ts  |  52 +++++++
 src/music/__tests__/matrix.spec.ts            | 134 +++++++++++++++++-
 src/music/matrix.ts                           |  24 ++++
 9 files changed, 299 insertions(+), 29 deletions(-)

diff --git a/src/components/MatrixGrid.vue b/src/components/MatrixGrid.vue
index 2f8269d..b494875 100644
--- a/src/components/MatrixGrid.vue
+++ b/src/components/MatrixGrid.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { computed } from 'vue'
+import { computePlaybackNote } from '@/music/matrix'
 import type { MatrixCell } from '@/music/matrix'
 import type { AnswerResult } from '@/music/scoring'
 import { useAudio } from '@/composables/useAudio'
-import { Note } from '@/music/tonal'
 
 const { playNote } = useAudio()
 
@@ -56,19 +56,7 @@ function isActive(cell: MatrixCell): boolean {
 }
 
 function noteForColumnPlayback(cell: MatrixCell): string {
-  if (!cell.note || !props.intervalSemitones) return cell.note
-  const givenRow = cell.col // diagonal: given is always at row === col
-  const givenCell = props.cells[givenRow]?.[cell.col]
-  if (!givenCell?.note) return cell.note
-  const givenMidi = Note.midi(`${givenCell.note}4`) ?? 60
-  const semDiff = (props.intervalSemitones[cell.row] ?? 0) - (props.intervalSemitones[givenRow] ?? 0)
-  const targetMidi = givenMidi + semDiff
-  const { letter, alt } = Note.get(cell.note)
-  // Note.get().chroma wraps mod 12, which is wrong for Cb/Cbb/B#/B## whose alt pushes the
-  // pitch class outside 0-11; rebuild the unbounded value from the natural letter + alt instead.
-  const unboundedChroma = Note.get(letter).chroma + alt
-  const octave = Math.round((targetMidi - unboundedChroma) / 12) - 1
-  return `${cell.note}${octave}`
+  return computePlaybackNote(props.cells, props.intervalSemitones, cell)
 }
 
 function handleClick(cell: MatrixCell) {
diff --git a/src/components/NotePicker.vue b/src/components/NotePicker.vue
index 1ae00b5..1e76c9e 100644
--- a/src/components/NotePicker.vue
+++ b/src/components/NotePicker.vue
@@ -2,9 +2,6 @@
 import { computed } from 'vue'
 import { parseNote } from '@/music/note'
 import type { NoteLetter, Accidental } from '@/music/note'
-import { useAudio } from '@/composables/useAudio'
-
-const { playNote } = useAudio()
 
 const model = defineModel<string | null>()
 
@@ -12,6 +9,10 @@ defineProps<{
   disabled: boolean
 }>()
 
+const emit = defineEmits<{
+  'note-click': [note: string]
+}>()
+
 const LETTERS: NoteLetter[] = ['C', 'D', 'E', 'F', 'G', 'A', 'B']
 const ACCIDENTALS: { value: Accidental; label: string }[] = [
   { value: 'bb', label: 'bb' },
@@ -31,12 +32,12 @@ function selectLetter(letter: NoteLetter) {
     const candidate = letter + activeAccidental.value
     if (parseNote(candidate)) {
       model.value = candidate
-      playNote(candidate)
+      emit('note-click', candidate)
       return
     }
   }
   model.value = letter
-  playNote(letter)
+  emit('note-click', letter)
 }
 
 function selectAccidental(acc: Accidental) {
@@ -44,7 +45,7 @@ function selectAccidental(acc: Accidental) {
   const candidate = activeLetter.value + acc
   if (parseNote(candidate)) {
     model.value = candidate
-    playNote(candidate)
+    emit('note-click', candidate)
   }
 }
 </script>
diff --git a/src/components/PianoKeyboard.vue b/src/components/PianoKeyboard.vue
index 84fc5c2..1f5e7f2 100644
--- a/src/components/PianoKeyboard.vue
+++ b/src/components/PianoKeyboard.vue
@@ -1,9 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { parseNote } from '@/music/note'
-import { useAudio } from '@/composables/useAudio'
-
-const { playNote } = useAudio()
 
 const props = defineProps<{
   activeNote?: string | null
@@ -11,6 +8,10 @@ const props = defineProps<{
   activeOnly?: boolean
 }>()
 
+const emit = defineEmits<{
+  'note-click': [note: string]
+}>()
+
 const activeChroma = computed<number | null>(() => {
   if (!props.activeNote) return null
   return parseNote(props.activeNote)?.chroma ?? null
@@ -32,7 +33,7 @@ function isKeyActive(noteName: string): boolean {
 
 function handleKeyClick(noteName: string): void {
   if (props.activeOnly && !isKeyActive(noteName)) return
-  playNote(noteName)
+  emit('note-click', noteName)
 }
 
 const WHITE_KEY_WIDTH = 36
diff --git a/src/components/PlayingView.vue b/src/components/PlayingView.vue
index a2b9c73..9ee3b70 100644
--- a/src/components/PlayingView.vue
+++ b/src/components/PlayingView.vue
@@ -18,9 +18,10 @@ import NotePicker from '@/components/NotePicker.vue'
 import PianoKeyboard from '@/components/PianoKeyboard.vue'
 import TheoryModal from '@/components/TheoryModal.vue'
 import { useAudio } from '@/composables/useAudio'
+import { computePlaybackNote } from '@/music/matrix'
 import type { MatrixCell } from '@/music/matrix'
 
-const { playJingle } = useAudio()
+const { playNote, playJingle } = useAudio()
 
 const gameStore = useGameStore()
 const progressStore = useProgressStore()
@@ -103,6 +104,17 @@ const puzzleIntervalSemitones = computed<number[]>(() => {
   return entry?.intervals.map((iv) => Interval.semitones(iv) ?? 0) ?? []
 })
 
+function playNoteForActiveCell(note: string): void {
+  if (!activeCell.value || session.value.phase !== 'playing') return
+  const { row, col } = activeCell.value
+  const playbackNote = computePlaybackNote(session.value.puzzle.cells, puzzleIntervalSemitones.value, {
+    row,
+    col,
+    note,
+  })
+  playNote(playbackNote)
+}
+
 const puzzleTitle = computed(() => {
   if (session.value.phase !== 'playing') return ''
   return formatPuzzleTitle(session.value.puzzle.diagonalNote, session.value.puzzle.quality)
@@ -185,9 +197,13 @@ function submit() {
         >Hint</button>
       </div>
 
-      <PianoKeyboard v-if="showPiano" :active-note="activeCellNote" />
+      <PianoKeyboard v-if="showPiano" :active-note="activeCellNote" @note-click="playNoteForActiveCell" />
 
-      <NotePicker v-model="activeCellNote" :disabled="activeCell === null" />
+      <NotePicker
+        v-model="activeCellNote"
+        :disabled="activeCell === null"
+        @note-click="playNoteForActiveCell"
+      />
 
       <button class="submit-btn" @click="submit">Submit</button>
     </main>
diff --git a/src/components/__tests__/NotePicker.spec.ts b/src/components/__tests__/NotePicker.spec.ts
index f46820c..e4d75dc 100644
--- a/src/components/__tests__/NotePicker.spec.ts
+++ b/src/components/__tests__/NotePicker.spec.ts
@@ -140,4 +140,36 @@ describe('NotePicker', () => {
       }
     })
   })
+
+  describe('note-click emit', () => {
+    it('emits note-click alongside update:modelValue when selecting a letter', async () => {
+      const wrapper = mount(NotePicker, {
+        props: { modelValue: null, disabled: false, 'onUpdate:modelValue': () => {} },
+      })
+      await wrapper.findAll('.letters-row .picker-btn')[2]!.trigger('click') // E
+      expect(wrapper.emitted('note-click')).toEqual([['E']])
+    })
+
+    it('emits note-click with the combined note when selecting an accidental', async () => {
+      const wrapper = mount(NotePicker, {
+        props: { modelValue: 'F', disabled: false, 'onUpdate:modelValue': () => {} },
+      })
+      await wrapper.findAll('.accidentals-row .picker-btn')[3]!.trigger('click') // #
+      expect(wrapper.emitted('note-click')).toEqual([['F#']])
+    })
+
+    it('emits both update:modelValue and note-click from the same click', async () => {
+      const updates: (string | null)[] = []
+      const wrapper = mount(NotePicker, {
+        props: {
+          modelValue: null,
+          disabled: false,
+          'onUpdate:modelValue': (v: string | null | undefined) => updates.push(v ?? null),
+        },
+      })
+      await wrapper.findAll('.letters-row .picker-btn')[4]!.trigger('click') // G
+      expect(updates).toEqual(['G'])
+      expect(wrapper.emitted('note-click')).toEqual([['G']])
+    })
+  })
 })
diff --git a/src/components/__tests__/PianoKeyboard.spec.ts b/src/components/__tests__/PianoKeyboard.spec.ts
index e42fcc0..4be267d 100644
--- a/src/components/__tests__/PianoKeyboard.spec.ts
+++ b/src/components/__tests__/PianoKeyboard.spec.ts
@@ -30,4 +30,30 @@ describe('PianoKeyboard', () => {
       expect((key.element as HTMLElement).style.left).toBeTruthy()
     }
   })
+
+  describe('note-click emit', () => {
+    it('emits note-click with the bare pitch class when a white key is clicked', async () => {
+      const wrapper = mount(PianoKeyboard)
+      await wrapper.findAll('.white-key')[2]!.trigger('click') // E
+      expect(wrapper.emitted('note-click')).toEqual([['E']])
+    })
+
+    it('emits note-click with the bare pitch class when a black key is clicked', async () => {
+      const wrapper = mount(PianoKeyboard)
+      await wrapper.findAll('.black-key')[0]!.trigger('click') // C#
+      expect(wrapper.emitted('note-click')).toEqual([['C#']])
+    })
+
+    it('does not emit note-click for an inactive key when activeOnly is set', async () => {
+      const wrapper = mount(PianoKeyboard, { props: { activeOnly: true, activeNote: 'C' } })
+      await wrapper.findAll('.white-key')[2]!.trigger('click') // E, not active
+      expect(wrapper.emitted('note-click')).toBeUndefined()
+    })
+
+    it('emits note-click for the active key when activeOnly is set', async () => {
+      const wrapper = mount(PianoKeyboard, { props: { activeOnly: true, activeNote: 'C' } })
+      await wrapper.findAll('.white-key')[0]!.trigger('click') // C, active
+      expect(wrapper.emitted('note-click')).toEqual([['C']])
+    })
+  })
 })
diff --git a/src/components/__tests__/PlayingView.spec.ts b/src/components/__tests__/PlayingView.spec.ts
index 3f02c27..20922ff 100644
--- a/src/components/__tests__/PlayingView.spec.ts
+++ b/src/components/__tests__/PlayingView.spec.ts
@@ -4,6 +4,11 @@ import { setActivePinia, createPinia } from 'pinia'
 import PlayingView from '@/components/PlayingView.vue'
 import { useGameStore } from '@/stores/game'
 
+const mockPlayNote = vi.fn<(note: string) => void>()
+vi.mock('@/composables/useAudio', () => ({
+  useAudio: () => ({ playNote: mockPlayNote, playJingle: vi.fn<() => void>() }),
+}))
+
 const DEFAULT_OPTIONS = { noDegreeLabels: false, noPianoKeyboard: false }
 
 function startGame(opts = DEFAULT_OPTIONS) {
@@ -111,6 +116,53 @@ describe('PlayingView', () => {
     })
   })
 
+  describe('piano keyboard / note picker playback (issue #122)', () => {
+    beforeEach(() => {
+      mockPlayNote.mockClear()
+    })
+
+    it('does not play a note when no cell is active', async () => {
+      startGame()
+      const wrapper = mountView()
+      await wrapper.findComponent({ name: 'PianoKeyboard' }).vm.$emit('note-click', 'C')
+      expect(mockPlayNote).not.toHaveBeenCalled()
+    })
+
+    it("plays a piano key note in the given cell's own octave when a given cell is active", async () => {
+      useGameStore().startPuzzle('C', 'dom9', DEFAULT_OPTIONS)
+      const wrapper = mountView()
+
+      await wrapper.find('.matrix-cell.given').trigger('click')
+      await wrapper.findComponent({ name: 'PianoKeyboard' }).vm.$emit('note-click', 'G')
+
+      // Given cells always yield a zero semitone offset from themselves, so any
+      // clicked note is placed in the same octave register as the given C4.
+      expect(mockPlayNote).toHaveBeenCalledWith('G3')
+    })
+
+    it('plays the octave-correct note when clicking a piano key with a non-given cell active', async () => {
+      useGameStore().startPuzzle('C', 'dom9', DEFAULT_OPTIONS)
+      const wrapper = mountView()
+
+      // Reversed row order puts row 4 (the 9th-degree row) first in the DOM;
+      // its non-given col-0 cell is the "D" (9th) of the C dom9 chord, 14 semitones above C4.
+      await wrapper.findAll('.matrix-cell')[0]!.trigger('click')
+      await wrapper.findComponent({ name: 'PianoKeyboard' }).vm.$emit('note-click', 'D')
+
+      expect(mockPlayNote).toHaveBeenCalledWith('D5')
+    })
+
+    it('plays the octave-correct note when NotePicker emits note-click', async () => {
+      useGameStore().startPuzzle('C', 'dom9', DEFAULT_OPTIONS)
+      const wrapper = mountView()
+
+      await wrapper.findAll('.matrix-cell')[0]!.trigger('click') // row4/col0, the 9th
+      await wrapper.findComponent({ name: 'NotePicker' }).vm.$emit('note-click', 'D')
+
+      expect(mockPlayNote).toHaveBeenCalledWith('D5')
+    })
+  })
+
   describe('answer submission flow', () => {
     it('stores the answer when NotePicker emits a note', async () => {
       const game = startGame()
diff --git a/src/music/__tests__/matrix.spec.ts b/src/music/__tests__/matrix.spec.ts
index 35e7661..4dcc07c 100644
--- a/src/music/__tests__/matrix.spec.ts
+++ b/src/music/__tests__/matrix.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
-import { generateMatrix, intervalToDegreeLabel } from '@/music/matrix'
-import type { MatrixPuzzle } from '@/music/matrix'
+import { generateMatrix, intervalToDegreeLabel, computePlaybackNote } from '@/music/matrix'
+import type { MatrixPuzzle, MatrixCell } from '@/music/matrix'
 import { parseNote } from '@/music/note'
 
 const col = (puzzle: MatrixPuzzle, c: number) =>
@@ -127,6 +127,136 @@ describe('generateMatrix — degrees', () => {
   })
 })
 
+describe('computePlaybackNote', () => {
+  // F major chord: semitones [0,4,7], diagonal note F
+  const fMajorCells: MatrixCell[][] = [
+    [
+      { note: 'F', isGiven: true, row: 0, col: 0 },
+      { note: 'Db', isGiven: false, row: 0, col: 1 },
+      { note: 'Bb', isGiven: false, row: 0, col: 2 },
+    ],
+    [
+      { note: 'A', isGiven: false, row: 1, col: 0 },
+      { note: 'F', isGiven: true, row: 1, col: 1 },
+      { note: 'D', isGiven: false, row: 1, col: 2 },
+    ],
+    [
+      { note: 'C', isGiven: false, row: 2, col: 0 },
+      { note: 'A', isGiven: false, row: 2, col: 1 },
+      { note: 'F', isGiven: true, row: 2, col: 2 },
+    ],
+  ]
+  const fMajorSemitones = [0, 4, 7]
+
+  it('computes A4 for row1/col0 (A above the given F4)', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 1, col: 0, note: 'A' })).toBe('A4')
+  })
+
+  it('computes C5 for row2/col0 (C above A4)', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 2, col: 0, note: 'C' })).toBe('C5')
+  })
+
+  it('computes Bb3 for row0/col2 (Bb below the given F4)', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 0, col: 2, note: 'Bb' })).toBe('Bb3')
+  })
+
+  it('computes D4 for row1/col2 (D below F4)', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 1, col: 2, note: 'D' })).toBe('D4')
+  })
+
+  it('computes F4 for the given cell itself', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 0, col: 0, note: 'F' })).toBe('F4')
+  })
+
+  it('falls back to the bare note when intervalSemitones is undefined', () => {
+    expect(computePlaybackNote(fMajorCells, undefined, { row: 2, col: 0, note: 'C' })).toBe('C')
+  })
+
+  it('falls back to the bare (empty) note when note is empty', () => {
+    expect(computePlaybackNote(fMajorCells, fMajorSemitones, { row: 0, col: 1, note: '' })).toBe('')
+  })
+
+  it('computes Cb4 for a Cb cell a semitone below given C4', () => {
+    const cells: MatrixCell[][] = [
+      [
+        { note: 'C', isGiven: true, row: 0, col: 0 },
+        { note: '', isGiven: false, row: 0, col: 1 },
+      ],
+      [
+        { note: 'Cb', isGiven: false, row: 1, col: 0 },
+        { note: 'C', isGiven: true, row: 1, col: 1 },
+      ],
+    ]
+    expect(computePlaybackNote(cells, [0, -1], { row: 1, col: 0, note: 'Cb' })).toBe('Cb4')
+  })
+
+  it('computes Cbb4 for a Cbb cell two semitones below given C4', () => {
+    const cells: MatrixCell[][] = [
+      [
+        { note: 'C', isGiven: true, row: 0, col: 0 },
+        { note: '', isGiven: false, row: 0, col: 1 },
+      ],
+      [
+        { note: 'Cbb', isGiven: false, row: 1, col: 0 },
+        { note: 'C', isGiven: true, row: 1, col: 1 },
+      ],
+    ]
+    expect(computePlaybackNote(cells, [0, -2], { row: 1, col: 0, note: 'Cbb' })).toBe('Cbb4')
+  })
+
+  it('computes B#4 for a B# cell a semitone above given B4', () => {
+    const cells: MatrixCell[][] = [
+      [
+        { note: 'B', isGiven: true, row: 0, col: 0 },
+        { note: '', isGiven: false, row: 0, col: 1 },
+      ],
+      [
+        { note: 'B#', isGiven: false, row: 1, col: 0 },
+        { note: 'B', isGiven: true, row: 1, col: 1 },
+      ],
+    ]
+    expect(computePlaybackNote(cells, [0, 1], { row: 1, col: 0, note: 'B#' })).toBe('B#4')
+  })
+
+  it('computes B##4 for a B## cell two semitones above given B4', () => {
+    const cells: MatrixCell[][] = [
+      [
+        { note: 'B', isGiven: true, row: 0, col: 0 },
+        { note: '', isGiven: false, row: 0, col: 1 },
+      ],
+      [
+        { note: 'B##', isGiven: false, row: 1, col: 0 },
+        { note: 'B', isGiven: true, row: 1, col: 1 },
+      ],
+    ]
+    expect(computePlaybackNote(cells, [0, 2], { row: 1, col: 0, note: 'B##' })).toBe('B##4')
+  })
+
+  it('computes the octave for a synthetic note not yet placed in the (still empty) cell', () => {
+    // Simulates auditioning a piano-key/note-picker click for an unanswered cell: the cell's
+    // own note is still '' (no answer submitted), but the helper computes the octave for
+    // whatever note is passed in, independent of what's actually stored at that position.
+    const unansweredCells: MatrixCell[][] = [
+      [
+        { note: 'F', isGiven: true, row: 0, col: 0 },
+        { note: '', isGiven: false, row: 0, col: 1 },
+        { note: '', isGiven: false, row: 0, col: 2 },
+      ],
+      [
+        { note: '', isGiven: false, row: 1, col: 0 },
+        { note: 'F', isGiven: true, row: 1, col: 1 },
+        { note: '', isGiven: false, row: 1, col: 2 },
+      ],
+      [
+        { note: '', isGiven: false, row: 2, col: 0 },
+        { note: '', isGiven: false, row: 2, col: 1 },
+        { note: 'F', isGiven: true, row: 2, col: 2 },
+      ],
+    ]
+    expect(computePlaybackNote(unansweredCells, fMajorSemitones, { row: 1, col: 0, note: 'A' })).toBe('A4')
+  })
+})
+
 describe('generateMatrix — additional qualities', () => {
   it('minor triad with C on diagonal', () => {
     const puzzle = generateMatrix('C', 'minor')!
diff --git a/src/music/matrix.ts b/src/music/matrix.ts
index 090486a..b6be2d9 100644
--- a/src/music/matrix.ts
+++ b/src/music/matrix.ts
@@ -63,6 +63,30 @@ export function puzzleSize(quality: ChordQuality | ScaleMode | IntervalGroup): n
   return intervalsFor(quality).length
 }
 
+// Computes the octave-qualified pitch a note should sound at when it occupies a given
+// matrix position, based on its semitone distance from that column's given (diagonal) note.
+// Reused both to replay an existing cell's own note (MatrixGrid) and to audition an
+// arbitrary candidate note as if it were placed in a cell (piano keyboard / note picker).
+export function computePlaybackNote(
+  cells: MatrixCell[][],
+  intervalSemitones: number[] | undefined,
+  cell: Pick<MatrixCell, 'row' | 'col' | 'note'>,
+): string {
+  if (!cell.note || !intervalSemitones) return cell.note
+  const givenRow = cell.col // diagonal: given is always at row === col
+  const givenCell = cells[givenRow]?.[cell.col]
+  if (!givenCell?.note) return cell.note
+  const givenMidi = Note.midi(`${givenCell.note}4`) ?? 60
+  const semDiff = (intervalSemitones[cell.row] ?? 0) - (intervalSemitones[givenRow] ?? 0)
+  const targetMidi = givenMidi + semDiff
+  const { letter, alt } = Note.get(cell.note)
+  // Note.get().chroma wraps mod 12, which is wrong for Cb/Cbb/B#/B## whose alt pushes the
+  // pitch class outside 0-11; rebuild the unbounded value from the natural letter + alt instead.
+  const unboundedChroma = Note.get(letter).chroma + alt
+  const octave = Math.round((targetMidi - unboundedChroma) / 12) - 1
+  return `${cell.note}${octave}`
+}
+
 export function generateMatrix(
   diagonalNote: string,
   quality: ChordQuality | ScaleMode | IntervalGroup,