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: 10.5 (Add landing page, fix "Return to Emberfall" links, add link-checker test) — TICKED in STATUS.md
• Next step: Phase 10.6 — Restore REAL rate limiting (re-enable login/register limiters, mount global /api limiter before auth routes)
• Updated: 2026-10-22
• 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–006 / "nothing to do"
npm test	193 passing, 0 failing (85 unit + 108 integration incl. 5 new 10.5 tests)
npm run seed:dev	creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear
npm start + curl localhost:3000/	200 HTML landing page
npm start + curl localhost:3000/api/health	{"ok":true}

3. What exists now (files that matter)

• public/index.html — Landing page (title, tagline, Login/Register buttons; "Play" button when logged in with hero). Uses GET /api/auth/me to detect auth state.
• public/leaderboard.html — Stub page (placeholder text; real UI in 10.17).
• public/404.html — Custom 404 error page. "Return to Emberfall" links to /.
• public/500.html — Custom 500 error page. "Return to Emberfall" links to /.
• src/app.js — Root route now serves index.html instead of redirecting to /login.html.
• tests/integration/link-checker.test.js — Reads all public/*.html, extracts local href/src values, asserts each target file exists. Skips API endpoints.
• tests/integration/step-10.5.test.js — 5 tests: GET / returns 200 HTML, Play button when logged in with hero, Login/Register when no hero, anonymous shows Login/Register, 404/500 have working links.
• public/game.html — Dashboard with 3-col grid (stats | action | combat), mobile bottom nav.
• public/js/game.js — hunt UI + inventory UI + expedition UI + mobile nav init.
• public/css/main.css — All styles including 3-col desktop grid, mobile bottom nav.
• public/shop.html / public/js/shop.js — Shop page (buy/sell).
• public/login.html, public/register.html, public/create-hero.html — Auth & hero creation.
• public/profile.html / public/js/profile.js — Public hero profile page.
• public/js/auth.js — Shared API wrapper + showError.
• public/js/login.js — Login form submits to /api/auth/login; on success uses data.hasHero to redirect.
• public/js/create-hero.js — Checks /api/auth/me on DOMContentLoaded, redirects to /game.html if hasHero.
• public/js/toast.js — Shared toast notification system.
• src/services/expeditionService.js — Fixed in 10.1 (energy tx params) + 10.2 (uses applyXpGain) + 10.3 (injectable opts.now/opts.rng).
• src/services/huntService.js — Refactored in 10.2 to use applyXpGain.
• src/game/leveling.js — Added applyXpGain shared function.
• src/utils/time.js — { now, setNow, resetNow }.
• src/utils/rng.js — { mulberry32, rngInt, rngFloat, rngRange }.
• src/routes/auth.js — handleRegister and handleLogin set req.session.username.

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.
• 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.6 next: Need to re-enable real rate limiters in src/routes/auth.js (currently no-ops), mount global /api limiter BEFORE auth routes, add test for 429 response.
• 10.17 next (after 10.6, 10.7, 10.8–10.13, 10.14–10.16): Real leaderboard UI; remove stub; update link-checker exception.

5. Decisions & deviations from the docs

• D-004..D-007 in docs/DECISIONS.md (combat rounds, equipment counted once, session store, clock).
• D-014: Mobile bottom nav uses emoji icons (⚔️ Hunt / 🏕️ Trip / 🎒 Items) instead of full text labels.
• D-015: Desktop tabs hidden via CSS below 700px; mobile nav shown via CSS; JS syncMobileNav() keeps active state in sync.
• D-016: applyXpGain in src/game/leveling.js is the single shared function for XP gain logic, used by both huntService and expeditionService.
• D-017: Landing page public/index.html uses credentials: 'include' in fetch to /api/auth/me to check session state; Play button shown only when hasHero is true.
• D-018: Link-checker test skips API endpoints (/api/...) since they're not static files.

6. Gotchas learned

• npm test must be node --test with NO path/glob; files must be named *.test.js.
• better-sqlite3-session-store ignores expired.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.
• SQL SELECT id from inventory returns the auto-increment row id; rename with AS inventory_id when you also need item_id.
• Transaction callback args must match the call order exactly. (This is the 10.1 bug — double-check param/call order in every new transaction.)
• Error responses from route-level AppErrors do NOT include data field.
• setNow affects ALL now() calls including those in service logic.
• Shop API returns { ok: true, data: { stock: [...], character: {...} } } — field is stock, not stocks.
• Shop stock items have flat fields (itemId, buyPrice), not nested (item.id).
• New characters have NO inventory items (starter gear not auto-created yet).
• Hero profile endpoint is PUBLIC — no requireAuth middleware.
• Profile page is public: no auth.js guard needed; uses ?name= query param for lookup.
• Rate limiters in tests: set NODE_ENV=test to get 1000 req/window limit; otherwise tests fail with 429.
• seed-dev.js must check NODE_ENV=production before any require() that loads config (config throws on placeholder SECRET).
• Express sendFile rejects ../ path segments — use path.resolve() + path.join() for absolute paths.
• express.static sends its own 404 responses; catch-all must be placed BEFORE static middleware.
• Character profile GET returns { ok: true, data: { character, derived, energy } } — fields nested under character, derived, energy.
• Register returns 201 (Created), not 200.
• Character creation returns 201 (Created), not 200.
• Expedition start uses defId in request body (not expeditionId).
• Expedition claim uses expeditionId in request body.
• Expedition start response returns data.expedition.id — capture this for claim.
• src/utils/time exports { now, setNow, resetNow } directly — const time = require(...), not const { time }.
• Inventory sell endpoint (POST /api/shop/sell) only accepts material-type items.
• handleListInventory in src/routes/inventory.js — parameter name must be res, not _res.
• Character profile response has energy at data.energy.current, NOT data.character.energy.
• 10.3: expeditionService.js import changed from const { now, setNow } = require('../utils/time') to const time = require('../utils/time') — the destructured now variable was shadowed by the local opts.now ?? time.now() pattern.
• 10.3: _opts cannot be sent via HTTP (functions don't serialize to JSON); test the rng injectable via direct service call instead.
• 10.4: req.session.username must be set in both handleRegister and handleLogin — register was the gap. /me reads it, so without it username is always empty string.
• 10.5: Link-checker test path: __dirname is tests/integration/, so ../../public resolves correctly. API endpoints (/api/...) must be excluded from link-checking since they're not static files.

7. Next-step briefing

• Next step: 10.6 — Restore REAL rate limiting:
  • In src/routes/auth.js, the login and register limiters are no-ops (real ones commented out). Re-enable them.
  • Login: 10 requests / 15 min / IP. Register: 5 requests / hour / IP.
  • Use standard error envelope: { ok: false, error: { code: 'RATE_LIMITED', message: '...' } }, status 429.
  • Mount global /api limiter BEFORE auth routes in src/app.js (currently after, so it doesn't cover auth).
  • Limits may be relaxed when NODE_ENV=test (e.g., 1000 req/window).
  • Add a test: enable real limiter, send 10 bad logins → 401, 11th → 429 JSON.