Improve piano instruments, previews, and key-stream safeguards

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 R199";
+window.CHGRID_WEB_VERSION = "2026.02.22 R200";
 // Optional display timezone for timestamps. Falls back to America/Detroit if unset/invalid.
 window.CHGRID_TIME_ZONE = "America/Detroit";

client/src/audio/pianoSynth.ts

@@ -8,6 +8,7 @@ export const PIANO_INSTRUMENT_OPTIONS = [
   'bass',
   'violin',
   'synth_lead',
+  'nintendo',
   'drum_kit',
 ] as const;
 
@@ -103,6 +104,27 @@ const PRESETS: Record<Exclude<PianoInstrumentId, 'drum_kit'>, InstrumentPreset>
     gain: 0.2,
     releaseScale: 1,
   },
+  nintendo: {
+    oscillators: [
+      { type: 'square', gain: 1 },
+      { type: 'square', detune: 8, gain: 0.16 },
+    ],
+    filter: { type: 'lowpass', frequency: 5200, q: 1.2 },
+    gain: 0.22,
+    releaseScale: 0.65,
+  },
+};
+
+export const DEFAULT_ENVELOPE_BY_INSTRUMENT: Record<PianoInstrumentId, { attack: number; decay: number }> = {
+  piano: { attack: 15, decay: 45 },
+  electric_piano: { attack: 12, decay: 40 },
+  guitar: { attack: 8, decay: 35 },
+  organ: { attack: 25, decay: 70 },
+  bass: { attack: 10, decay: 35 },
+  violin: { attack: 22, decay: 75 },
+  synth_lead: { attack: 6, decay: 30 },
+  nintendo: { attack: 2, decay: 28 },
+  drum_kit: { attack: 1, decay: 22 },
 };
 
 /** Maps 0..100 control values to note attack seconds. */

client/src/items/itemPropertyEditor.ts

