# Production Play Screen Implementation Plan

## Overview

Create a new production play screen at `templates/game/play.html` with a 3-column layout optimized for immersive gameplay, separate from the dev console.

## Layout Structure

```
+-------------+------------------------+------------------+
|   LEFT      |        MIDDLE          |      RIGHT       |
|  (280px)    |       (1fr flex)       |     (320px)      |
+-------------+------------------------+------------------+
| Character   | Location Header        | [History]        |
| - Name/Lv   | - Name, Type, Turn #   | [Quests]         |
| - HP/MP     | Ambient Details        | [NPCs]           |
| - Stats     | ----------------       | [Map]            |
| ----------  | DM Response Area       |                  |
| Actions     | (main narrative)       | Each accordion   |
| [Free]      |                        | independently    |
| [Premium]   |                        | refreshable      |
| [Elite]     |                        |                  |
| ----------  |                        |                  |
| [Talk NPC]  |                        |                  |
| [Travel]    |                        |                  |
+-------------+------------------------+------------------+
```

## Files to Create

### Templates
| File | Purpose |
|------|---------|
| `templates/game/play.html` | Main 3-column layout |
| `templates/game/partials/character_panel.html` | Left: actions + character stats |
| `templates/game/partials/narrative_panel.html` | Middle: DM response + location |
| `templates/game/partials/sidebar_history.html` | Right accordion: turn history |
| `templates/game/partials/sidebar_quests.html` | Right accordion: active quests |
| `templates/game/partials/sidebar_npcs.html` | Right accordion: NPCs at location |
| `templates/game/partials/sidebar_map.html` | Right accordion: discovered locations |
| `templates/game/partials/job_polling.html` | Job status polling partial |
| `templates/game/partials/travel_modal.html` | Travel destination modal |
| `templates/game/partials/npc_chat_modal.html` | NPC dialogue modal |

### CSS
| File | Purpose |
|------|---------|
| `static/css/play.css` | All play screen styles |

### Flask Views
| File | Purpose |
|------|---------|
| `app/views/game_views.py` | New blueprint for production game routes |

### Modify
| File | Change |
|------|--------|
| `app/__init__.py` | Register `game_bp` blueprint |

## Flask Routes

```python
# Main routes
GET  /play/session/<session_id>              # Main play screen
GET  /play/session/<id>/character-panel      # Refresh character stats
GET  /play/session/<id>/narrative            # Refresh narrative
GET  /play/session/<id>/history              # Refresh history accordion
GET  /play/session/<id>/quests               # Refresh quests accordion
GET  /play/session/<id>/npcs                 # Refresh NPCs accordion
GET  /play/session/<id>/map                  # Refresh map accordion

# Action routes
POST /play/session/<id>/action               # Submit action -> job polling
GET  /play/session/<id>/job/<job_id>         # Poll job status

# Modal routes
GET  /play/session/<id>/travel-modal         # Get travel modal
POST /play/session/<id>/travel               # Execute travel
GET  /play/session/<id>/npc/<npc_id>/chat    # Get NPC chat modal
POST /play/session/<id>/npc/<npc_id>/talk    # Send message to NPC
```

## CSS Theme

```css
/* Dark fantasy theme matching existing */
--play-bg-primary: #1a1a2a;
--play-bg-secondary: #2a2a3a;
--play-border: #4a4a5a;

/* Action tiers */
--action-free: #3b82f6;      /* Blue */
--action-premium: #8b5cf6;   /* Purple */
--action-elite: #f59e0b;     /* Gold */

/* Resource bars */
--hp-bar-fill: #ef4444;
--mp-bar-fill: #3b82f6;
```

## Action Button Organization

**Free Tier (Blue):**
1. Ask Locals for Information (town/tavern)
2. Explore the Area (wilderness/dungeon)
3. Search for Supplies (any) - 2 turn cooldown
4. Rest and Recover (town/tavern/safe) - 3 turn cooldown

**Premium Tier (Purple):**
5. Investigate Suspicious Activity (any)
6. Follow a Lead (any)
7. Make Camp (wilderness) - 5 turn cooldown

**Elite Tier (Gold):**
8. Consult Ancient Texts (library/town) - 3 turn cooldown
9. Commune with Nature (wilderness) - 4 turn cooldown
10. Seek Audience with Authorities (town) - 5 turn cooldown

## HTMX Patterns

### Action Submission
```html
<button hx-post="/play/session/{id}/action"
        hx-vals='{"action_type":"button","prompt_id":"ask_locals"}'
        hx-target="#narrative-content"
        hx-indicator="#loading"
        hx-disabled-elt="this">
```

### Job Polling (1s interval)
```html
<div hx-get="/play/session/{id}/job/{job_id}"
     hx-trigger="load delay:1s"
     hx-swap="innerHTML">
```

### Cascade Refresh (after action completes)
```html
<!-- Hidden triggers in dm_response.html -->
<div hx-get="/play/session/{id}/history" hx-target="#accordion-history" hx-trigger="load" hidden></div>
<div hx-get="/play/session/{id}/npcs" hx-target="#accordion-npcs" hx-trigger="load" hidden></div>
```

## Responsive Design

- **Desktop (>1024px):** 3-column grid
- **Tablet (768-1024px):** 2-column, left sidebar as slide-out drawer
- **Mobile (<768px):** Single column, right sidebar as bottom sheet

