From b4cf85ac44dba24ff136b6d0b261d37b8d3a1eea Mon Sep 17 00:00:00 2001
From: Jage9 <jj@bestmidi.com>
Date: Mon, 23 Feb 2026 00:26:38 -0500
Subject: [PATCH] Add piano octave hotkeys and escape-only exit

---
 client/public/help.json  |  2 +-
 client/public/version.js |  2 +-
 client/src/main.ts       | 19 +++++++++++++++++--
 docs/controls.md         |  3 ++-
 4 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/client/public/help.json b/client/public/help.json
index e8d72c9..3350639 100644
--- a/client/public/help.json
+++ b/client/public/help.json
@@ -87,7 +87,7 @@
         },
         {
           "keys": "Piano mode",
-          "description": "When using a piano: 1-9 (and 0 for the 10th slot) changes instrument, ASDFGHJKL;' plays C major notes, WETYUOP] plays sharps, Enter/Escape exits"
+          "description": "When using a piano: 1-9 (and 0 for the 10th slot) changes instrument, -/= changes octave, ASDFGHJKL;' plays C major notes, WETYUOP] plays sharps, Escape exits"
         }
       ]
     },
diff --git a/client/public/version.js b/client/public/version.js
index a3a5674..9189dac 100644
--- a/client/public/version.js
+++ b/client/public/version.js
@@ -1,5 +1,5 @@
 // Maintainer-controlled web client version.
 // Format: YYYY.MM.DD Rn (example: 2026.02.20 R2)
-window.CHGRID_WEB_VERSION = "2026.02.22 R203";
+window.CHGRID_WEB_VERSION = "2026.02.22 R204";
 // Optional display timezone for timestamps. Falls back to America/Detroit if unset/invalid.
 window.CHGRID_TIME_ZONE = "America/Detroit";
diff --git a/client/src/main.ts b/client/src/main.ts
index 3d6f94c..f3dfdb6 100644
--- a/client/src/main.ts
+++ b/client/src/main.ts
@@ -880,9 +880,10 @@ async function startPianoUseMode(itemId: string): Promise<void> {
   if (!item || item.type !== 'piano') return;
   activePianoItemId = itemId;
   activePianoKeys.clear();
+  activePianoKeyMidi.clear();
   state.mode = 'pianoUse';
   await audio.ensureContext();
-  updateStatus(`Piano mode: ${item.title}. Press Enter or Escape to stop.`);
+  updateStatus(`using ${item.title}, press escape to stop.`);
   audio.sfxUiBlip();
 }
 
@@ -2313,7 +2314,7 @@ function handleMicGainEditModeInput(code: string, key: string, ctrlKey: boolean)
 
 /** Handles realtime keyboard performance while piano item mode is active. */
 function handlePianoUseModeInput(code: string): void {
-  if (code === 'Escape' || code === 'Enter') {
+  if (code === 'Escape') {
     stopPianoUseMode(true);
     return;
   }
@@ -2327,6 +2328,20 @@ function handlePianoUseModeInput(code: string): void {
     stopPianoUseMode(false);
     return;
   }
+  if (code === 'Equal' || code === 'Minus') {
+    const current = getPianoParams(item).octave;
+    const next = Math.max(-2, Math.min(2, current + (code === 'Equal' ? 1 : -1)));
+    item.params.octave = next;
+    signaling.send({ type: 'item_update', itemId, params: { octave: next } });
+    void previewPianoSettingChange(item, {});
+    updateStatus(`octave ${next}.`);
+    if (next === current) {
+      audio.sfxUiCancel();
+    } else {
+      audio.sfxUiBlip();
+    }
+    return;
+  }
   if (code.startsWith('Digit')) {
     const digit = Number(code.slice(5));
     const instrumentIndex = digit === 0 ? 9 : digit - 1;
diff --git a/docs/controls.md b/docs/controls.md
index 4f9c948..ff6dd7c 100644
--- a/docs/controls.md
+++ b/docs/controls.md
@@ -80,7 +80,8 @@ Applies to effect select, user/item list modes, item selection, item property li
 - `A S D F G H J K L ; '`: Play white keys (C major from C4 upward)
 - `W E T Y U O P ]`: Play sharps
 - Multiple keys can be held/played at once
-- `Enter` / `Escape`: Exit piano mode
+- `-` / `=`: Shift octave down/up
+- `Escape`: Exit piano mode
 
 ## Help Viewer Mode