@@ -39,6 +39,7 @@ type EditorDeps = {
   applyTextInputEdit: (code: string, key: string, maxLength: number, ctrlKey?: boolean, allowReplaceOnNextType?: boolean) => void;
   setReplaceTextOnNextType: (value: boolean) => void;
   suppressItemPropertyEchoMs: (ms: number) => void;
+  onPreviewPropertyChange?: (item: WorldItem, key: string, value: unknown) => void;
   updateStatus: (message: string) => void;
   sfxUiBlip: () => void;
   sfxUiCancel: () => void;
@@ -105,6 +106,7 @@ export function createItemPropertyEditor(deps: EditorDeps): {
         const nextValue = options[nextIndex];
         deps.suppressItemPropertyEchoMs(600);
         deps.signalingSend({ type: 'item_update', itemId, params: { [selectedKey]: nextValue } });
+        deps.onPreviewPropertyChange?.(item, selectedKey, nextValue);
         deps.updateStatus(nextValue);
         deps.sfxUiBlip();
         return;
@@ -118,6 +120,7 @@ export function createItemPropertyEditor(deps: EditorDeps): {
         const nextValue = !current;
         deps.suppressItemPropertyEchoMs(600);
         deps.signalingSend({ type: 'item_update', itemId, params: { [selectedKey]: nextValue } });
+        deps.onPreviewPropertyChange?.(item, selectedKey, nextValue);
         deps.updateStatus(nextValue ? 'on' : 'off');
         deps.sfxUiBlip();
         return;
@@ -141,6 +144,7 @@ export function createItemPropertyEditor(deps: EditorDeps): {
         if (Number.isFinite(max)) nextValue = Math.min(max, nextValue);
         deps.suppressItemPropertyEchoMs(600);
         deps.signalingSend({ type: 'item_update', itemId, params: { [selectedKey]: nextValue } });
+        deps.onPreviewPropertyChange?.(item, selectedKey, nextValue);
         deps.updateStatus(formatSteppedNumber(nextValue, step));
         if (Math.abs(nextValue - currentValue) < 1e-9 || Math.abs(nextValue - attempted) > 1e-9) {
           deps.sfxUiCancel();
@@ -254,6 +258,7 @@ export function createItemPropertyEditor(deps: EditorDeps): {
         deps.state.nicknameInput = formatSteppedNumber(nextValue, step);
         deps.state.cursorPos = deps.state.nicknameInput.length;
         deps.setReplaceTextOnNextType(false);
+        deps.onPreviewPropertyChange?.(item, propertyKey, nextValue);
         deps.updateStatus(deps.state.nicknameInput);
         if (Math.abs(nextValue - currentValue) < 1e-9 || Math.abs(nextValue - attempted) > 1e-9) {
           deps.sfxUiCancel();
@@ -268,6 +273,9 @@ export function createItemPropertyEditor(deps: EditorDeps): {
       const value = deps.state.nicknameInput.trim();
       const sendItemParams = (params: Record<string, unknown>): void => {
         deps.signalingSend({ type: 'item_update', itemId, params });
+        for (const [key, nextValue] of Object.entries(params)) {
+          deps.onPreviewPropertyChange?.(item, key, nextValue);
+        }
       };
       const parseToggleValue = (raw: string, field: string): { ok: true; value: boolean } | { ok: false } => {
         const normalized = raw.toLowerCase();
@@ -397,6 +405,10 @@ export function createItemPropertyEditor(deps: EditorDeps): {
     if (control.type === 'select') {
       const selectedValue = deps.state.itemPropertyOptionValues[deps.state.itemPropertyOptionIndex];
       deps.signalingSend({ type: 'item_update', itemId, params: { [propertyKey]: selectedValue } });
+      const item = deps.state.items.get(itemId);
+      if (item) {
+        deps.onPreviewPropertyChange?.(item, propertyKey, selectedValue);
+      }
       deps.state.mode = 'itemProperties';
       deps.state.editingPropertyKey = null;
       deps.state.itemPropertyOptionValues = [];

client/src/items/itemRegistry.ts

@@ -54,6 +54,7 @@ const DEFAULT_PIANO_INSTRUMENT_OPTIONS = [
   'bass',
   'violin',
   'synth_lead',
+  'nintendo',
   'drum_kit',
 ] as const;
 

client/src/main.ts

@@ -14,7 +14,7 @@ import {
   shouldProxyStreamUrl,
 } from './audio/radioStationRuntime';
 import { ItemEmitRuntime } from './audio/itemEmitRuntime';
-import { PianoSynth, type PianoInstrumentId } from './audio/pianoSynth';
+import { DEFAULT_ENVELOPE_BY_INSTRUMENT, PianoSynth, type PianoInstrumentId } from './audio/pianoSynth';
 import { normalizeDegrees } from './audio/spatial';
 import {
   applyPastedText,
@@ -251,6 +251,7 @@ let activeTeleportLoopToken = 0;
 let activePianoItemId: string | null = null;
 const activePianoKeys = new Set<string>();
 const activeRemotePianoKeys = new Set<string>();
+let pianoPreviewTimeoutId: number | null = null;
 let activeTeleport:
   | {
       startX: number;
@@ -797,6 +798,7 @@ function getPianoParams(item: WorldItem): { instrument: PianoInstrumentId; attac
     rawInstrument === 'bass' ||
     rawInstrument === 'violin' ||
     rawInstrument === 'synth_lead' ||
+    rawInstrument === 'nintendo' ||
     rawInstrument === 'drum_kit'
       ? rawInstrument
       : 'piano';
@@ -820,6 +822,7 @@ function normalizePianoInstrument(value: unknown): PianoInstrumentId {
   if (raw === 'bass') return 'bass';
   if (raw === 'violin') return 'violin';
   if (raw === 'synth_lead') return 'synth_lead';
+  if (raw === 'nintendo') return 'nintendo';
   if (raw === 'drum_kit') return 'drum_kit';
   return 'piano';
 }
@@ -866,6 +869,39 @@ function stopPianoUseMode(announce = true): void {
   }
 }
 
+/** Plays one short C4 preview using the piano item's current/overridden envelope+instrument. */
+async function previewPianoSettingChange(item: WorldItem, overrides: Partial<{ instrument: PianoInstrumentId; attack: number; decay: number }>): Promise<void> {
+  if (item.type !== 'piano') return;
+  await audio.ensureContext();
+  const ctx = audio.context;
+  const destination = audio.getOutputDestinationNode();
+  if (!ctx || !destination) return;
+  const current = getPianoParams(item);
+  const instrument = overrides.instrument ?? current.instrument;
+  const attack = Math.max(0, Math.min(100, Math.round(overrides.attack ?? current.attack)));
+  const decay = Math.max(0, Math.min(100, Math.round(overrides.decay ?? current.decay)));
+  const sourceX = item.carrierId === state.player.id ? state.player.x : item.x;
+  const sourceY = item.carrierId === state.player.id ? state.player.y : item.y;
+  const previewKeyId = '__piano_preview_c4__';
+  pianoSynth.noteOff(previewKeyId);
+  pianoSynth.noteOn(
+    previewKeyId,
+    60,
+    instrument,
+    attack,
+    decay,
+    { audioCtx: ctx, destination },
+    { x: sourceX - state.player.x, y: sourceY - state.player.y, range: current.emitRange },
+  );
+  if (pianoPreviewTimeoutId !== null) {
+    window.clearTimeout(pianoPreviewTimeoutId);
+  }
+  pianoPreviewTimeoutId = window.setTimeout(() => {
+    pianoSynth.noteOff(previewKeyId);
+    pianoPreviewTimeoutId = null;
+  }, 320);
+}
+
 /** Plays one inbound piano note from another user using item spatial position. */
 function playRemotePianoNote(note: {
   itemId: string;
@@ -1612,6 +1648,10 @@ function disconnect(): void {
     activeRemotePianoKeys.delete(key);
     pianoSynth.noteOff(key);
   }
+  if (pianoPreviewTimeoutId !== null) {
+    window.clearTimeout(pianoPreviewTimeoutId);
+    pianoPreviewTimeoutId = null;
+  }
 }
 
 const onAppMessage = createOnMessageHandler({
@@ -2484,6 +2524,26 @@ const itemPropertyEditor = createItemPropertyEditor({
   suppressItemPropertyEchoMs: (ms) => {
     suppressItemPropertyEchoUntilMs = Math.max(suppressItemPropertyEchoUntilMs, Date.now() + Math.max(0, ms));
   },
+  onPreviewPropertyChange: (item, key, value) => {
+    if (item.type !== 'piano') return;
+    if (key === 'instrument') {
+      const instrument = normalizePianoInstrument(value);
+      const defaults = DEFAULT_ENVELOPE_BY_INSTRUMENT[instrument];
+      void previewPianoSettingChange(item, { instrument, attack: defaults.attack, decay: defaults.decay });
+      return;
+    }
+    if (key === 'attack') {
+      const attack = Number(value);
+      if (!Number.isFinite(attack)) return;
+      void previewPianoSettingChange(item, { attack });
+      return;
+    }
+    if (key === 'decay') {
+      const decay = Number(value);
+      if (!Number.isFinite(decay)) return;
+      void previewPianoSettingChange(item, { decay });
+    }
+  },
   updateStatus,
   sfxUiBlip: () => audio.sfxUiBlip(),
   sfxUiCancel: () => audio.sfxUiCancel(),

docs/item-schema.md

@@ -170,7 +170,8 @@
 ```
 
 - `instrument`: one of
-  `piano | electric_piano | guitar | organ | bass | violin | synth_lead | drum_kit`.
+  `piano | electric_piano | guitar | organ | bass | violin | synth_lead | nintendo | drum_kit`.
+- Selecting a new instrument resets `attack`/`decay` to that instrument's defaults.
 - `attack`: integer, range `0-100`, default `15`.
 - `decay`: integer, range `0-100`, default `45`.
 - `emitRange`: integer, range `5-20`, default `15`.

docs/item-types.md

@@ -171,10 +171,11 @@ This is behavior-focused documentation for item types and their defaults.
 - Announces that the user begins playing the piano (client enters piano key mode).
 
 ### Validation
-- `instrument`: `piano | electric_piano | guitar | organ | bass | violin | synth_lead | drum_kit`
+- `instrument`: `piano | electric_piano | guitar | organ | bass | violin | synth_lead | nintendo | drum_kit`
 - `attack`: integer `0..100`
 - `decay`: integer `0..100`
 - `emitRange`: integer `5..20`
+- Instrument changes reset `attack`/`decay` to instrument defaults.
 
 ## Adding A New Item Type (Registry V1)
 

server/app/items/piano.py

@@ -32,9 +32,22 @@ INSTRUMENT_OPTIONS: tuple[str, ...] = (
     "bass",
     "violin",
     "synth_lead",
+    "nintendo",
     "drum_kit",
 )
 
+DEFAULT_ENVELOPE_BY_INSTRUMENT: dict[str, tuple[int, int]] = {
+    "piano": (15, 45),
+    "electric_piano": (12, 40),
+    "guitar": (8, 35),
+    "organ": (25, 70),
+    "bass": (10, 35),
+    "violin": (22, 75),
+    "synth_lead": (6, 30),
+    "nintendo": (2, 28),
+    "drum_kit": (1, 22),
+}
+
 PROPERTY_METADATA: dict[str, dict[str, object]] = {
     "title": {"valueType": "text", "tooltip": "Display name spoken and shown for this item.", "maxLength": 80},
     "instrument": {"valueType": "list", "tooltip": "Instrument voice used when playing this piano."},
@@ -62,6 +75,7 @@ def validate_update(_item: WorldItem, next_params: dict) -> dict:
     instrument = str(next_params.get("instrument", "piano")).strip().lower()
     if instrument not in INSTRUMENT_OPTIONS:
         raise ValueError(f"instrument must be one of: {', '.join(INSTRUMENT_OPTIONS)}.")
+    previous_instrument = str(_item.params.get("instrument", "piano")).strip().lower()
     next_params["instrument"] = instrument
 
     try:
@@ -70,14 +84,17 @@ def validate_update(_item: WorldItem, next_params: dict) -> dict:
         raise ValueError("attack must be an integer between 0 and 100.") from exc
     if not (0 <= attack <= 100):
         raise ValueError("attack must be between 0 and 100.")
-    next_params["attack"] = attack
-
     try:
         decay = int(next_params.get("decay", 45))
     except (TypeError, ValueError) as exc:
         raise ValueError("decay must be an integer between 0 and 100.") from exc
     if not (0 <= decay <= 100):
         raise ValueError("decay must be between 0 and 100.")
+
+    # When instrument changes, reset envelope to instrument-appropriate defaults.
+    if instrument != previous_instrument:
+        attack, decay = DEFAULT_ENVELOPE_BY_INSTRUMENT.get(instrument, (15, 45))
+    next_params["attack"] = attack
     next_params["decay"] = decay
 
     try:

server/app/server.py

@@ -68,6 +68,7 @@ from .models import (
 LOGGER = logging.getLogger("chgrid.server")
 PACKET_LOGGER = logging.getLogger("chgrid.server.packet")
 CLIENT_PACKET_ADAPTER = TypeAdapter(ClientPacket)
+MAX_ACTIVE_PIANO_KEYS_PER_CLIENT = 32
 
 
 class SignalingServer:
@@ -92,6 +93,7 @@ class SignalingServer:
         self.clients: dict[ServerConnection, ClientConnection] = {}
         self.item_service = ItemService(state_file=state_file)
         self.item_last_use_ms: dict[str, int] = {}
+        self.active_piano_keys_by_client: dict[str, set[str]] = {}
         self.grid_size = max(1, grid_size)
         self.instance_id = str(uuid.uuid4())
         self.server_version = self._resolve_server_version()
@@ -260,6 +262,7 @@ class SignalingServer:
         finally:
             if websocket in self.clients:
                 disconnected = self.clients.pop(websocket)
+                self.active_piano_keys_by_client.pop(disconnected.id, None)
                 for item in self.item_service.drop_carried_items_for_disconnect(disconnected):
                     await self._broadcast_item(item)
                 self.item_service.save_state()
@@ -666,6 +669,13 @@ class SignalingServer:
                 return
             if item.carrierId is None and (item.x != client.x or item.y != client.y):
                 return
+            active_keys = self.active_piano_keys_by_client.setdefault(client.id, set())
+            if packet.on:
+                if packet.keyId not in active_keys and len(active_keys) >= MAX_ACTIVE_PIANO_KEYS_PER_CLIENT:
+                    return
+                active_keys.add(packet.keyId)
+            else:
+                active_keys.discard(packet.keyId)
             instrument = str(item.params.get("instrument", "piano")).strip().lower()
             attack = int(item.params.get("attack", 15)) if isinstance(item.params.get("attack", 15), (int, float)) else 15
             decay = int(item.params.get("decay", 45)) if isinstance(item.params.get("decay", 45), (int, float)) else 45

server/tests/test_item_use_cooldown.py

@@ -370,8 +370,6 @@ async def test_piano_update_and_use(monkeypatch: pytest.MonkeyPatch) -> None:
                 "itemId": item.id,
                 "params": {
                     "instrument": "drum_kit",
-                    "attack": 22,
-                    "decay": 67,
                     "emitRange": 12,
                 },
             }
@@ -379,10 +377,19 @@ async def test_piano_update_and_use(monkeypatch: pytest.MonkeyPatch) -> None:
     )
     assert send_payloads[-1].ok is True
     assert item.params.get("instrument") == "drum_kit"
-    assert item.params.get("attack") == 22
+    assert item.params.get("attack") == 1
-    assert item.params.get("decay") == 67
+    assert item.params.get("decay") == 22
     assert item.params.get("emitRange") == 12
 
+    await server._handle_message(
+        client,
+        json.dumps({"type": "item_update", "itemId": item.id, "params": {"instrument": "nintendo"}}),
+    )
+    assert send_payloads[-1].ok is True
+    assert item.params.get("instrument") == "nintendo"
+    assert item.params.get("attack") == 2
+    assert item.params.get("decay") == 28
+
     await server._handle_message(client, json.dumps({"type": "item_use", "itemId": item.id}))
     assert send_payloads[-1].ok is True
     assert "begin playing" in send_payloads[-1].message.lower()
@@ -438,3 +445,38 @@ async def test_piano_note_packet_broadcasts(monkeypatch: pytest.MonkeyPatch) ->
     assert getattr(packet, "attack", -1) == 20
     assert getattr(packet, "decay", -1) == 60
     assert getattr(packet, "emitRange", -1) == 12
+
+
+@pytest.mark.asyncio
+async def test_piano_note_key_cap(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = SignalingServer("127.0.0.1", 8765, None, None)
+    ws_sender = _fake_ws()
+    sender = ClientConnection(websocket=ws_sender, id="u1", nickname="tester", x=5, y=6)
+    server.clients[ws_sender] = sender
+    item = server.item_service.default_item(sender, "piano")
+    server.item_service.add_item(item)
+
+    broadcast_payloads: list[object] = []
+
+    async def fake_send(websocket: ServerConnection, packet: object) -> None:
+        return
+
+    async def fake_broadcast(packet: object, exclude: ServerConnection | None = None) -> None:
+        broadcast_payloads.append(packet)
+
+    monkeypatch.setattr(server, "_send", fake_send)
+    monkeypatch.setattr(server, "_broadcast", fake_broadcast)
+
+    for index in range(32):
+        await server._handle_message(
+            sender,
+            json.dumps({"type": "item_piano_note", "itemId": item.id, "keyId": f"Key{index}", "midi": 60, "on": True}),
+        )
+    assert len(broadcast_payloads) == 32
+
+    # 33rd distinct held key is dropped by cap.
+    await server._handle_message(
+        sender,
+        json.dumps({"type": "item_piano_note", "itemId": item.id, "keyId": "KeyOverflow", "midi": 60, "on": True}),
+    )
+    assert len(broadcast_payloads) == 32