Emberfall/HANDOFF.md

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: 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
npm run migrate	applies 001–004 and 006 / "nothing to do"
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/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 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 (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, dangling seed script, restart test, equipment-in-combat, HP regen, zone min_level balance).