@@ 0,0 1,75 @@
+# systems-power
+
+**Branch:** `systems-power`
+
+Third milestone of the `ftl-shape` vertical slice. Adds the data + UI layer for player-allocatable reactor power across the 5 ship systems. No gameplay effect this milestone — the combat milestone consumes the data later.
+
+## Design
+
+**Purpose.** Introduce per-system power: the player ship has a fixed reactor capacity, each system has a current power level and a per-system cap, and the player allocates power via clickable HUD bars at the bottom of the screen. Visual feedback shows powered vs unpowered cells and dims unpowered system rooms in the ship view. The combat milestone later wires shields/weapons/engines behavior on top of this data.
+
+**In scope.** `System` data model (per-role power level + cap); fixed reactor capacity; bottom-screen HUD strip with one stacked-cell column per system + a `Reactor: used/cap` readout; left-click in column → +1 power, right-click → −1 power, both gated by caps; unpowered system rooms rendered dimmer in the ship view; disabling the browser context menu so right-click works in WASM.
+
+**Out of scope.** Damage to systems; per-weapon / per-shield-layer / engine-evasion power costs; crew manning bonuses; reactor upgrades, scrap, store, events; drag-to-allocate; animations on power change.
+
+**Chosen approach.**
+
+- **Data — new file `systems.go`** (pure, no Ebitengine):
+ - `type System struct { Role RoomRole; PowerLevel, MaxLevel int }`.
+ - `func NewStartingSystems() []System` — Pilot 0/1, Weapons 0/4, Shields 0/4, MedBay 0/2, Engines 0/4. Indexed by `int(RoomRole)`.
+ - `func reactorUsed(sys []System) int` — sum of `PowerLevel`.
+ - `func addPower(sys []System, role RoomRole, reactorCap int) bool` — true if level incremented; rejects if system at cap or reactor full.
+ - `func removePower(sys []System, role RoomRole) bool` — true if level decremented; rejects if level==0.
+ - `const ReactorCap = 8` — fixed for this milestone.
+
+- **HUD layout — new file `hud.go`** (pure, no Ebitengine; constants + math only):
+ - HUD strip occupies virtual `y ∈ [HudY=272, 360)` — 88 px tall, below the ship which ends at row 240.
+ - 5 columns, each `HudColW=40` wide, starting at `HudX=200`. Column band spans `x ∈ [200, 400)`, leaving the `x ∈ [0, 200)` band for the `Reactor: used/cap` readout and a 240-px right gutter.
+ - Each column shows `MaxLevel` cells stacked bottom-up; cell size 12×10 with 2 px gap.
+ - `func hudHitTest(px, py int) (role RoomRole, ok bool)` — returns the role whose column the pixel falls into, or `ok=false` for gutters / outside HUD region.
+
+- **Rendering — `render.go`** (modify):
+ - Add `func drawHud(screen *ebiten.Image, reactor int, sys []System)` — for each column: draw cells (role tint if `i < PowerLevel`, dim ~30% tint if `i < MaxLevel` but unpowered), 1-px outline per cell, role name above the column, `Reactor: used/cap` text to the left of the columns.
+ - Modify `drawShip` to take a `powered map[RoomRole]bool` (or equivalent) so unpowered system rooms render at ~60% brightness. Single new arg.
+
+- **Input — `main.go`** (modify):
+ - `Update` on left-click: if `cy >= HudY` → call `hudHitTest`; if hit, `addPower(...)`. Else (HUD miss) fall through to the existing crew select / move logic, gated on `cy < HudY` so HUD-area clicks never reach crew code.
+ - On right-click (`inpututil.IsMouseButtonJustPressed(ebiten.MouseButtonRight)`): if `cy >= HudY` and `hudHitTest` hits → `removePower(...)`. Right-click outside HUD is a no-op.
+
+- **WASM context menu — `web/index.html`** (modify): add `<body oncontextmenu="return false">` so right-click works in browser without spawning the OS context menu.
+
+**Tradeoffs that settled the decisions.**
+- Flat `[]System` indexed by role (vs `map[RoomRole]System`) — keeps iteration order stable for HUD column rendering and is trivial to look up. Map adds an ordering decision with no benefit at 5 entries.
+- `ReactorCap` as const (vs a `Reactor` field on `Game`) — one less moving part; combat milestone can promote it. YAGNI.
+- Pure `hud.go` (vs putting hit-test in `render.go`) — hit-testing is logic, not drawing. Mirrors the established `tiles.go` / `render.go` split.
+- Dimming unpowered rooms (vs no in-ship signal) — without it, allocation is invisible above the HUD and the milestone feels dead. A 30% darken of the room fill is one extra branch in `roleColor`.
+- Right-click for remove (vs shift-click) — FTL idiom; the WASM context-menu issue is a one-line `oncontextmenu="return false"` fix.
+
+**Unknowns.** Whether 30% dimming on unpowered rooms is enough visual signal at 640×360 zoom — resolved at verify; bump to 50% or add a "POWERED OFF" overlay tag if too subtle.
+
+**TDD: yes** — `addPower`, `removePower`, `reactorUsed`, and `hudHitTest` are pure functions with clear inputs/outputs and meaningful branching (cap reached, reactor full, level zero, column hit/miss, gutter miss). Rendering and input wiring stay manual smoke (browser).
+
+### Invariants
+
+- IV1 — `systems.go` and `hud.go` must not import Ebitengine. Power state and HUD geometry are pure.
+- IV2 — `addPower` / `removePower` are the only mutators of `System.PowerLevel`. Renderer never writes to `System`.
+- IV3 — `reactorUsed(sys) ≤ ReactorCap` holds after every `addPower` / `removePower` call.
+- IV4 — `0 ≤ PowerLevel ≤ MaxLevel` for every system at all times.
+- IV5 — Single codebase builds unchanged for `GOOS=js GOARCH=wasm` and native targets; no `//go:build` directives, no platform-suffixed files.
+- IV6 — HUD geometry constants live in `hud.go` and are referenced by both render and input paths; no duplication.
+
+### Principles
+
+- PC1 — Fail fast: invalid clicks (cap reached, reactor full, level zero, gutter) are silent no-ops, not partial state changes or wrap-arounds.
+- PC2 — Tests cover pure logic (`addPower`, `removePower`, `reactorUsed`, `hudHitTest`); rendering and input wiring stay manual.
+- PC3 — Separate data from rendering and input: `systems.go` doesn't know HUD pixel layout; `hud.go` doesn't know Ebitengine; `render.go` reads only.
+
+### Assumptions
+
+- AS1 — `inpututil.IsMouseButtonJustPressed(ebiten.MouseButtonRight)` works under `GOOS=js GOARCH=wasm`. Documented to; left-click was verified in crew-movement.
+- AS2 — `<body oncontextmenu="return false">` is sufficient to suppress the browser context menu so right-click reaches the canvas. Standard Ebitengine WASM pattern.
+- AS3 — The ship layout's bottom edge stays at virtual y ≤ 240, leaving the 272–360 band free for the HUD. True for `NewPlayerShip()` as defined; revisit if the ship grows.
+
+### Unknowns
+
+- UK1 — Whether 30% dimming on unpowered rooms is enough visual signal at 640×360 zoom. Resolved at verify by browser smoke.