galaxy-game/ui/docs/ship-group-actions.md

# Ship-group inspector actions

Phase 20 turns the read-only ship-group inspector
(`ui/frontend/src/lib/inspectors/ship-group.svelte`) into an
interactive command source for the player's own groups in orbit.
This document is the running spec for the actions panel
(`ui/frontend/src/lib/inspectors/ship-group/actions.svelte`):
which actions exist, what gates each one, how partial-ship
operations split a group on the fly, and what the modernize cost
preview shows.

## Reaching a group

The map renderer hides on-planet ship groups to avoid crowding
the canvas. The player reaches an own on-planet group through the
planet inspector's **stationed ship groups** subsection: clicking
a row pivots the `SelectionStore` to the matching
`shipGroup.local` ref, the sidebar swaps from the planet
inspector to the ship-group inspector, and the actions panel
mounts. In-flight (in-space) groups appear as map primitives and
can be selected by clicking the rendered point.

## Action surface

| Action      | Implicit-split? | Partial input | FBS payload                  | Engine reference                                      |
| ----------- | :-------------: | ------------- | ---------------------------- | ----------------------------------------------------- |
| Split       |       —         | ships count   | `CommandShipGroupBreak`      | `controller/ship_group.go.breakGroup`                  |
| Send        |       yes       | ships count + destination | `CommandShipGroupSend` | `controller/ship_group_send.go.shipGroupSend`         |
| Load        |       yes       | ships count + cargo + quantity | `CommandShipGroupLoad` | `controller/ship_group.go.shipGroupLoad`              |
| Unload      |       yes       | ships count + quantity | `CommandShipGroupUnload` | `controller/ship_group.go.shipGroupUnload`            |
| Modernize   |       yes       | ships count + tech + level | `CommandShipGroupUpgrade` | `controller/ship_group_upgrade.go.shipGroupUpgrade` |
| Dismantle   |       yes       | ships count + foreign-COL confirm | `CommandShipGroupDismantle` | `controller/ship_group.go.shipGroupDismantle`         |
| Transfer    |       yes       | ships count + acceptor race | `CommandShipGroupTransfer` | `controller/ship_group.go.shipGroupTransfer`          |
| Join Fleet  |       —         | fleet name (existing or new) | `CommandShipGroupJoinFleet` | `controller/fleet.go.ShipGroupJoinFleet`              |

"Implicit-split" means the inspector accepts a number of ships
`M < N` and emits a `CommandShipGroupBreak(id, newId, M)` command
*before* the action command, then targets the action at the
freshly-minted `newId`. The FBS schema only carries a per-ship
`quantity` on `CommandShipGroupBreak`; every other ship-group
command applies to the whole group, so the implicit-split
pattern is the only way to act on a subset without forcing the
player to pre-split manually. Acceptance criteria: "splitting a
group of N into K and N-K results in two valid commands" — that
is exactly the (Break, Action) pair this pipeline emits.

Split and Join Fleet do not accept a partial ship count: Split
*is* the break operation; Join Fleet attaches the whole group
atomically (the engine handles a partial detach by issuing Split
first, which the player drives explicitly).

## Disabled-state rules

The inspector mirrors the engine's pre-conditions per command
(see the references column above) and surfaces each as a
disabled-button tooltip. Any state other than `In_Orbit` disables
every action with `ships are busy ({state})`. Per-action gates:

- **Send**: requires the ship class to have a non-zero drive
  block (`controller/ship_group_send.go:32`); the picker
  pre-filters destinations by reach
  (`localPlayerDrive * 40`), so a valid pick is always within
  range. With no reachable planet, the action is disabled with
  the "no planets in drive range" tooltip.
- **Load**: requires the orbit planet to be owned by the player
  or unowned (`controller/ship_group.go:215`) and the ship class
  to have a cargo block (`shipGroupLoad:220`). The dropdown is
  pinned to the existing cargo type when the group is already
  partially loaded (the engine refuses cargo-type changes at
  `shipGroupLoad:223`).
- **Unload**: requires non-empty cargo. Colonists (`COL`) over a
  foreign planet are blocked (`shipGroupUnload:283`), with the
  matching tooltip in the disabled state.
- **Modernize**: requires the orbit planet to be own/unowned
  (`shipGroupUpgrade:29`) and at least one block whose race tech
  exceeds the group tech (otherwise nothing can be upgraded).
- **Dismantle**: always available in orbit. When the orbit is
  over a foreign planet AND the group carries colonists, the
  inline form replaces the normal "confirm" with "confirm —
  colonists die"; the player has to click twice to commit
  (engine reference `shipGroupDismantle:177-179` — over a
  foreign planet, `UnloadColonists` is not called and the
  cargo is lost).
- **Transfer**: requires at least one non-extinct race other
  than the local player (sourced from
  `GameReport.otherRaces`).
- **Join Fleet**: existing-fleet picker is restricted to fleets
  in the same orbit (`fleet.go:135-137`); creating a new fleet
  always works.

## Modernize cost preview

The form's preview line calls
`core.blockUpgradeCost({ blockMass, currentTech, targetTech })`
once per ship block (drive, weapons, shields, cargo) and sums
the per-ship totals before multiplying by the targeted ship
count. Block masses come from the player's
`ShipClassSummary` for the group's class:

- Drive / shields / cargo block mass = the corresponding ship-
  class field (raw value).
- Weapons block mass = `core.weaponsBlockMass({ weapons,
  armament })` (Phase 18 bridge); returns null on the invalid
  weapons/armament pairing, in which case the row contributes
  zero.

For `tech === "ALL"` every block whose mass is non-zero
contributes against the player's race tech as the target. For
per-block tech (`DRIVE` / `WEAPONS` / `SHIELDS` / `CARGO`) only
the chosen block contributes, with `level` as the target.

The preview hides when the form is invalid (`tech !== "ALL"`
with non-positive `level`) or when `Core` has not yet booted —
the bridge call is the only source of truth, so we surface
"preview unavailable" rather than fall back to a JS
re-implementation that could drift from the engine.

## Wire shape

Every emitted command carries:

- `id` — client-minted UUID (`crypto.randomUUID()`), used by the
  order draft for status tracking; mirrored as
  `CommandItem.cmdId` on the wire.
- `groupId` — the source ship-group's UUID (or `newGroupId` when
  the action is the second half of an implicit split). On the
  wire it is the `id` field of every ship-group payload type.

Per-action additional fields are documented on the
`OrderCommand` union in
`ui/frontend/src/sync/order-types.ts` next to the JSDoc for each
variant.

## Decisions baked into Phase 20

- **`BlockUpgradeCost` migrated to `pkg/calc`**. The cost
  formula previously lived in
  `game/internal/controller/ship_group_upgrade.go`. To keep the
  `ui/core/calc` bridge a wrapper around pure `pkg/calc/`
  formulas, the function moved to `pkg/calc/ship.go` and the
  controller now imports it (`controller/ship_group_upgrade.go`).
- **`GameReport.otherRaces`**. The transfer-to-race picker reads
  from a new `GameReport.otherRaces: string[]` field, populated
  by walking `report.player[]` and excluding the local race plus
  every `extinct` entry. Phase 22 (Races View) reuses the same
  field.
- **Stationed-ship rows are clickable**. The map deliberately
  hides on-planet groups; the planet inspector's stationed-ship
  rows now pivot the selection to the corresponding ship-group
  variant so the actions panel is reachable from the standard
  click flow.