step 5.4: done

HANDOFF.md

@@ -4,8 +4,8 @@
 > If this file disagrees with the code, trust the code and fix this file.
 
 ## 1. Where we are
-- **Last completed step:** 5.3 (stackable consumables: POST /api/inventory/use)
-- **Next step:** 5.4 — UI: inventory grid, equipment panel, tooltips with stats
+- **Last completed step:** 5.4 (inventory UI: tabs, equipment panel, inventory grid, tooltips)
+- **Next step:** 6.1 — Shop: `GET /api/shop`, `POST /api/shop/buy`, `POST /api/shop/sell`
 - **Updated:** 2026-10-20
 - **Was the last session cut off mid-task?** No
 
@@ -23,21 +23,22 @@
 - `src/services/zoneService.js` — `listZones(characterLevel)` → zones with `unlocked` flag.
 - `src/services/combatLogService.js` — `getCombatLog(characterId, limit)` → recent fights.
 - `src/services/characterService.js` — `createCharacter`, `getCharacterProfile`, `getCharacterIdForUser`.
-- **NEW:** `src/services/inventoryService.js` — `listInventory`, `equipItem`, `unequipItem`, `useConsumable`. Uses WeakMap stmt cache. Derived stats recalculated on list. Consumables: heal (capped at maxHp) and energy (capped at ENERGY_MAX), qty decrement, row removal at 0.
-- **NEW:** `src/routes/inventory.js` — `GET /api/inventory`, `POST /api/inventory/equip`, `POST /api/inventory/unequip`, `POST /api/inventory/use`. Zod-validated.
+- `src/services/inventoryService.js` — `listInventory`, `equipItem`, `unequipItem`, `useConsumable`. Uses WeakMap stmt cache.
+- `src/routes/inventory.js` — `GET /api/inventory`, `POST /api/inventory/equip`, `POST /api/inventory/unequip`, `POST /api/inventory/use`.
 - `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
 - `src/routes/zones.js` — `GET /api/zones`.
 - `src/routes/combatLog.js` — `GET /api/combat-log`.
 - `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE).
 - `src/db/migrations/004_inventory.sql` — inventory table, FK constraints, partial unique index for equipped slots.
 - `tests/integration/inventory.test.js` — 20 integration tests (13 equip/unequip + 7 consumable).
-- `public/game.html` — dashboard with stats panel, zone list, combat log, result panel.
-- `public/js/game.js` — full hunt UI: load zones, hunt handler, result display, combat log replay, toast notifications, energy sync.
-- `public/css/main.css` — zone cards, combat log entries, result panel, toast styles.
+- `public/game.html` — dashboard with stats panel, tabbed action panel (Hunt/Inventory), equipment panel, inventory grid.
+- `public/js/game.js` — full hunt UI + inventory UI: load zones, hunt handler, result display, combat log, tab switching, loadInventory, renderEquipmentPanel, renderInventoryGrid, equip/unequip/use handlers, tooltips.
+- `public/css/main.css` — zone cards, combat log, result panel, toast styles, tabs, equipment panel, inventory grid, tooltips, rarity colors.
 
 ## 4. Half-finished / fragile things
-- No consumable UI yet (Phase 5 step 5.4).
-- No inventory grid/equipment panel/tooltips in game.html.
+- No shop UI yet (Phase 6).
+- No expedition UI yet (Phase 7).
+- No leaderboard UI yet (Phase 8).
 - HP never regenerates naturally; only level-up restores it.
 - No restart-persistence test for sessions.
 - `npm run seed` script in package.json points to nonexistent `scripts/seed.js`.
@@ -49,6 +50,8 @@
 - Inventory response uses `itemId` (item.id) and `inventoryId` (inventory row id) to avoid confusion.
 - Consumable effect parsing: regex `^(heal|energy):(\d+)$` on items.effect field.
 - Qty decrement avoids CHECK constraint violation: delete directly when qty==1, decrement when qty>1.
+- UI uses emoji icons (⚔️🛡️💍🧪📦) for item types per UI_GUIDE recommendation.
+- Rarity colors match UI_GUIDE spec (common #b8b0a3, uncommon #5fb36b, rare #4a8fe0, epic #a45ee0, legendary #f2a23a).
 
 ## 6. Gotchas learned
 - `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`. A shell glob once skipped 17 tests.
@@ -61,11 +64,11 @@
 - `itemInSlot` query must alias `id AS inventory_id` so `existing.inventory_id` works in unequip logic.
 - Transaction callback args must match the call order exactly — passing `qty` as the second arg when the callback expects `etype` silently misapplies the effect.
 
-## 7. Next-step briefing (5.4)
-- **Goal:** UI for inventory — grid display of items (equipment + consumables), equipment panel showing current gear with stats, tooltips with stat bonuses.
-- **Docs:** GAME_DESIGN.md §Items, UI_GUIDE.md, API.md.
-- **Files to modify:** `public/game.html` (add inventory/equipment panels), `public/js/game.js` (load inventory, render grid, equip/unequip/use handlers, tooltips), `public/css/main.css` (inventory grid, tooltips, equipment panel styles).
-- **Key rules:** Use `GET /api/inventory` for data; render equipment slots + consumable list; show stat bonuses on hover; click to equip/unequip; click consumable to use.
+## 7. Next-step briefing (6.1)
+- **Goal:** Shop API endpoints — `GET /api/shop` (list stock), `POST /api/shop/buy` (buy items), `POST /api/shop/sell` (sell items). Sell value = 40% of base price. Gold never goes negative.
+- **Docs:** GAME_DESIGN.md §Economy, API.md, BALANCE.md.
+- **Files to create/modify:** `src/services/shopService.js`, `src/routes/shop.js`, register in `app.js`.
+- **Key rules:** Shop stock determined by character level (level-gated). Sell = 40% of buy_price. Use transactions for buy. Item slug → buy_price from items table.
 
 ## 8. Open Known Issues
 STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).