step 4.5: done

HANDOFF.md

@@ -4,47 +4,57 @@
 > If this file disagrees with the code, trust the code and fix this file.
 
 ## 1. Where we are
-- **Last completed step:** 4.4 (hunt endpoint) + a full review/fix pass
-- **Next step:** 4.5 — hunt UI (needs `GET /api/zones` first, see STATUS issue 2)
+- **Last completed step:** 4.5 (hunt UI — zones endpoint, combat-log endpoint, zone cards, hunt button, result panel, combat log replay)
+- **Next step:** 5.1 — inventory migration (`004_inventory.sql`)
 - **Updated:** 2026-10-20
 - **Was the last session cut off mid-task?** No
 
 ## 2. Verified state (run these first)
 | Command | Expected |
 |---|---|
-| `npm install` | succeeds (better-sqlite3 is a native module; needs Node 20+ and a C++ toolchain if no prebuilt binary) |
+| `npm install` | succeeds |
 | `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
-| `npm test` | **93 passing, 0 failing** (69 unit + 24 integration) |
+| `npm test` | **98 passing, 0 failing** (74 unit + 29 integration) |
 
 ## 3. What exists now (files that matter)
 - `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp (implemented in `leveling.js`).
 - `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`.
 - `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
-- `src/middleware/session.js` — real SQLite session store (timer unref'd).
-- `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE). Changing balance = NEW migration, never edit 003.
-- `tests/helpers.js` — `setup()/teardown()/cleanup()`: fresh app + temp DB per call. `tests/integration/hunt-service.test.js` shows how to force outcomes with test-only zones.
+- `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).
+- `tests/integration/zones-log.test.js` — 5 integration tests for zones + combat-log endpoints.
+- `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 `GET /api/zones` yet; `public/js/game.js` has no hunt UI yet (4.5).
-- HP never regenerates naturally; only level-up restores it (Rest/potions in Phases 5–6).
+- No inventory/equipment system yet (Phase 5).
+- 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`.
 
 ## 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.
 
 ## 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.
 
-## 7. Next-step briefing (4.5)
-- **Goal:** zone list + Hunt button + combat log replay + result summary + level-up message on the dashboard.
-- **Docs:** API.md §Hunting, UI_GUIDE.md §game.html, GAME_DESIGN.md §Combat.
-- **Files:** add `src/routes/zones.js` (+ service fn) and mount in app.js; extend `public/game.html` + `public/js/game.js`; add an integration test for `GET /api/zones`.
-- **Watch out for:** use `textContent` (no innerHTML); show energy cost on the button; disable button while request is in flight; re-sync energy from the hunt response (`data.energy`, `data.hpRemaining`, `data.hpMax`).
+## 7. Next-step briefing (5.1)
+- **Goal:** Create `004_inventory.sql` migration (inventory table + starting items for new heroes).
+- **Docs:** DATABASE.md, GAME_DESIGN.md §Items.
+- **Files:** `src/db/migrations/004_inventory.sql`.
+- **Schema:** `inventory` table (`id, character_id, item_id, quantity, equipped_slot NULL, acquired_at`), FK constraints. Starting items: class-appropriate common weapon (auto-equipped) + 2 Minor Healing Potions on character creation.
 
 ## 8. Open Known Issues
-STATUS.md issues 1–6 (balance, zones endpoint, dangling `seed` script, restart test, equipment-in-combat, HP regen).
+STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).