let Q clear the selection, and keep selection and build mode apart

Q backed out of a build mode or toggled deconstruct mode; it now clears the
selection as its middle case. That needed a rule for a selection held while a
build mode is active, a state the code allows today: clearAll() is called only
by a click or drag that hit nothing, so a selection survives into builder,
blueprint, and deconstruct mode.

Make the two mutually exclusive instead, matching what the controls panel
already shows: entering any build mode clears the selection. The blueprint
gestures read the selection before the mode entry clears it, so C and Ctrl+C
lose nothing.

Drops the accuracy carve-out that had C / Ctrl+C merely omitted from the build
contexts on the strength of a surviving selection -- with no selection there,
they are unavailable rather than omitted, and the list is the three cases its
intro claims.

Requirements only; no code yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ne3mejABZoLWKLh8fgpM3x

docs/requirements.md

@@ -122,7 +122,7 @@ Any ship, module, building, or assembler recipe id that appears in no unlock gro
 - REQ-BLD-COST: The player places buildings from a build menu. Placement costs building blocks from the global stock. The cost per building type is read from `buildings.toml [[building]].cost`.
 - REQ-BLD-QUEUE: Placed buildings enter a construction queue and are built one at a time. Each building takes a duration defined in `buildings.toml [[building]].construction_time_seconds` to construct.
 - REQ-BLD-ASTEROID-ONLY: Buildings can only be placed on asteroid tiles (per surface_mask; tiles marked `S` may extend into space).
-- REQ-BLD-BUILDER-MODE: Clicking a build button activates builder mode for that building type. Builder mode is exited by right-clicking in the game world or clicking the same build button again. (Exception: while a belt drag placement is in progress, right-clicking cancels that drag instead of exiting, and builder mode stays active — REQ-BLD-BELT-DRAG.)
+- REQ-BLD-BUILDER-MODE: Clicking a build button activates builder mode for that building type, clearing the selection as entering any build mode does (REQ-UI-SELECTION-EXCLUSIVE). Builder mode is exited by right-clicking in the game world or clicking the same build button again. (Exception: while a belt drag placement is in progress, right-clicking cancels that drag instead of exiting, and builder mode stays active — REQ-BLD-BELT-DRAG.)
 - REQ-BLD-GHOST: While in builder mode, a ghost of the building is rendered at the tile under the cursor, showing where it would be placed. The ghost follows the tile the cursor points at, which includes the view scrolling (REQ-UI-SCROLL) under a cursor that has not moved: the ghost then moves across the world with the scroll rather than sticking to the tile it was last placed on by a mouse move, exactly as a running selection box does (REQ-UI-MULTI-SELECT). The same holds for everything else the hovered position determines — placement validity (REQ-BLD-PLACE-VALID), the tunnel end being placed (REQ-BLD-TUNNEL-MODE), a belt drag's path (REQ-BLD-BELT-DRAG), the blueprint ghost (REQ-UI-BLUEPRINT-MODE), and the deconstruct hover (REQ-UI-DECONSTRUCT-BUTTON). A cursor that is not over the game world — resting on one of the floating panels (REQ-UI-CONTROLS-PANEL, REQ-UI-BUILD-BAR, REQ-UI-SELECTION-PANEL), or outside the window — points at no tile and therefore hovers nothing: no builder ghost and no blueprint ghost is drawn, no tunnel connection is previewed, and no building is tinted as the deconstruct hover, until the cursor returns to the world. The mode itself is unaffected — the player is still building, just not over anything — and the position the ghost had is not remembered: it is re-derived from wherever the cursor comes back. This applies whenever the cursor points elsewhere, including at the moment a mode is entered, so a mode entered from a build button (REQ-UI-BUILD-BAR) shows its ghost only once the cursor is over the world, while one entered by hotkey (REQ-UI-HOTKEYS) under a cursor already there shows it at once. The one exception is a gesture that holds the mouse button — a belt drag (REQ-BLD-BELT-DRAG) or a selection or deconstruct box (REQ-UI-MULTI-SELECT, REQ-BLD-DECONSTRUCT-BOX) — which goes on following the cursor across the panels and beyond the window until the button is released. The ghost is drawn semi-transparently in the building type's own visuals — its `fill` and `outline` colors and `glyph` from `visuals.toml` — so that different building types are visually distinguishable in builder mode rather than all looking alike. When the current cursor position is invalid, the ghost instead uses the distinct "invalid" color (REQ-BLD-PLACE-VALID), which overrides the per-building coloring.
 - REQ-BLD-ROTATE: While in builder mode, pressing Shift+R rotates the ghost 90° clockwise and R rotates it 90° counter-clockwise. Rotation affects the direction of the output port.
 - REQ-BLD-PLACE: Clicking a valid tile in builder mode places a construction site and adds it to the build queue, consuming building blocks from the global stock. (For belts, placement is instead deferred to a drag gesture and happens on mouse release — REQ-BLD-BELT-DRAG.)
