zfxaction26_2/TASKS.md

# Reactor Maintenance Rewrite Tasks

## Current State
- Approved design iteration targets the simulation model, rule removal, action economy, reactor requirements, and editor layer workflow.
- Work is proceeding on branch `design-iteration-structural-editor` in methodical commits.
- Completed commits:
  - `787f1e5` Document approved design iteration.
  - `3d40617` Restore complete design system documentation.
  - `e1ac56d` Rework simulation rules.
- Design documentation must preserve every existing system-level rule unless a change explicitly supersedes it. Superseded sections must document the replacement behavior with equal detail.
- The next implementation iteration is the Win2D editor overhaul.

## Completed Work
- Created the approved implementation plan for:
  - single multi-service consumers,
  - count-based reactor requirements,
  - cell-derived doors,
  - 0-10 structural integrity,
  - fixed automatic rule systems,
  - quick/lengthy action economy,
  - all-seeing-eye viewing without persistent unlocking,
  - layer-aware editor visualization and tools.
- Repaired the design documentation after the hazard-interaction regression:
  - restored the complete surface hazard interaction matrix,
  - documented that leaked coolant plus leaked fuel directly holds unless mediated by heat/electricity,
  - expanded structural integrity, consumer, reactor, all-seeing-eye, and action-economy details.
- Reworked simulation state and systems:
  - removed data-driven rule predicates/effects/events from runtime state, validation, forecasts, serialization, and tests,
  - replaced explicit reactor consumer bindings with unbound reactor controls plus required fuel/coolant/electricity consumer counts,
  - made consumer props carrier-agnostic with per-carrier service state derived from networks beneath the cell,
  - moved doors from explicit edge state to door props on floor cells with orientation inferred from opposing wall cells,
  - added underground structural integrity, high-pressure degradation, automatic leak creation, structural forecasts, and repair-to-max behavior,
  - removed action budgets and made movement quick while mutating interactions resolve one simulation step,
  - removed persistent all-seeing-eye unlocking from simulation state,
  - bumped serialized level schema to version 3.
- Updated simulation tests for the replacement systems:
  - consumer derivation and disabled consumer service state,
  - count-based reactor readiness and reactor-under-network positive-flow requirement,
  - quick movement versus lengthy door interaction,
  - inferred door blocking,
  - structural degradation, automatic leaks, repair integrity reset,
  - schema version 3 round-tripping and old-schema rejection.
- Kept the Win2D project compiling after the simulation model changes with narrow compatibility edits. Full editor workflow/rendering work remains outstanding.
- Verified after the simulation rework:
  - `dotnet test tests\ReactorMaintenance.Simulation.Tests\ReactorMaintenance.Simulation.Tests.csproj` passed with 23 tests,
  - `dotnet build ReactorMaintenance.slnx` passed with 0 warnings.
- Reworked the Win2D editor workflow:
  - added the Surface/Electricity/Fuel/Coolant layer combobox,
  - filtered tools by active layer and fixed exclusive tool selection,
  - rendered underground networks as carrier-colored centerline networks with source dots and layer opacity rules,
  - removed Rule Events, Reactor Binding, and pending workflow panels from the editor UI,
  - replaced two-click electricity leak authoring with electric-layer leak access cycling,
  - made Shift+left drag pan in all tools and Cursor drag move the robot or props.
- Added editor-helper tests for electricity leak access cycling and cursor drag movement behavior.
- Verified after the editor overhaul:
  - `dotnet test tests\ReactorMaintenance.Simulation.Tests\ReactorMaintenance.Simulation.Tests.csproj` passed with 26 tests,
  - `dotnet build ReactorMaintenance.slnx` passed with 0 warnings.

## Current Work
- Editor overhaul implementation is complete; commit is pending.

## Editor Overhaul Requirements
- Add a layer combobox with Surface, Electricity, Fuel, and Coolant.
- When Surface is active, draw the surface layer at full opacity and all underground layers at 25% opacity.
- When an underground layer is active, draw the surface layer at 50% opacity, other underground layers at 25% opacity, and the active underground layer at full opacity.
- Render coolant blue, fuel red, and electricity yellow.
- Render networks as thick lines connecting adjacent cell centers; render sources as large centered dots.
- Make tools layer-aware:
  - Cursor is always available.
  - Heat, Floor, Walls, Props, Consumers, Hazards, and Doors are only available for Surface.
  - Network painting and Sources are only available on their respective underground layers.
- Selecting a tool must deselect all other tools. The current two-way binding can leave multiple tools selected.
- Shift+LMB should pan the view in all tools, including Cursor mode.
- Cursor LMB drag should move any prop or robot from one cell to another.
- Remove Rule Events UI.
- Remove Reactor Binding UI.
- Remove editor workflow and pending actions.
- Door cells are redesigned as single prop cells.
- Electricity leak neighbour should be toggled by using the electric leak tool on an existing electric leak cell.

## Future Work
- Add authored sample levels once the new schema stabilizes.
- Tune structural integrity balancing after playtesting.
- Extend UI affordances for inspecting per-carrier consumer service state.

## 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.

- [ ] **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

- [ ] **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

- [ ] **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

- [ ] **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.

- [ ] **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

- [ ] **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%)

- [ ] **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

- [ ] **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)

- [ ] **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

- [ ] **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

- [ ] **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