tiennm99bot/plans/260424-1335-twentyq-game-module/phase-03-gameplay-handlers.md

# Phase 03 — Gameplay Handlers + Render

## Context links

- Plan overview: `./plan.md`
- Foundation pieces: `./phase-01-foundation.md`
- AI client: `./phase-02-ai-client.md`
- Handler pattern reference: `src/modules/doantu/handlers.js`
- Render reference: `src/modules/doantu/render.js`
- Subject resolution + grammY ctx: `src/modules/loldle/handlers.js`

## Overview

- **Priority:** P1
- **Status:** planned
- **Description:** Wire all four commands (`/twentyq`, `/twentyq_giveup`,
  `/twentyq_stats`, plus the implicit ask/guess flow via `/twentyq <text>`)
  to the seeds + state + AI client. Build the renderer for board snapshots and
  per-turn replies. Manage round lifecycle: start → answer turns → solve/giveup.

## Key insights

- grammY `ctx.match` holds the slash-command argument string (everything after
  `/twentyq`). Empty `ctx.match` → board view OR start fresh round.
- Subject = user id in DMs (`ctx.chat.type === "private"`), chat id otherwise.
  Mirror `doantu/handlers.js` resolver.
- Auto-start rule: `/twentyq` with no args AND no active game → start a round.
  With args → submit input (start a round first if none).
- After a `solved` round: next `/twentyq` (any form) clears + starts fresh.
- Use Telegram HTML mode for output (matches loldle/doantu).

## Requirements

### Functional
- `/twentyq` (no args) — show board if active, else start a round and show
  intro line + initial hint.
- `/twentyq <text>` — validate input → if invalid, reply with rephrase hint
  (no state mutation, no AI call). If valid, call `judge`, append turn, reply
  with `yes/no + hint`. If `is_guess && answer==="yes"`, mark solved, record
  stats, reveal secret, congratulate.
- `/twentyq_giveup` — if active round, reveal secret + record loss; clear
  game key. Idempotent if no active round (replies "no active round").
- `/twentyq_stats` — render `{played, solved, totalTurns, bestTurnCount}`.
- Repeat-question detection: simple lowercased exact-text dedup against prior
  turns. If repeat → reply `🔁 already asked` and skip AI call (no count).

### Non-functional
- Each handler ≤80 LOC.
- HTML escape all user-rendered text via existing `src/util/escape-html.js`.
- Surface `UpstreamError` as a friendly "AI service hiccup, try again" reply.
- Each file ≤200 LOC.

## Architecture

```
src/modules/twentyq/
├── handlers.js     # handleTwentyq, handleGiveup, handleStats — the entry points
├── render.js       # formatBoard, formatTurnReply, formatGiveup, formatStats, formatIntro
└── index.js        # full module export with all four commands wired
```

```
ctx ──► handleTwentyq ──► loadGame
              │              │
              ├── empty arg ─┴── present? show board   : start round (intro)
              │
              └── arg present ─► validateQuestion → judge → save turn → reply
```

## Related code files

### Create
- `src/modules/twentyq/handlers.js`
- `src/modules/twentyq/render.js`

### Edit
- `src/modules/twentyq/index.js` — replace phase-1 stub with real commands array.

## Implementation steps

1. Create `src/modules/twentyq/render.js`:
   - `formatIntro(state)` → `"🎯 I'm thinking of a <category>.\nHint: <initialHint>"`.
   - `formatTurnReply({ answer, hint, isGuess, solved, target, turnCount })`:
     - solve win → `"🎉 Correct! It was <b>{target}</b>. Solved in {turnCount} questions."`
     - guess miss → `"❌ No. Hint: {hint}"`
     - regular yes → `"✅ Yes. Hint: {hint}"`
     - regular no → `"❌ No. Hint: {hint}"`
   - `formatBoard(state)` — initial hint + numbered list of past Q/A in `<pre>`.
   - `formatGiveup(state)` — `"🏳️ Gave up. The answer was <b>{target}</b>."`
   - `formatStats(stats)` — terse multi-line summary.
   - All target/text values HTML-escaped.