## Implementation Approach: Visual First

Build complete UI with mock/sample data first, then wire up real API calls. This allows rapid iteration on layout and styling before integrating backend.

### Phase 1: Complete Visual Layout with Mock Data
1. Create `game_views.py` with main route using hardcoded mock data
2. Create `play.html` base template with 3-column grid
3. Create `play.css` with all styles (theme, grid, components)
4. Register blueprint
5. Build all visual components with sample content:
   - Left: Character panel with mock stats/actions
   - Middle: Narrative panel with sample DM text
   - Right: All 4 accordions with mock entries

### Phase 2: Interactive Components (No API)
1. Accordion toggle functionality (JavaScript)
2. Modal open/close (travel + NPC chat)
3. Action button states (hover, disabled, loading simulation)
4. Collapsible ambient details
5. Responsive breakpoints

### Phase 3: Wire Up API Integration ✅ COMPLETE (Nov 24, 2025)
1. ✅ Replace mock data with real API calls in Flask view
2. ✅ Implement job polling for actions
3. ✅ Wire up travel modal to `/api/v1/travel`
4. ✅ Wire up NPC chat to `/api/v1/npcs/{id}/talk`
5. ✅ Add HTMX refresh triggers for accordions
6. ✅ Wire up equipment modal with real character data

### Phase 4: Polish
- Error handling states
- Loading indicators
- Empty state messages
- Accessibility (ARIA labels, keyboard nav)

## Critical Reference Files

1. `public_web/templates/dev/story_session.html` - HTMX patterns, job polling
2. `public_web/app/views/dev.py` - Flask view patterns, API client usage
3. `public_web/static/css/main.css` - Theme variables, base styles
4. `api/app/data/action_prompts.yaml` - All 10 action definitions
5. `api/app/api/sessions.py` - Session API response formats

## API Endpoints Used

All endpoints already exist:
- `GET /api/v1/sessions/{id}` - Session state (updated to include `character_id`)
- `POST /api/v1/sessions/{id}/action` - Submit action
- `GET /api/v1/sessions/{id}/history` - Conversation history
- `GET /api/v1/jobs/{id}/status` - Poll job status
- `GET /api/v1/characters/{id}` - Character data
- `GET /api/v1/npcs/at-location/{id}` - NPCs at location
- `POST /api/v1/npcs/{id}/talk` - Talk to NPC
- `GET /api/v1/travel/available` - Available destinations
- `POST /api/v1/travel` - Travel to location

---

## Implementation Notes (Phase 3)

### Session Creation from Characters Page

Added the ability for players to create game sessions directly from `/characters`:

**Files Modified:**
- `public_web/app/views/character_views.py`
  - Updated `list_characters()` to fetch user sessions via `GET /api/v1/sessions` and map them to characters
  - Added new route `POST /characters/<character_id>/play` (`create_session`) that creates a session and redirects to play screen

- `public_web/templates/character/list.html`
  - Added sessions section showing active sessions per character (up to 3 displayed)
  - Added "Continue Playing" button (resumes latest session)
  - Added "New Session" button (creates new session)
  - Added "Start Adventure" button for characters without sessions
  - Added CSS for session badges (turn number, status indicator)

### Play Screen API Integration

**Files Modified:**
- `public_web/app/views/game_views.py`
  - Removed all mock data constants
  - Added helper functions:
    - `_get_user_tier(client)` - Gets user subscription tier
    - `_build_location_from_game_state(game_state)` - Builds location dict from session
    - `_build_character_from_api(char_data)` - Transforms API character response with robust defaults
  - Updated all routes to use real API calls:
    - `play_session` - Main play screen
    - `character_panel` - Character stats refresh
    - `narrative_panel` - Narrative content refresh
    - `history_accordion`, `quests_accordion`, `npcs_accordion`, `map_accordion` - Sidebar refreshes
    - `take_action` - Submit actions to API, return job polling partial
    - `poll_job` - Poll job status, handle NPC dialogue vs story responses
    - `equipment_modal`, `travel_modal`, `npc_chat_modal` - Modal data loading
    - `do_travel`, `talk_to_npc` - Execute travel and NPC dialogue

**New Template:**
- `public_web/templates/game/partials/npc_dialogue_response.html` - Displays NPC dialogue from job polling results

### API Changes

**Files Modified:**
- `api/app/api/sessions.py`
  - Updated `get_session_state()` to include `character_id` and `status` in response
  - This was required because the play screen needs to know which character to load

### CSS Fixes

**Files Modified:**
- `public_web/static/css/play.css`
  - Increased `max-width` from 1800px to 2400px for wider screens
  - Changed middle column from `1fr` to `minmax(500px, 1fr)` to ensure minimum width
  - Fixed NPC tags overflow:
    - Added `flex-wrap: wrap` to `.npc-tags`
    - Added `overflow: hidden` and `max-height: 3.5em`
    - Added `white-space: nowrap` to `.npc-tag`

### Bug Fixes

1. **Character data showing "Unknown"** - Fixed `_build_character_from_api()` to always return complete dict with sensible defaults even when API data is empty or incomplete

2. **API not returning character_id** - Updated `api/app/api/sessions.py` to include `character_id` in session state response

3. **NPC tags overflow** - Fixed CSS to wrap tags and hide overflow