Document campaign choice rescue

docs/UX.md

@@ -9,6 +9,7 @@ This document is the Godot implementation blueprint for the player-facing fronte
 - Keep menu flow short: splash, main menu, mode selection, level, outcome, next action.
 - Treat campaign as a linear chain of handcrafted levels with names and short flavor text.
 - Let players retry a lost level from its starting state and advance from a won level to the next campaign level.
+- Keep one-action setups in guided tutorial content; campaign levels should present at least two plausible lengthy interventions with different pulse outcomes.
 
 ## Scene Flow
 
@@ -166,7 +167,7 @@ Primary controls:
   - visible hazards, sprinkler water, and wet-electricity risk with safe/caution/critical bands
   - forecast warnings
 - `ActionBar`
-  - contextual action buttons: move, interact, activate sprinkler valve, repair, remedy, heat shield, activate reactor
+  - contextual action buttons: move, interact, toggle isolation valve, activate sprinkler valve, repair, remedy, heat shield, activate reactor
   - disabled buttons must show why the action is unavailable
 - `InventoryPanel`
   - fuel neutralizer count
@@ -178,16 +179,18 @@ Behavior:
 
 - Selection and inspection are quick actions and must not trigger a pulse.
 - Movement is a quick action and must update robot position without triggering a pulse.
-- Interact, sprinkler valve activation, repair, remedy, and heat shield are environment-changing actions and must trigger one animated pulse when accepted.
+- Interact, isolation valve toggles, sprinkler valve activation, repair, remedy, and heat shield are environment-changing actions and must trigger one animated pulse when accepted.
 - Activate reactor must be visually prominent when ready and should resolve immediately without requiring a wait or extra pulse.
 - Invalid actions should produce a short refusal message and not mutate level state.
 - When the level state becomes `Lost`, show `LoseOverlay`.
 - When the level state becomes `Won`, show `WinOverlay`.
 - When the reactor is ready, make `Activate Reactor` visually prominent but keep other valid actions available.
+- Before committing a lengthy action, the selected action state should expose the forecasted pulse consequence in plain terms such as isolated leak, restored pressure, downstream starvation, hazard growth, or reactor ready.
 
 Pulse playback behavior:
 
 - During a pulse, animate the configured steps as one short cascade of hazard motion, leak growth, quenching, evaporation, ignition, electrical conduction, and readiness updates.
+- Isolation valve toggles must visibly mark the affected underground branch, show stopped or restored pressure flow, and warn when downstream consumers or reactor feed will starve.
 - Sprinkler valve activation must visibly release blue sprinkler water at authored outlet cells and show the affected coolant service area losing pressure.
 - Evaporation must be communicated through shrinking wet overlays and stronger steam/cooling feedback on hot cells.
 - Wet cells that can spread electricity must use a distinct warning treatment so the player can distinguish helpful suppression water from dangerous electrified water.
@@ -305,15 +308,16 @@ Controls:
 
 Behavior:
 
-- Keep tutorial text focused on action economy, pulses, sprinkler suppression, evaporation, wet-electricity hazards, forecasts, remedies, and reactor activation.
+- Keep tutorial text focused on action economy, pulses, isolation valves, sprinkler suppression, evaporation, wet-electricity hazards, forecasts, remedies, and reactor activation.
 - Tutorial level can reuse `LevelScreen` with a tutorial mode flag and guided prompts.
+- A tutorial level may demonstrate a single safe lengthy action. The first campaign level should not be a single-action demonstration; it should ask the player to choose between service restoration, isolation, repair, or activation timing.
 
 ## Reusable Controls
 
 - `PrimaryButton`: consistent command button style and focus behavior.
 - `StateBadge`: color-coded label for `Stable`, `Caution`, `Critical`, `Ready`, `Lost`, and `Won`.
 - `LevelHeader`: level metadata, global state, and campaign progress.
-- `CellInspector`: selected cell details, visible hazards, sprinkler water, wet-electricity risk, prop state, underground details when available.
+- `CellInspector`: selected cell details, visible hazards, sprinkler water, wet-electricity risk, prop state, isolation valve branch impact, underground details when available.
 - `ForecastList`: ordered warnings from soonest to latest pulse.
 - `InventoryStrip`: remedy and heat shield counts.
 - `OutcomeOverlay`: shared base layout for win and loss overlays.
@@ -339,6 +343,7 @@ Keep repeated controls as separate scenes so the level screen, tutorial, and ove
   - coolant/sprinkler water: blue
   - electricity: yellow
   - heat: orange or white-hot accent
+  - isolated branch: muted carrier color with a broken-flow or valve marker
   - wet-electricity risk: yellow over blue or a distinct charged-water pattern
   - safe: neutral or green
   - caution: amber
@@ -356,6 +361,7 @@ Keep repeated controls as separate scenes so the level screen, tutorial, and ove
 - Final campaign win reaches `GameWonScreen`.
 - Full failure endpoint reaches `GameOverScreen`.
 - The level screen distinguishes quick actions from lengthy actions.
