added transformation item

doc/development.md

@@ -73,7 +73,7 @@ That gives items on almost every piece and a near-instant start, which is useful
 
 **Server**
 
-- File-scoped namespaces, nullable reference types enabled, one main type per file. Small closely related types may share a file, e.g. all five items in `Items.cs`.
+- File-scoped namespaces, nullable reference types enabled, one main type per file. Small closely related types may share a file, e.g. all items in `Items.cs`.
 - `ActionBlocks.Game` must stay free of ASP.NET or serialization dependencies. Mapping to the wire format happens in `ActionBlocks.Server/Dtos`.
 - Game objects are not thread-safe. Only touch them inside `lock (lobby.Sync)`.
 - Prefer adding a value to `GameSettings`, or an implementation of an existing interface, over hard-coding numbers in logic.

doc/extending.md

@@ -38,7 +38,7 @@ public sealed class SpeedUpItem : IItem
 
 ### 2. Server: add any new state the item needs
 
-If existing `PlayerGame` methods (`InsertGarbageNow`, `RemoveBottomLine`, `ClearBoard`, `SwapBoards`, `InvisibleUntil`) aren't enough, add a property or method to `PlayerGame`. For the example:
+If existing `PlayerGame` methods (`InsertGarbageNow`, `RemoveBottomLine`, `ClearBoard`, `SwapBoards`, `InvisibleUntil`, `Transform`) aren't enough, add a property or method to `PlayerGame`. For the example:
 
 ```csharp
 public double FastUntil { get; set; }
@@ -62,7 +62,7 @@ public static ItemRegistry Default { get; } = new(
 
 ### 4. Server: test it
 
-Add a test to `tests/ActionBlocks.Game.Tests/ItemAndMatchTests.cs`, and update `Registry_contains_five_unique_items` to the new count.
+Add a test to `tests/ActionBlocks.Game.Tests/ItemAndMatchTests.cs`, and update `Registry_contains_six_unique_items` to the new count.
 
 ### 5. Website: add the visuals
 
@@ -81,7 +81,7 @@ The id key must match `IItem.Id`. Unknown ids still work but show `unknown.svg`.
 
 ### 6. Website: show the effect (only if needed)
 
-If the item needs a visual effect, as Blackout does, expose the state in the snapshot (see [below](#add-new-state-to-the-snapshot)) and use it in `GamePage` / `draw.ts`.
+If the item needs a visual effect, as Blackout does, expose the state in the snapshot (see [below](#add-new-state-to-the-snapshot)) and use it in `GamePage` / `draw.ts`. For a timed effect, add an entry to the `effects` list of `EffectTimers` in `GamePage` and `MiniBoard` to show a countdown.
 
 ---
 
@@ -161,7 +161,7 @@ Keep snapshots small. They are sent ~30 times per second for every player to eve
 |---|---|
 | Item icon | Replace the file in `public/assets/items/`, or point `itemVisuals[id].icon` elsewhere |
 | Logo | Put an image in `public/assets/`, set `uiAssets.logo: asset('assets/logo.png')` |
-| Block colors | `src/theme/colors.ts` (`blockColors[1..7]` pieces, `[8]` garbage) |
+| Block colors | `src/theme/colors.ts` (`blockColors[1..7]` pieces, `[8]` garbage, `[9..13]` Transformation shapes) |
 | Block style (bevel, texture, …) | `drawBlock` in `src/render/draw.ts` |
 | Ghost look | `drawGhostCell` in `draw.ts`, `boardColors.ghostAlpha` |
 | UI colors, borders, font | CSS variables in `src/theme/global.css` |

doc/frontend.md

@@ -93,7 +93,7 @@ Layout: **hold + stats + "1 YOU"**, then the **own board** with the garbage mete
   - If the target dies, an effect resets it to yourself, which mirrors the server rule. The selected board gets a cyan frame, and its slot number is filled cyan.
 - **Leave.** The Leave button in the corner calls `leaveLobby`. While you are still alive in a match, leaving gives up that match, so the first click only turns the button into a red `SURE?` for 3 s and a second click leaves. After you are out, or once the match has finished, one click is enough. No browser dialog is used, because dialogs block the page.
 - **Overlays on the own board:** `ItemFlashOverlay` (flashes whose `targetId` is you), the countdown number, and "YOU WIN!" or "<name> WINS".
-- **Blackout.** `hideStack={me.invisibleRemaining > 0}` makes `drawBoard` skip locked cells, item icons and the ghost.
+- **Blackout.** `hideStack={me.invisibleRemaining > 0}` makes `drawBoard` skip locked cells, item icons and the ghost. `EffectTimers` shows the seconds left on Blackout and Transformation in the board corner.
 - **Garbage meter.** A red bar whose height is `pendingGarbage × cell`.
 - **Inventory bar.** 10 slots, with the oldest item outlined, plus the hint line `F: <next item> > <target>`.
 - **Mini boards.** `MiniBoard` is memoized. It shows the slot number, the name, the board, a flash overlay and the opponent's **item bar beneath the board**.

doc/game-rules.md

@@ -28,7 +28,7 @@ Pieces spawn in the two buffer rows directly above the visible field. They are h
 ## Pieces and randomizer
 
 - There are 7 shapes. Each has 4 rotation states (0 = spawn, 1 = right, 2 = 180°, 3 = left). States are derived by rotating the spawn shape inside its bounding box (`Core/PieceDefinitions.cs`).
-- The **bag randomizer** shuffles all 7 shapes into a bag and deals them one by one, then refills (`Core/Randomizer.cs`). This guarantees every shape appears exactly once in every 7 pieces.
+- The **bag randomizer** shuffles all 7 shapes into a bag and deals them one by one, then refills (`Core/Randomizer.cs`). This guarantees every shape appears exactly once in every 7 pieces. The odd Transformation shapes are never in the bag.
 
 ## Rotation (SRS)
 
@@ -133,7 +133,7 @@ A player is eliminated when any of these happens:
 - Everyone sees every opponent's inventory in the item bar beneath their mini board.
 - Every client is told when an item hits someone (`ItemUsedEvent`): which player was hit and which item, but not who used it. The item name flashes on top of the hit player's board. That is the big board for yourself, or the mini board for an opponent.
 
-### The five items
+### The six items
 
 | Id | Name | Effect | Class |
 |---|---|---|---|
@@ -142,6 +142,7 @@ A player is eliminated when any of these happens:
 | `nuke` | Wipe Out | Removes **all** locked blocks of the target. The active piece is unaffected. | `ClearBoardItem` |
 | `swap` | Switch | The user and the target exchange all locked blocks. Active pieces, hold, queues, inventories and pending garbage stay with their owners. If an active piece now overlaps, it is pushed up. Does nothing when used on yourself. | `SwapBoardItem` |
 | `blind` | Blackout | For 4 seconds, the target cannot see their locked blocks or their ghost piece. Only the falling piece stays visible. Durations stack: each further Blackout adds 4 s to the time that is left. | `InvisibilityItem` |
+| `transform` | Transformation | For 8 seconds, the target's upcoming pieces become odd shapes: Dot, small L, U, Plus or W (random). The whole next queue changes at once; the falling piece does not. Items inside a piece move to the new shape. When the time runs out, pieces still in the queue or hold change back to what they were. Durations stack like Blackout. | `TransformationItem` |
 
 Every item can also be used on yourself: target `1`. *Wipe Out* and *Clear Line* are useful defensively.
 

doc/protocol.md

@@ -143,11 +143,12 @@ sequenceDiagram
   "lines": 12,
   "level": 2,
   "pendingGarbage": 3,             // incoming lines waiting to rise
-  "invisibleRemaining": 0          // seconds of Blackout left (> 0 = hide stack + ghost)
+  "invisibleRemaining": 0,         // seconds of Blackout left (> 0 = hide stack + ghost)
+  "transformedRemaining": 0        // seconds of Transformation left (queue shows odd shapes)
 }
 ```
 
-**Board encoding.** One character per cell: `'0'` is empty, `'1'`–`'7'` are piece colors (I, J, L, O, S, Z, T), `'8'` is garbage. Index = `y * width + x`, where y = 0 is the **top visible row**.
+**Board encoding.** One character per cell: `'0'` is empty, `'1'`–`'7'` are piece colors (I, J, L, O, S, Z, T), `'8'` is garbage, and `'9'`, `':'`, `';'`, `'<'`, `'='` (values 9–13) are the Transformation shapes (Dot, SmallL, U, Plus, W). Decode with `charCode - 48`. Index = `y * width + x`, where y = 0 is the **top visible row**.
 
 **Coordinates.** All `x, y` values are in visible coordinates. Active-piece cells can have **negative y** while the piece is still above the visible area. Clients skip those cells when drawing.