step 10.10: wip (not ticked)

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:** 10.9 — Allocation UI: unspent points display with + buttons per stat on dashboard stats panel — TICKED in STATUS.md
-- **Next step:** Phase 10.10 — POST /api/character/rest endpoint + dashboard button
+- **Last completed step:** 10.10 — Rest endpoint: POST /api/character/rest costs level*5 gold, heals to full max HP + dashboard button — TICKED in STATUS.md
+- **Next step:** Phase 10.11 — Natural HP regeneration: +1% max HP/min, lazy computation, new migration adds hp_updated_at
 - **Updated:** 2026-10-23
 - **Was the last session cut off mid-task?** No
 
@@ -14,29 +14,30 @@
 |---|---|
 | `npm install` | succeeds |
 | `npm run migrate` | applies 001–006 / "nothing to do" |
-| `npm test` | **222 passing, 0 failing** (85 unit + 137 integration incl. 8 allocation UI tests) |
+| `npm test` | **227 passing, 0 failing** (85 unit + 142 integration incl. 5 rest endpoint tests) |
 | `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
 | `npm start` + `curl localhost:3000/` | 200 HTML landing page |
-| Open `/game.html` logged in → check dashboard for allocation UI | Shows unspent points with + buttons when > 0, hidden when 0 |
+| Open `/game.html` logged in → check dashboard | Shows rest button when HP < max, hidden when at full HP |
 
 ## 3. What exists now (files that matter)
-- `public/game.html` — Added `#allocation-section` div (hidden by default) with unspent points display, alloc-rows container, alloc-total, alloc-apply-btn.
-- `public/js/game.js` — Added 5 allocation functions: `buildAllocationRows`, `handleAllocIncrement`, `updateAllocState`, `handleAllocApply`, `initAllocationUI`. Calls `initAllocationUI` from `loadCharacter`. Apply button listener attached in init.
-- `public/css/main.css` — Added allocation UI styles: `#allocation-section`, `.alloc-row`, `.alloc-btn`, `.btn-alloc-apply`.
-- `tests/integration/step-10.9.test.js` — 8 tests (5 HTML/JS structure + 2 API flow + 1 full flow).
-- `src/services/characterService.js` — `allocatePoints` function (from 10.8).
-- `src/routes/character.js` — `handleAllocate` handler (from 10.8).
+- `src/services/characterService.js` — Added `rest()` function: costs level*5 gold, heals to full max HP, errors NOTHING_TO_HEAL/INSUFFICIENT_GOLD
+- `src/routes/character.js` — Added `handleRest` handler, exported `postRest`
+- `src/app.js` — Mounted `POST /api/character/rest` route
+- `public/game.html` — Added `#rest-section` div with `#rest-btn` button (hidden by default)
+- `public/css/main.css` — Added `.btn-rest` styles
+- `public/js/game.js` — Added `initRestUI()`, `handleRest()`, calls `initRestUI` from `loadCharacter`, attaches click handler
+- `tests/integration/step-10.10.test.js` — 5 tests (happy heal, full HP rejection, insufficient gold, cross-user isolation, level scaling)
 
 ## 4. Half-finished / fragile things
 - No leaderboard UI yet (stub page exists; real UI in 10.17).
-- HP never regenerates naturally; only level-up restores it.
+- HP never regenerates naturally; only level-up/rest restores it. (10.11 next)
 - 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).
 - Starter gear documented but not auto-created on character creation.
 - `GET /api/zones` documented in API.md but not implemented (Issue #2).
 - Mobile nav uses emoji icons (⚔️ 🏕️ 🎒) — verify they render acceptably on all platforms.
-- **10.10 next:** Rest endpoint — costs level*5 gold, heals to full max HP.
+- **10.11 next:** Natural HP regeneration — +1% max HP/min, lazy computation like energy, migration adds hp_updated_at
 
 ## 5. Decisions & deviations from the docs
 - D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
@@ -94,8 +95,12 @@
 - **10.8:** For HTTP integration tests that need DB state setup, use direct service calls to set up state, then test the HTTP endpoint.
 - **10.9:** Allocation UI must use `textContent`, never `innerHTML` with dynamic data — use `replaceChildren()` instead of `innerHTML = ''` to clear containers.
 - **10.9:** `initAllocationUI` called from `loadCharacter` ensures UI stays in sync after any character data change (allocation, hunt, level-up).
+- **10.10:** `setupHero` helper must use `.then()` chain (not `return async () => { ... }`) — the latter returns a function that doesn't execute when awaited.
+- **10.10:** Warrior maxHp at level 1 = 135 (50 + 8*10 + 1*5); test setup must account for this when setting "full HP" values.
 
 ## 7. Next-step briefing
-- **Next step: 10.10** — Rest endpoint: `POST /api/character/rest` costs `level * 5` gold, heals to full max HP. Errors: `NOTHING_TO_HEAL` (422) if HP is already full, `INSUFFICIENT_GOLD` (422). One transaction. Add a "Rest (N gold)" button to the dashboard.
-- Read API.md §Rest and BALANCE.md §Rest for the spec.
-- The endpoint is similar to allocate (auth, zod validation, transaction, returns updated character + derived).
+- **Next step: 10.11** — Natural HP regeneration: +1% max HP/min, computed lazily like energy.
+- New migration (next unused number, likely 007) adds `hp_updated_at INTEGER` column to characters table; backfill existing rows with `energy_updated_at`.
+- Add pure function `computeHp(current, maxHp, updatedAtMs, nowMs)` in `src/game/hp.js` with unit tests (partial minute, cap at max, clock backwards, large gap).
+- Apply computeHp before HP checks in: hunting, `getCharacterProfile`, potion use, and rest.
+- Heals/damage must set `hp_updated_at = now`.