-- The level screen makes sprinkler valve outlets, evaporation, and wet-electricity risk readable before and after a pulse.
+- The level screen previews selected lengthy-action pulse consequences before commitment.
+- The level screen makes isolation valve branch effects, sprinkler valve outlets, evaporation, and wet-electricity risk readable before and after a pulse.
 - Forecasts, inventory, selected cell inspection, and global level state have dedicated UI space.
 - Documentation stays aligned with `docs/design.md` when simulation rules change.

docs/design.md

@@ -8,7 +8,7 @@ The simulation core is built from:
 
 - static floor and wall terrain,
 - underground fuel, coolant, and electricity networks,
-- surface props for controls, terminals, supplies, doors, and reactor activation,
+- surface props for sources, isolation valves, controls, terminals, supplies, doors, and reactor activation,
 - consumers that consume whichever underground services exist under their cell,
 - reachable leaks and sprinkler valves that project hazards or suppression water onto floor cells,
 - transport network structural integrity,
@@ -28,7 +28,7 @@ Quick actions do not mutate the environment and do not trigger a pulse:
 
 Lengthy actions commit an intervention and immediately trigger one pulse:
 
-- `InteractProp`: toggle flow props, toggle consumers, cycle junction ratios, open or close doors, pick up remedy supplies, or activate all-seeing-eye access from a terminal,
+- `InteractProp`: toggle flow props, toggle isolation valves, toggle consumers, cycle junction ratios, open or close doors, pick up remedy supplies, or activate all-seeing-eye access from a terminal,
 - `InteractLeak`: repair a reachable leak or apply a matching elemental remedy,
 - `ApplyHeatShield`: spend one heat shield and set heat immunity movement steps,
 - `ActivateReactor`: activate a ready reactor at the current reactor control prop.
@@ -65,6 +65,30 @@ The level is lost when:
 
 Consumer starvation blocks readiness but does not directly cause loss.
 
+## Campaign Progression
+
+The campaign grows by teaching one intervention grammar at a time. A guided tutorial may use a one-action setup to teach pulse playback, but campaign levels should not rely on a single obvious lengthy action. Every non-tutorial campaign level should present at least two plausible first interventions whose pulses create different readable consequences.
+
+Early levels can still use one carrier, but they need a real systems choice:
+
+- feed the service now and risk worsening a pressure-fed fault,
+- isolate the damaged branch and temporarily starve a consumer or reactor feed,
+- repair the leak while the root pressure remains unresolved,
+- reroute or rebalance the network before restoring service.
+
+Campaign authoring should answer two questions for each level:
+
+- What are the plausible first lengthy actions?
+- What does each resulting pulse visibly improve, worsen, or reveal?
+
+Recommended progression:
+
+1. Tutorial: one safe guided action may teach that lengthy actions trigger pulses.
+2. First campaign level: one carrier, one pressure-fed leak, one source, one isolation valve, one repair site, and reactor activation.
+3. Next single-carrier levels: add routing, junction ratios, doors, or limited remedies.
+4. Mid campaign: add heat and coolant sprinkler tradeoffs.
+5. Late campaign: add electricity, wet conduction, multi-service consumers, and full three-system cascades.
+
 ## Information
 
 The player can always inspect:
@@ -143,6 +167,7 @@ The derived level states are:
 Surface prop categories:
 
 - flow prop,
+- isolation valve prop,
 - consumer prop,
 - junction prop,
 - door prop,
@@ -157,7 +182,15 @@ Props exist on floor cells. Props do not directly participate in the surface haz
 
 A flow prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
 
-During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. A disabled flow prop injects nothing.
+During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. A disabled flow prop injects nothing. Flow props are source feeders; use isolation valves for branch shutoffs so startup, shutdown, and damaged-branch isolation stay readable as separate player decisions.
+
+### Isolation Valve Props
+
+An isolation valve prop is bound to fuel, coolant, or electricity and sits on a floor cell whose coordinate has exactly one matching underground carrier. It can be `Open` or `Closed`.
+
+During network flow, an open isolation valve allows carrier propagation through the underground branch normally. A closed isolation valve blocks intentional network propagation across that underground cell's connected branch boundary. Closing a valve can stop pressure or voltage from reaching a damaged segment, but it can also starve downstream consumers, sprinkler valves, or reactor feed.
+
+Toggling an isolation valve is a lengthy action and triggers one pulse. The forecast and inspection UI should make the affected branch, isolated leak, and downstream service loss readable before the player commits.
 
 ### Consumer Props
 
@@ -239,6 +272,8 @@ Each supply provides one matching inventory item and then becomes depleted.
 
 Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.
 
