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.4 (hunt endpoint) + a full review/fix pass
• Next step: 4.5 — hunt UI (needs GET /api/zones first, see STATUS issue 2)
• 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 run migrate	applies 001–004 and 006 / "nothing to do"
npm test	93 passing, 0 failing (69 unit + 24 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/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.

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 restart-persistence test for sessions.

5. Decisions & deviations from the docs

• D-004..D-007 in docs/DECISIONS.md (combat rounds, equipment counted once, session store, clock).

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".

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).

8. Open Known Issues

STATUS.md issues 1–6 (balance, zones endpoint, dangling seed script, restart test, equipment-in-combat, HP regen).