2. Create `src/modules/twentyq/handlers.js`:
   - `resolveSubject(ctx)` — same as doantu (private → user id, else chat id).
   - `handleTwentyq(ctx, { db, env })`:
     - Subject = resolveSubject.
     - `state = await loadGame(db, subject)`.
     - If state and `state.solved` → clearGame + treat as no game.
     - If no state and no `ctx.match` → start a round (call `getRandomSeed`,
       build state, save, reply `formatIntro`).
     - If no state and `ctx.match` → start round THEN process input as turn.
     - If state and no `ctx.match` → reply `formatBoard(state)`.
     - If state and `ctx.match` → process turn (see below).
   - Process-turn block:
     - `validateQuestion(text)` → on fail reply with reason.
     - Repeat-text check against `state.turns[].text` (lowercased) → reply
       `🔁 already asked`.
     - `await judge(env, state, text)`. Catch `UpstreamError` → friendly reply.
     - Append turn to `state.turns`. If `result.is_guess && result.answer === "yes"`:
       set `state.solved = true`; recordResult({solved:true, turnCount: turns.length}); clearGame.
     - Else save updated state.
     - Reply with `formatTurnReply(...)`.
   - `handleGiveup(ctx, { db })`:
     - Load game; if none → "no active round".
     - Else → recordResult({solved:false, turnCount}); reveal target;
       clearGame; reply `formatGiveup(state)`.
   - `handleStats(ctx, { db })` — load + render.
3. Replace `src/modules/twentyq/index.js`:
   - Mirror doantu shape: closure-scoped `db` set in `init`, plus `env` passed
     through to handlers (because we need `env.AI`). Two options:
       - **Option A (cleaner):** capture `env` in `init` alongside `db` and
         hand both to handlers.
       - **Option B:** pass `env` as `ctx.env` (grammY already exposes it via
         the worker handler binding). Confirm at impl time; if not exposed,
         use Option A.
   - Register 4 commands: `twentyq`, `twentyq_giveup`, `twentyq_stats`, plus a
     hidden alias if useful (skip for now per YAGNI).
4. Manual smoke test in `wrangler dev` (use ngrok / cloudflared tunnel + a
   throwaway test bot) — verify start, ask, guess-correct, giveup paths.

## Todo list

- [ ] `render.js` — all five formatters with HTML escape
- [ ] `handlers.js` — three handlers, subject resolver, repeat dedup
- [ ] `index.js` — full module export with `init({ db, env })` capture
- [ ] Confirm `env` propagation pattern (capture-in-init vs ctx.env)
- [ ] Manual smoke test happy path + giveup + repeat input
- [ ] `npm run lint` clean

## Success criteria

- Manual flow works end-to-end through Telegram.
- `is_guess && yes` ends round and records solve.
- `/twentyq_giveup` ends round, reveals, records loss.
- Repeat input does NOT increment turn count and does NOT call AI.
- Open-ended question ("what is it?") gets the validator's rephrase reply.
- KV state persists across cold starts (verified by waiting >30s between turns).

## Risk assessment

- **`env` propagation** — modules currently capture only `db` in `init`.
  Doantu/semantle capture `env` only enough to read URL config at init time,
  not for per-request AI calls. Need to capture the full `env` ref or change
  the dispatcher contract. **Decision: capture in `init` closure** — least
  invasive, no framework change.
- **Race condition on rapid double-send** — two near-simultaneous `/twentyq`
  questions could both load state, both write — last writer wins. Acceptable
  for v1 (KV is eventually consistent anyway; users notice nothing in normal
  pacing).
- **AI hint may leak the secret** despite system-prompt instructions.
  Mitigation: post-process hint to redact case-insensitive substring of
  `target`. Add as a defensive filter in `formatTurnReply` (cheap, ~3 lines).

## Security considerations

- All user-controlled strings (input text, target, hint) HTML-escaped before
  rendering.
- No KV keys derived from raw user text — only subject id + literal prefix.
- Secret-leak filter on hints (see Risk above).

## Next steps

→ Phase 04 — vitest coverage, README, help-command verification.