zfxaction26_2/TASKS.md

# Reactor Maintenance Tasks

## Godot Frontend Integration

The Godot frontend (src/ReactorMaintenance.Godot) has a complete UX scaffold (splash to main menu to campaign intro to level screen to win/loss overlays) and reusable controls (StateBadge, PrimaryButton, CellInspector, ForecastList, InventoryStrip, ConfirmDialog, OutcomeOverlay) but no connection to the simulation core. This section covers bridging the gap.

### Phase 1: Simulation Bridge (Critical Path)

**Goal:** Connect LevelScreen to SimulationEngine so gameplay state flows between simulation and UI.

- [x] **Task 1.1: Create GameSession class**
  - Location: src/ReactorMaintenance.Godot/Data/GameSession.cs
  - Wraps SimulationEngine and holds the current LevelState
  - Loads LevelState from JSON via LevelSerializer.Deserialize() using Godot FileAccess
  - Exposes current state properties: RobotPosition, GlobalState, Terrain, Surface, UndergroundLayers, Props, Leaks, Forecasts
  - Fires events on state changes: OnLevelStateChanged, OnRobotMoved, OnTurnAdvanced, OnLevelWon, OnLevelLost
  - Exposes action methods: MoveRobot, EndTurn, InteractProp, InteractLeak, ApplyHeatShield, ActivateReactor
  - Validates actions before committing (rejects invalid moves)
  - Handles level start snapshot for retry

- [x] **Task 1.2: Create LevelStateLoader helper**
  - Location: src/ReactorMaintenance.Godot/Data/LevelStateLoader.cs
  - Static helper that takes a res://Data/Levels/... path
  - Uses Godot FileAccess to read JSON string
  - Calls LevelSerializer.Deserialize() and returns LevelState
  - Throws descriptive exceptions for missing files or schema errors
  - Supports both res:// and user:// paths

- [x] **Task 1.3: Wire LevelScreen to GameSession**
  - Update LevelScreen.Configure() to accept GameSession instead of raw CampaignLevel
  - Replace placeholder grid with real viewport
  - Wire CellInspector.SetCellInfo() to display live selected cell data
  - Wire ForecastList.SetForecasts() to display live simulation forecasts
  - Connect action bar buttons to GameSession action methods
  - Update LevelHeader with live global state badge (Stable/Caution/Critical/Ready)
  - Update InventoryStrip with live remedy/heat shield counts

- [x] **Task 1.4: Create res://Data/Levels/ directory and level files**
  - Create placeholder level files for the 3 campaign levels
  - Use Win2D editor to export v3 JSON schema for each level
  - Files: coolant_restart.json, fuel_bleed.json, black_start.json
  - Verify round-trip: load -> serialize -> deserialize -> validate

### Phase 2: Grid Viewport Rendering (Critical Path)

**Goal:** Replace the grid placeholder with a functional, interactive tile-based viewport.

- [x] **Task 2.1: Create GridViewport control**
  - Location: src/ReactorMaintenance.Godot/Controls/GridViewport.cs
  - Custom Control that renders the level grid via CanvasItem._draw()
  - Supports configurable tile size (default 48px)
  - Handles viewport scrolling and zoom
  - Exposes SelectedCell, RobotPosition, HoveredCell properties
  - Fires OnCellSelected, OnCellHovered, OnGridClicked signals

- [x] **Task 2.2: Implement terrain rendering**
  - Draw floor tiles with graphite/steel palette per ART.md
  - Draw wall tiles with darker steel, reinforced silhouettes
  - Apply subtle hue shifts between adjacent floor plates (no checkerboard)
  - Support layer opacity rules (surface full / underground 25% or 50%)

- [x] **Task 2.3: Implement prop rendering**
  - Draw props at cell centers with semantic colors
  - Show state indicators (enabled/disabled, producing/starved)
  - Use generated asset textures where available, fall back to procedural badges
  - Support prop highlight for selected cell

- [x] **Task 2.4: Implement robot marker**
  - Draw robot sprite at current RobotPosition
  - Show direction indicator
  - Use maintenance_robot.png from Assets/Characters
  - Animate on position change (optional, low priority)

- [x] **Task 2.5: Implement hazard rendering**
  - Draw surface hazards on affected floor cells
  - Use semantic colors: fuel (red slicks), coolant (blue-cyan), electricity (yellow arcs), heat (orange-white)
  - Show hazard intensity via saturation/opacity

- [x] **Task 2.6: Implement cell selection highlight**
  - Draw selection rectangle around selected cell
  - Draw reachable/actionable hints on valid move targets
  - Support hover highlight on non-selected cells

- [x] **Task 2.7: Implement underground network visualization**
  - Draw carrier-colored network lines between adjacent cells with positive flow
  - Fuel = red, Coolant = blue, Electricity = yellow
  - Render sources as large centered dots
  - Support layer toggle: show/hide each underground layer independently
  - Apply opacity rules per design doc