+Leaks are pressure-fed or voltage-fed faults. A leaking underground cell remains damaged until repaired, but fresh surface injection only occurs when the leaking cell currently receives positive amount and positive pressure or voltage from network propagation. Isolating a leak therefore stops new hazard growth without repairing the underlying fault. Repair removes the fault and restores structural integrity, but it does not clean hazards already on the surface.
+
 Fuel leaks:
 
 - occur under floor cells,
@@ -254,7 +289,7 @@ Electricity leaks:
 - can be repaired or remediated from that floor cell,
 - emit only to that stored face.
 
-All leaks must have valid floor access. Repair changes the underground cell from `Leaking` to `Intact`, restores structural integrity to max, and stops future injection. Repair does not clean existing surface hazards.
+All leaks must have valid floor access. Repair changes the underground cell from `Leaking` to `Intact`, restores structural integrity to max, and stops future injection. Repair does not clean existing surface hazards. If the repaired segment is immediately returned to unsafe pressure or voltage, structural integrity rules may damage it again on later pulses.
 
 The robot carries remedial consumables with balance-defined inventory capacity:
 
@@ -276,9 +311,9 @@ For each carrier:
 1. Clear transient carrier amount and pressure or voltage.
 2. Start from every enabled flow prop connected to that carrier.
 3. Walk through connected intact and leaking underground cells.
-4. Stop at absent cells and disconnected topology.
+4. Stop at absent cells, closed isolation valve boundaries, and disconnected topology.
 5. Apply distance falloff.
-6. Apply valid junction ratio weights.
+6. Apply valid junction ratio weights and isolation valve branch blocking.
 7. Assign each reached cell its best incoming carrier amount and best incoming pressure or voltage.
 8. Clamp final values.
 
@@ -288,13 +323,13 @@ A consumer is supplied when carrier amount, pressure or voltage, and connectivit
 
 ## Surface Hazards
 
-Leaking underground cells remain part of network propagation.
+Leaking underground cells remain part of network propagation unless isolated by a closed valve.
 
 During leak injection:
 
-- fuel leaks add leaked fuel to the accessible floor cell,
-- coolant pipe failures and sprinkler valves add sprinkler water to valid floor cells,
-- electricity leaks add leaked electricity to the stored floor emission face,
+- fed fuel leaks add leaked fuel to the accessible floor cell,
+- fed coolant pipe failures and sprinkler valves add sprinkler water to valid floor cells,
+- fed electricity leaks add leaked electricity to the stored floor emission face,
 - active matching remedy blocks prevent matching element entry.
 
 Injection magnitude is balance data and may depend on local carrier amount, pressure, or voltage. If the target floor cell has an active matching remedy block, that matching element is not injected into the cell for that step. Remedy blocks do not block other elements or heat.
@@ -447,6 +482,7 @@ Forecast output includes:
 - starved required consumer warnings,
 - growing hazard warnings when values cross caution or critical bands,
 - wet-electricity spread warnings,
+- isolation valve warnings for branch shutoff, restored pressure, isolated leaks, and downstream starvation,
 - coolant pressure-drop warnings from sprinkler valve use,
 - structural integrity leak warnings when weakened cells are expected to leak.
 
@@ -466,6 +502,7 @@ Validation errors:
 - invalid door cell,
 - invalid leak access,
 - invalid coolant sprinkler valve outlet or missing coolant network connection,
+- isolation valve without exactly one matching underground carrier,
 - junction without exactly one underground carrier,
 - ambiguous junction flow,
 - network loop or equal-source ambiguity at a junction,
@@ -477,6 +514,7 @@ Validation warnings:
 - underground cell with no source path,
 - initially starved required consumer,
 - initially unready reactor,
+- isolation valve with no meaningful upstream/downstream distinction,
 - unused remedy supply,
 - sprinkler valve with no useful suppression target,
 - visible hazard with no detectable nearby remedy or route.
@@ -488,6 +526,7 @@ The editor authors:
 - surface terrain,
 - underground fuel, coolant, and electricity cells,
 - flow props,
+- isolation valves,
 - multi-service consumer props,
 - required fuel, coolant, and electricity consumer counts,
 - junction props and balance-defined ratio mode index,
@@ -515,6 +554,6 @@ The loader accepts only schema-valid level data and returns clear errors for mal
 
 ## Balancing And Tests
 
-Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, sprinkler discharge, coolant pressure drops, evaporation, wet-electricity conduction, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
+Balancing defines source strengths, falloff, ratio math, isolation valve branch blocking, consumer predicates, leak magnitudes, sprinkler discharge, coolant pressure drops, evaporation, wet-electricity conduction, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
 
-Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, leak access, sprinkler valves, coolant pressure drops, coolant mitigation, evaporation, wet-electricity spread, remedies, door blocking, forecasts, and serialization round trips.
+Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, isolation valve branch blocking, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, pressure-fed leak injection, leak access, sprinkler valves, coolant pressure drops, coolant mitigation, evaporation, wet-electricity spread, remedies, door blocking, forecasts, campaign authoring rules, and serialization round trips.