@@ -519,7 +519,12 @@ The screen is a single column: a header bar across the top and the game world vi
   - **W** — increases game speed by one step in the sequence 0×, 0.5×, 1×, 2×, 10× (no wrap-around past 10×).
   - **S** — decreases game speed by one step in the same sequence (no wrap-around past 0×).
   - **A / D** — scroll the view left / right (REQ-UI-SCROLL).
-  - **Q** — context-sensitive. If a build mode is active (builder mode or blueprint placement mode), pressing Q exits it. Otherwise, pressing Q toggles deconstruct mode: it enters deconstruct mode if inactive, or exits deconstruct mode if already active. (See also REQ-UI-DECONSTRUCT-BUTTON for the equivalent button.)
+  - **Q** — context-sensitive: one key that backs out of whatever the player is currently in, and enters deconstruct mode when they are in nothing. Its cases are evaluated in order:
+    - A build mode is active (builder mode, blueprint placement mode, or deconstruct mode) — Q exits it.
+    - Something is selected — Q clears the selection (REQ-UI-EMPTY-SELECTION). The two cases never both apply, a selection and a build mode being mutually exclusive (REQ-UI-SELECTION-EXCLUSIVE); the order is stated only to fix the reading.
+    - Neither — Q enters deconstruct mode (see also REQ-UI-DECONSTRUCT-BUTTON for the equivalent button, which enters it from any of these states and clears the selection in doing so).
+
+    Entering deconstruct mode by keyboard while holding a selection therefore takes two presses — the first clears it, the second enters the mode — whereas the Deconstruct button does it in one click.
   - **R / Shift+R** — in builder mode, rotate the ghost counter-clockwise / clockwise (REQ-BLD-ROTATE).
   - **C** — create a temporary blueprint from the current selection and enter its placement mode (REQ-UI-BLUEPRINT-TEMP). Has effect only when at least one player-placeable building is selected; otherwise it does nothing.
   - **V** — re-enter placement mode for the last temporary blueprint created with C (REQ-UI-BLUEPRINT-TEMP). Does nothing when no temporary blueprint exists.
@@ -559,6 +564,9 @@ The panel shows exactly one **content** at a time, picked from the catalog in RE
 
 - REQ-UI-EMPTY-SELECTION: When nothing is selected (no building, construction site, ship, defence station, or piece of debris), the selection panel is not shown at all — it is hidden rather than shown empty, so the full game world view is visible (REQ-UI-SELECTION-PANEL). It reappears as soon as an object is selected.
 - REQ-UI-SELECTION-CATEGORIES: **Selection categories and precedence.** Every selectable object belongs to one of two mutually exclusive selection categories: **buildings** (buildings and construction sites) and **field objects** (ships and defence stations — player or enemy — together with debris). A single selection holds objects from only one category at a time. Field objects of different kinds may be selected together (e.g. several ships plus debris, freely mixing player and enemy actors). Buildings are exclusive and take precedence — **buildings win**: selecting a building (by click, Ctrl+click, or a box-drag covering at least one building) clears any field selection and yields a buildings-only selection, and conversely selecting any field object clears any building selection. Point hit-testing prefers a building over a coincident field object, and among field objects prefers an actor (ship or defence station) over a coincident piece of debris (REQ-UI-ENTITY-CLICK-SELECT, REQ-UI-DEBRIS-CLICK-SELECT).