### Phase 3: Action Input System

**Goal:** Enable player interaction with the simulation through grid input and keyboard.

- [ ] **Task 3.1: Implement grid click-to-select**
  - Left-click on grid cell -> select cell, update CellInspector
  - Right-click -> context menu for available actions (repair, interact, etc.)
  - Click on robot position -> select robot cell

- [ ] **Task 3.2: Implement keyboard movement**
  - WASD / Arrow keys -> move robot to adjacent floor cell
  - Validate against SimulationEngine.MoveRobot before committing
  - Show rejected movement as brief toast/negative feedback
  - Tab -> cycle focus between grid, inspector, action bar buttons

- [ ] **Task 3.3: Implement action bar integration**
  - Move button -> enter move mode (highlight reachable cells)
  - Interact button -> execute prop interaction at robot position
  - Repair button -> repair reachable leak at robot position
  - Trigger Win / Trigger Lose -> remove for release, keep for dev testing
  - Disable buttons when action is invalid; keep them inspectable

- [ ] **Task 3.4: Implement Enter/Space action confirmation**
  - Enter -> confirm current action (interact, repair, activate)
  - Space -> quick action (move to adjacent in facing direction)
  - Escape -> cancel current mode, deselect

### Phase 4: UI Polish and Data Flow

**Goal:** Make all UI controls display live simulation data and feel responsive.

- [ ] **Task 4.1: Complete CellInspector data binding**
  - Display: position, terrain type, prop type, prop state
  - Display: surface hazards (type, amount, band)
  - Display: underground state (when all-seeing-eye active)
  - Update on every simulation step

- [ ] **Task 4.2: Complete ForecastList data binding**
  - Map EForecastKind values to display strings
  - Show turn offset (+1, +2, etc.) and severity band
  - Order from soonest to latest
  - Update on every simulation step

- [ ] **Task 4.3: Complete InventoryStrip data binding**
  - Display remedy counts (fuel/coolant/electricity remedy types)
  - Display heat shield count
  - Show depleted/empty states

- [ ] **Task 4.4: Complete LevelHeader data binding**
  - Display global state badge (Stable/Caution/Critical/Ready/Lost/Won)
  - Display reactor heat level with band coloring
  - Display campaign progress (Level X / Y)

- [ ] **Task 4.5: Add turn transition feedback**
  - Brief visual indicator when a turn is resolved
  - Show outcome of lengthy actions (prop toggled, leak repaired, etc.)
  - Toast/negative feedback for rejected actions

### Phase 5: Testing and Verification

**Goal:** Ensure simulation -> Godot data flow is correct and reliable.

- [ ] **Task 5.1: Write GameSession unit tests**
  - Load level from JSON -> verify LevelState matches expected
  - Execute actions -> verify state mutations match simulation engine
  - Test retry restores start snapshot
  - Test invalid action rejection

- [ ] **Task 5.2: Write LevelStateLoader tests**
  - Load existing level files -> verify successful deserialization
  - Load missing file -> verify descriptive exception
  - Load malformed JSON -> verify schema error message

- [ ] **Task 5.3: End-to-end integration verification**
  - Run Godot editor, load campaign, play through one full level
  - Verify all props, leaks, hazards render correctly
  - Verify cell inspector shows accurate data
  - Verify forecasts match simulation output
  - Verify win/loss overlays trigger at correct simulation states

- [ ] **Task 5.4: Verify Win2D to Godot level compatibility**
  - Export a level from Win2D editor -> load in Godot frontend
  - Verify all terrain, props, underground data, robot state, and inventory transfer correctly
  - Verify simulation engine produces identical results regardless of source

### Phase 6: Underground Layer Toggle (Medium Priority)

**Goal:** Allow the player to inspect underground networks when at an all-seeing-eye terminal.

- [ ] **Task 6.1: Implement all-seeing-eye viewing mode**
  - When robot is at an all-seeing-eye terminal, enable underground visibility
  - Show all three underground layers simultaneously with reduced opacity
  - Highlight the carrier of the active underground layer at full opacity

- [ ] **Task 6.2: Implement per-layer underground toggle**
  - Allow player to cycle through Fuel/Coolant/Electricity underground views
  - Each view shows only that carrier network at full opacity
  - Other layers at 25% opacity

### Phase 7: Release Cleanup (Low Priority)

**Goal:** Prepare the Godot frontend for release.

- [ ] **Task 7.1: Remove dev-only buttons**
  - Remove Trigger Win and Trigger Lose buttons from action bar
  - Replace with End Turn / Wait button

- [ ] **Task 7.2: Add loading state for level transitions**
  - Show loading indicator when loading level JSON
  - Handle slow load gracefully

- [ ] **Task 7.3: Export configuration**
  - Verify Godot export template for Windows works
  - Test standalone build with all assets bundled