What a mess

docs/EQUIPMENT_VISUAL_ENHANCEMENTS.md

@@ -0,0 +1,175 @@
+# Equipment Visual Enhancements
+
+## Summary
+Enhanced the equipment system with visual improvements and better user feedback.
+
+## Changes Made
+
+### 1. Visual Equipment Grid in Character Sheet ✅
+
+**Location:** `pwa/src/components/Game.tsx` (lines 1211-1336)
+
+Added a dedicated equipment display section that shows all 7 equipment slots in a visual grid layout:
+
+```
+      [Head]
+[Shield] [Torso] [Backpack]
+      [Weapon]
+      [Legs]
+      [Feet]
+```
+
+**Features:**
+- Empty slots show placeholder icons and labels (e.g., 🪖 Head, ⚔️ Weapon)
+- Filled slots show item emoji, name, and durability (e.g., 50/80)
+- Click equipped items to unequip them
+- Color-coded borders (red for equipment vs blue for inventory)
+- Responsive layout with three-column middle row
+
+**Styling:** `pwa/src/components/Game.css` (lines 1321-1412)
+- `.equipment-sidebar` - Container styling
+- `.equipment-grid` - Flex column layout
+- `.equipment-row` - Individual slot rows
+- `.equipment-slot` - Individual slot styling
+- `.equipment-slot.empty` - Empty slot appearance (grayed out)
+- `.equipment-slot.filled` - Filled slot appearance (red border, hover effects)
+
+### 2. Improved Equip Messaging ✅
+
+**Location:** `api/main.py` (lines 1108-1150)
+
+Enhanced the equip endpoint to provide better feedback when replacing equipped items:
+
+**Before:**
+```json
+{
+  "success": true,
+  "message": "Equipped Rusty Knife"
+}
+```
+
+**After (when slot occupied):**
+```json
+{
+  "success": true,
+  "message": "Unequipped Old Knife, equipped Rusty Knife",
+  "unequipped_item": "Old Knife"
+}
+```
+
+**Behavior:**
+- Automatically unequips the old item when equipping to an occupied slot
+- No need for manual unequip first
+- Clear messaging about what was replaced
+- Old item returns to inventory
+
+### 3. Durability Display in Item Info ✅
+
+**Location:** `pwa/src/components/Game.tsx` (lines 1528-1542)
+
+Added durability and tier information to the item info tooltip:
+
+```
+📦 Item Name
+Weight: 2kg
+Volume: 1L
+⚔️ Damage: 3-7
+🔧 Durability: 65/80  [NEW]
+⭐ Tier: 2            [NEW]
+```
+
+Shows for all equipment items with durability tracking.
+
+## Known Limitations
+
+### Durability-Based Item Stacking ⚠️
+
+**Current Behavior:**
+Items with different durability values currently stack together and show as a single inventory line. For example:
+- Knife (80/80 durability)
+- Knife (50/80 durability)
+
+These appear as "Knife ×2" in inventory.
+
+**Why This Happens:**
+The `add_item_to_inventory()` function in `api/database.py` (line 336) groups items by `item_id` only:
+
+```python
+result = await session.execute(
+    select(inventory).where(
+        and_(
+            inventory.c.player_id == player_id,
+            inventory.c.item_id == item_id  # Only checks item type, not durability
+        )
+    )
+)
+```
+
+**Required Fix:**
+To make items with different durability separate inventory lines, we would need to:
+
+1. Change `add_item_to_inventory()` to check durability as well
+2. Modify pickup, drop, and loot systems to handle durability-unique items
+3. Update combat loot generation to create unique inventory rows per item
+4. Adjust inventory queries to NOT group by durability for equipment
+
+**Complexity:** This is a significant change that affects:
+- Pickup system
+- Drop system  
+- Combat loot
+- Inventory management
+- Database queries across multiple endpoints
+
+**Recommendation:** Create this as a separate task since it requires careful testing to avoid:
+- Breaking existing inventory stacks
+- Creating duplicate item issues
+- Affecting non-equipment items (consumables should still stack)
+
+## Testing Checklist
+
+- [x] Equipment grid displays in character section
+- [x] Empty slots show placeholder icons
+- [x] Equipped items show name and durability
+- [x] Click equipped item to unequip
+- [x] Equipping to occupied slot auto-unequips old item
+- [x] Message shows what was unequipped
+- [x] Item info tooltip shows durability and tier
+- [x] Styling matches game theme (red borders for equipment)
+- [x] Build succeeds without errors
+- [ ] Durability stacking (NOT FIXED - see limitations above)
+
+## Files Modified
+
+1. `pwa/src/components/Game.tsx`
+   - Added equipment grid display (lines 1211-1336)
+   - Added durability to item info tooltip (lines 1528-1542)
+
+2. `pwa/src/components/Game.css`
+   - Added equipment sidebar styling (lines 1321-1412)
+
+3. `api/main.py`
+   - Enhanced equip endpoint messaging (lines 1108-1150)
+
+## Next Steps (Optional Future Work)
+
+1. **Durability-Based Stacking:**
+   - Refactor `add_item_to_inventory()` to check durability
+   - Update all item acquisition paths (pickup, loot, crafting)
+   - Add migration to separate existing stacked items by durability
+   - Test thoroughly with edge cases
+
+2. **Additional Equipment Items:**
+   - Create armor items for head, torso, legs, feet slots
+   - Add shields for offhand slot
+   - Balance encumbrance and stats
+
+3. **Weapon Upgrade System:**
+   - Repair mechanics (restore durability)
+   - Upgrade mechanics (increase tier)
+   - Crafting system integration
+
+4. **Visual Polish:**
+   - Add item rarity colors (common, uncommon, rare, epic)
+   - Animated durability bars
+   - Slot hover effects with preview
+   - Drag-and-drop equip from inventory to equipment grid