+- REQ-UI-SELECTION-EXCLUSIVE: **A selection and a build mode are mutually exclusive.** At any moment the player is either holding a selection or in one of the build modes — builder mode (REQ-BLD-BUILDER-MODE), blueprint placement mode (REQ-UI-BLUEPRINT-MODE), or deconstruct mode (REQ-UI-DECONSTRUCT-BUTTON) — never both. **Entering any build mode clears the selection**, whichever way the mode is entered: a build button, a build hotkey, the Deconstruct button, the Q deconstruct toggle, C, or picking a blueprint card (REQ-UI-HOTKEYS, REQ-UI-BLUEPRINT-TEMP, REQ-UI-BLUEPRINT-DIALOG). Switching directly from one build mode to another therefore has no selection left to clear. The converse direction needs no rule of its own: while a build mode is active there is no gesture that selects — a left click places, marks for demolition, or transfers settings instead (REQ-BLD-BUILDER-MODE, REQ-BLD-DECONSTRUCT-CLICK, REQ-UI-BLUEPRINT-TRANSFER) — so a selection can only be made after the mode is left.
+  - **A selection is read before it is cleared.** The gestures that act on the selection and then enter a mode capture it first: C builds its temporary blueprint from the selection and only then enters placement mode (REQ-UI-BLUEPRINT-TEMP), and Ctrl+C's save dialog creates its blueprint before the selection dialog it opens can start a placement (REQ-UI-BLUEPRINT-CREATE). Neither loses what it was invoked on.
+  - **What follows from it.** The selection panel is never shown while a build mode is active, being hidden on an empty selection (REQ-UI-EMPTY-SELECTION), and the world draws no selection outlines there. The controls panel's contexts (REQ-UI-CONTROLS-CONTENT) become a partition of the state rather than a precedence rule: exactly one of General, Selection, Build, Blueprint, and Deconstruct applies, and the Selection context's "no build mode active" clause restates the exclusivity instead of resolving an overlap. Nothing here reaches the simulation — selection and build mode are both presentation state, and clearing a selection is not a player command, never enters the replay stream, and has no effect on the simulation.
 - REQ-UI-SELECTION-CARD: **Card structure.** Every panel content is a card with the same three parts, top to bottom:
   - **Header** — always shown. It holds the selection's identity symbol on the left — the building's icon glyph (REQ-UI-WORLD-ICON), a ship's schematic color swatch, or the kind symbol of a defence station or piece of debris — the selection's name beside it, and one optional **right slot**. The right slot holds a status indicator (REQ-UI-SELECTION-STATUS), a ship's current behavior (REQ-UI-SHIP-BEHAVIOR), or an object count — never more than one of them; which one applies is stated per content in REQ-UI-SELECTION-CONTENT. The header carries no control of its own, and doubles as the panel's drag handle (REQ-UI-SELECTION-PANEL-DRAG).
   - **Configuration group** — the controls that change how the selected object is set up: the recipe/schematic selection control (REQ-UI-SELECT-BUTTON), a shipyard's layout preview and Configure button (REQ-MOD-UI-PREVIEW), and a splitter's output filters (REQ-BLD-SPLITTER). It is shown identically for an operational building and for a construction site of the same type (REQ-BLD-SITE-CONFIG).
@@ -647,7 +655,7 @@ The panel shows exactly one **content** at a time, picked from the catalog in RE
 - REQ-UI-BUILD-ICON: Each build button shows an icon. Icons are SVG files loaded at runtime from `data/icons/buildings/` (a sibling of the config directory, read the same way as `visuals.toml`), one file per button named after the building's id (e.g. `belt.svg`, `reprocessing_plant.svg`). The shared Tunnel button (REQ-UI-BUILD-BAR) uses `tunnel_entry.svg`; the Deconstruct button (REQ-UI-DECONSTRUCT-BUTTON) uses `deconstruct.svg`. Each icon is a rounded colored "chip" bearing a white line glyph, the chip color following the building's fill color in `visuals.toml`. A missing icon file leaves the button showing its building name as a text caption in place of the icon, so the button stays identifiable in the icon-only bar (REQ-UI-BUILD-COST); it is not an error.
 - REQ-UI-BUILD-TOOLTIP: Each building-type button shows a hover tooltip consisting of the building name followed by the descriptive text defined for that building type in `buildings.toml` (the optional per-building tooltip field). Because the button caption is icon-only (REQ-UI-BUILD-COST), the name is always part of the tooltip; if a building type defines no tooltip text, the tooltip shows the name alone. This tooltip is distinct from the item production tooltip of the selection panel's item chips (REQ-UI-ITEM-TOOLTIP); the recipe/schematic selection dialog has no tooltip at all (REQ-UI-SELECT-OPTIONS). The Deconstruct button (REQ-UI-DECONSTRUCT-BUTTON) is not a building type and so has no config-defined tooltip; it instead shows its own refund tooltip defined in REQ-UI-DECONSTRUCT-BUTTON.
 - REQ-UI-BUILD-DISABLED: Buttons for buildings the player cannot currently afford are shown as disabled. A disabled button's icon (REQ-UI-BUILD-ICON) is rendered in a greyed variant, with its colored chip background recolored grey while the white glyph is retained.
