Add piano item type with realtime play mode and remote notes

docs/controls.md

@@ -74,6 +74,13 @@ Applies to effect select, user/item list modes, item selection, item property li
 - `Space`: Read tooltip/help for current option (where metadata is available)
 - First-letter navigation: jump to next matching entry
 
+## Piano Use Mode
+
+- `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
+
 ## Help Viewer Mode
 
 - `ArrowUp` / `ArrowDown`: Previous/next help line

docs/item-schema.md

@@ -5,7 +5,7 @@
 ```json
 {
   "id": "string",
-  "type": "radio_station | dice | wheel | clock | widget",
+  "type": "radio_station | dice | wheel | clock | widget | piano",
   "title": "string",
   "x": 0,
   "y": 0,
@@ -24,8 +24,8 @@
 - `useSound`: optional client-played one-shot sound when item `use` succeeds; global item field and not user-editable in V1.
 - `emitSound`: optional continuously-looping spatial sound emitted from the item on the grid; global item field and not user-editable in V1.
 - `capabilities`, `useSound`, and `emitSound` are derived from global item-type definitions at runtime (not stored per-instance in persisted state).
-- `useCooldownMs`: global per item type (`radio_station=1000`, `dice=1000`, `wheel=4000`, `clock=1000`, `widget=1000`), not per-instance editable.
-- `emitRange`: global spatial range default per item type (`radio_station=20`, `dice=15`, `wheel=15`, `clock=10`, `widget=15`).
+- `useCooldownMs`: global per item type (`radio_station=1000`, `dice=1000`, `wheel=4000`, `clock=1000`, `widget=1000`, `piano=1000`), not per-instance editable.
+- `emitRange`: global spatial range default per item type (`radio_station=20`, `dice=15`, `wheel=15`, `clock=10`, `widget=15`, `piano=15`).
   - `radio_station` can override this per instance via `params.emitRange` (`5..20`).
 - `directional`: global directional attenuation flag per item type (`radio_station=true`, others `false`); `widget` can override per instance via `params.directional`.
 
@@ -34,7 +34,7 @@
 ```json
 {
   "id": "string",
-  "type": "radio_station | dice | wheel | clock | widget",
+  "type": "radio_station | dice | wheel | clock | widget | piano",
   "title": "string",
   "x": 0,
   "y": 0,
@@ -158,6 +158,23 @@
 - `useSound`: empty, filename (assumed under `sounds/`), or full URL.
 - `emitSound`: empty, filename (assumed under `sounds/`), or full URL.
 
+### `piano`
+
+```json
+{
+  "instrument": "piano",
+  "attack": 15,
+  "decay": 45,
+  "emitRange": 15
+}
+```
+
+- `instrument`: one of
+  `piano | electric_piano | guitar | organ | bass | violin | synth_lead | drum_kit`.
+- `attack`: integer, range `0-100`, default `15`.
+- `decay`: integer, range `0-100`, default `45`.
+- `emitRange`: integer, range `5-20`, default `15`.
+
 ## Packet Shapes
 
 - `item_upsert`:
@@ -201,3 +218,22 @@
   "y": 8
 }
 ```
+
+- `item_piano_note`:
+
+```json
+{
+  "type": "item_piano_note",
+  "itemId": "item-id",
+  "senderId": "user-id",
+  "keyId": "KeyA",
+  "midi": 60,
+  "on": true,
+  "instrument": "piano",
+  "attack": 15,
+  "decay": 45,
+  "x": 12,
+  "y": 8,
+  "emitRange": 15
+}
+```

docs/item-types.md

@@ -151,6 +151,31 @@ This is behavior-focused documentation for item types and their defaults.
 - `useSound`: empty, filename (assumed under `sounds/`), or full URL
 - `emitSound`: empty, filename (assumed under `sounds/`), or full URL
 
+## `piano`
+
+### Defaults
+- Title: `piano`
+- Params:
+  - `instrument="piano"`
+  - `attack=15`
+  - `decay=45`
+  - `emitRange=15`
+- Global:
+  - `useSound=none`
+  - `emitSound=none`
+  - `useCooldownMs=1000`
+  - `emitRange=15`
+  - `directional=false`
+
+### Use
+- 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`
+- `attack`: integer `0..100`
+- `decay`: integer `0..100`
+- `emitRange`: integer `5..20`
+
 ## Adding A New Item Type (Registry V1)
 
 Item types are currently code-registered on both server and client. Server item logic is split per item module and wired through one registry.

docs/protocol-notes.md

@@ -15,6 +15,7 @@ This is a behavior guide for packet semantics beyond raw schemas.
 - `chat_message`: player chat.
 - `ping`: latency measurement.
 - `item_add`, `item_pickup`, `item_drop`, `item_delete`, `item_use`, `item_update`: item actions.
+- `item_piano_note`: realtime piano note on/off for active piano use mode.
 
 ## Server -> Client
 
@@ -28,12 +29,17 @@ This is a behavior guide for packet semantics beyond raw schemas.
 - `item_remove`: item deletion.
 - `item_action_result`: action success/failure and user-facing message.
 - `item_use_sound`: spatial one-shot sound on successful item use (if `useSound` configured).
+- `item_piano_note`: broadcast piano note on/off with resolved instrument/envelope/spatial params.
 
 ## Item Packet Behavior
 
 - `item_upsert` is full-state replacement for one item, not partial patch.
 - `item_action_result` messages are intended for direct screen-reader/user status feedback.
 - `item_use_sound` contains absolute item world coordinates (`x`, `y`) and sound path.
+- `item_piano_note` contains:
+  - `itemId`, `senderId`, `keyId`, `midi`, `on`
+  - resolved `instrument`, `attack`, `decay`, `emitRange`
+  - absolute source coordinates `x`, `y`
 
 ## Welcome Metadata
 

docs/runtime-flow.md

@@ -41,6 +41,7 @@ Core incoming message effects:
 - `item_remove`: remove item and cleanup runtimes.
 - `item_action_result`: success/error status for actions.
 - `item_use_sound`: play one-shot spatial sample (world layer gated).
+- `item_piano_note`: start/stop synthesized piano notes from remote users (item layer gated).
 - `pong`:
   - positive `clientSentAt`: user ping response (`P` command)
   - negative `clientSentAt`: internal heartbeat response