# HANDOFF.md — Session Handoff (OVERWRITE at the end of every phase or when context is getting long)

> **Read order for a new session:** `NOTES.md` → `STATUS.md` → this file → then work.
> 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
- **Updated:** 2026-10-20
- **Was the last session cut off mid-task?** No

## 2. Verified state (run these first)
| Command | Expected |
|---|---|
| `npm install` | succeeds |
| `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
| `npm test` | **118 passing, 0 failing** (87 unit + 31 integration) |

## 3. What exists now (files that matter)
- `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp.
- `src/game/combat.js` — `resolveCombat(hero, monster, rng)`; both sides attack each round, faster first.
- `src/services/huntService.js` — `hunt(characterId, zoneId, {rng, now})`; ONE transaction; test-injectable.
- `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/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.

## 4. Half-finished / fragile things
- No consumable UI yet (Phase 5 step 5.4).
- No inventory grid/equipment panel/tooltips in game.html.
- 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`.
- Equipment bonuses not yet passed into combat (Issue #5 in STATUS.md).

## 5. Decisions & deviations from the docs
- D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
- Zod query param parsing uses `zod.coerce.number()` because Express query params are strings.
- 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.

## 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.
- better-sqlite3-session-store ignores `clear:false`; that's why the timer is unref'd.
- Statement caches are per-DB-handle (WeakMap) in huntService; copy that pattern for new services.
- Verify test COUNT, not just "all passing".
- Node.js `fetch` doesn't persist cookies across calls — extract `Set-Cookie` header and pass manually in integration tests.
- Express query params are strings, not numbers — use `zod.coerce.number()` for numeric query params.
- SQL `SELECT id` from inventory returns the auto-increment row id; rename with `AS inventory_id` when you also need `item_id`.
- `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.

## 8. Open Known Issues
STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).