-- REQ-UI-DECONSTRUCT-BUTTON: A dedicated **Deconstruct** button is shown in the build button bar (REQ-UI-BUILD-BAR), as the last entry of the row and **visually separated** from the building-type buttons by a gap (not a divider line), because it toggles a mode rather than selecting a building type. Its face follows REQ-UI-BUILD-COST with two differences: its hotkey badge reads `Q`, and because it has no building block cost it shows its **Deconstruct** name as a text caption where the building-type buttons show their cost — so it is the one labelled button in the bar. It is therefore wider than the building-type buttons, which share a uniform width. Clicking it toggles deconstruct mode on and off, equivalent to the Q deconstruct toggle (REQ-UI-HOTKEYS). The button is shown in a visually active/pressed state while deconstruct mode is active. The button shows a hover tooltip stating the deconstruction refund (REQ-BLD-DECONSTRUCT): that deconstructing a fully-built building returns `world.toml [world].refund_percentage` percent of its building block cost once deconstruction completes, and that a construction site removed before it finishes building is refunded in full. When `refund_percentage` is 100% both cases yield the same refund, and the tooltip is simplified to state the single refund percentage without distinguishing the two cases. Unlike the building-type button tooltips (REQ-UI-BUILD-TOOLTIP), this tooltip is not config-defined text but is composed from the refund percentage.
+- REQ-UI-DECONSTRUCT-BUTTON: A dedicated **Deconstruct** button is shown in the build button bar (REQ-UI-BUILD-BAR), as the last entry of the row and **visually separated** from the building-type buttons by a gap (not a divider line), because it toggles a mode rather than selecting a building type. Its face follows REQ-UI-BUILD-COST with two differences: its hotkey badge reads `Q`, and because it has no building block cost it shows its **Deconstruct** name as a text caption where the building-type buttons show their cost — so it is the one labelled button in the bar. It is therefore wider than the building-type buttons, which share a uniform width. Clicking it toggles deconstruct mode on and off; entering the mode clears the selection (REQ-UI-SELECTION-EXCLUSIVE), which is the one way in which it differs from the Q key (REQ-UI-HOTKEYS): Q clears a selection before it enters the mode, so with something selected the button gets there in one click and Q in two. The button is shown in a visually active/pressed state while deconstruct mode is active. The button shows a hover tooltip stating the deconstruction refund (REQ-BLD-DECONSTRUCT): that deconstructing a fully-built building returns `world.toml [world].refund_percentage` percent of its building block cost once deconstruction completes, and that a construction site removed before it finishes building is refunded in full. When `refund_percentage` is 100% both cases yield the same refund, and the tooltip is simplified to state the single refund percentage without distinguishing the two cases. Unlike the building-type button tooltips (REQ-UI-BUILD-TOOLTIP), this tooltip is not config-defined text but is composed from the refund percentage.
 
 ### Controls Panel
 
@@ -698,7 +706,7 @@ The controls panel tells the player which controls are available right now. It i
   | | `LMB` drag | Select area |
   | | `Ctrl` `LMB` | Add / remove from selection |
   | | `Ctrl` `LMB` drag | Add area to selection |
-  | | `Q` | Deconstruct mode |
+  | | `Q` | Clear selection |
   | | `C` | Copy to temporary blueprint |
   | | `Ctrl` `C` | Create blueprint |
   | Build, Blueprint | `LMB` | Place |
@@ -716,7 +724,6 @@ The controls panel tells the player which controls are available right now. It i
   - **`LMB` — Place** reads **Apply settings** instead whenever the ghost under the cursor resolves to a configuration transfer (REQ-UI-BLUEPRINT-TRANSFER) — a single-building blueprint hovering a same-type building of a configurable type, which is the case in which clicking hands over settings rather than placing anything. A blueprint holding more than one building keeps the `Place` label, since its click both places and transfers (REQ-UI-BLUEPRINT-PLACE).
 - REQ-UI-CONTROLS-ACCURACY: **The panel never advertises a binding that would do nothing.** Every row shown must, if triggered in the situation the panel is showing it in, have the effect its label names; a binding that is inert in the current context is omitted rather than shown greyed (REQ-UI-CONTROLS-CARD). The relation holds in one direction only: the panel may omit a binding that is available, and deliberately does so in three cases:
   - **Build hotkeys** (REQ-UI-HOTKEYS) are live in every context, but are advertised on the build buttons' badges (REQ-UI-BUILD-COST) instead of taking eleven rows in every context of this panel.
-  - **`C` and `Ctrl` `C`** are omitted from the Build, Blueprint, and Deconstruct contexts even though a selection surviving into a build mode keeps them working. They belong to the Selection context, and repeating them in every mode would defeat the panel's purpose of showing what the player's current situation affords.
   - **`Ctrl` `LMB` and `Ctrl` `LMB` drag** work with nothing selected — they select the object under the cursor much as a plain click would — but are shown only in the Selection context. "Add / remove from selection" names an operation on a selection, and there is none to operate on until something is selected; the plain `LMB` row already covers what the gesture does before then.
   - **`F3` and `F4`** (REQ-UI-DEBUG-DRAW) are development controls rather than player controls and appear in no context.
 
@@ -749,7 +756,7 @@ Blueprints occupy no permanent screen space. They are saved with **Ctrl+C** from
 +------------------------------------------------------+
 ```
 
-- REQ-UI-BLUEPRINT-TEMP: Pressing the **C** key (REQ-UI-HOTKEYS) creates a **temporary blueprint** from the current selection and immediately enters blueprint placement mode for it, without opening the naming dialog. It has effect only when at least one player-placeable building is currently selected — the same condition as REQ-UI-BLUEPRINT-CREATE; pressing C with an empty selection, or a selection containing only non-player-placeable buildings (HQ, defence stations), does nothing at all, and in particular leaves any existing temporary blueprint in place. Entering this mode replaces any currently active build, blueprint placement, or deconstruct mode. The temporary blueprint is captured exactly as a saved blueprint (REQ-UI-BLUEPRINT-STORAGE), silently excluding any non-player-placeable buildings from the selection, but it is never named, never shown in the blueprint selection dialog (REQ-UI-BLUEPRINT-DIALOG), and never persisted to `blueprints.toml` (REQ-UI-BLUEPRINT-SAVE). Placement behaves identically to a saved blueprint's placement mode (REQ-UI-BLUEPRINT-MODE, REQ-UI-BLUEPRINT-PLACE): a ghost is rendered per building, R / Shift+R rotate the entire constellation, placement follows the same per-building validity and total-cost rules, and after a successful placement the mode stays active so the blueprint can be placed again. Right-clicking in the game world exits placement mode; unlike the mode, the temporary blueprint itself survives, so it can be entered again with V.
+- REQ-UI-BLUEPRINT-TEMP: Pressing the **C** key (REQ-UI-HOTKEYS) creates a **temporary blueprint** from the current selection and immediately enters blueprint placement mode for it, without opening the naming dialog. It has effect only when at least one player-placeable building is currently selected — the same condition as REQ-UI-BLUEPRINT-CREATE; pressing C with an empty selection, or a selection containing only non-player-placeable buildings (HQ, defence stations), does nothing at all, and in particular leaves any existing temporary blueprint in place. Entering this mode replaces any currently active build, blueprint placement, or deconstruct mode, and clears the selection — the blueprint is captured from it first, so C loses nothing (REQ-UI-SELECTION-EXCLUSIVE). The temporary blueprint is captured exactly as a saved blueprint (REQ-UI-BLUEPRINT-STORAGE), silently excluding any non-player-placeable buildings from the selection, but it is never named, never shown in the blueprint selection dialog (REQ-UI-BLUEPRINT-DIALOG), and never persisted to `blueprints.toml` (REQ-UI-BLUEPRINT-SAVE). Placement behaves identically to a saved blueprint's placement mode (REQ-UI-BLUEPRINT-MODE, REQ-UI-BLUEPRINT-PLACE): a ghost is rendered per building, R / Shift+R rotate the entire constellation, placement follows the same per-building validity and total-cost rules, and after a successful placement the mode stays active so the blueprint can be placed again. Right-clicking in the game world exits placement mode; unlike the mode, the temporary blueprint itself survives, so it can be entered again with V.
 
   Pressing the **V** key re-enters blueprint placement mode for the temporary blueprint, capturing nothing new: it is independent of the current selection, can be pressed any number of times, and yields exactly the mode described above. Like C it replaces any currently active build, blueprint placement, or deconstruct mode, and it does not test whether the player can currently afford the blueprint — cost is enforced at placement (REQ-UI-BLUEPRINT-PLACE), consistently with C. Pressing V when no temporary blueprint exists does nothing: no mode is entered and any currently active mode is left untouched.