galaxy-game/ui/docs/calculator-ux.md

Ship Class Calculator — UX

The ship-class designer and calculator are fused into one sidebar tool (lib/sidebar/calculator-tab.svelte). The standalone designer view/route was replaced by this combined tool. All numeric math lives in pkg/calc and is reached through the Core WASM bridge; the calculator holds input state and orchestrates, it never computes.

Modes

• Calculator (ship): the full tool — design area, derived results, planet build, goal-seek.
• Modernization: reuses the design area and shows per-block and total BlockUpgradeCost from the current tech to an editable target tech. The design-area component is extracted (lib/calculator/ship-design-area.svelte) so the future ship-group upgrade flow can reuse it.

The path mode from the original plan was dropped (MVP path-finding is brute force); reach circles on the map replace it. bombing is folded in as a per-ship result rather than a separate mode.

Areas

1. Ship Class design area — five blocks (drive, armament, weapons, shields, cargo) and four tech levels (drive, weapons, shields, cargo). Tech defaults to the player's current tech: the cell renders the inherited number with an open padlock; clicking the open lock activates an input (closed padlock), where the player may type an override at or above their current tech. Clicking the closed padlock resets to the default. The padlock slot is always reserved, so the column width does not shift as the lock state toggles. The four ship-class blocks (drive, weapons, shields, cargo) use a smart keyboard step that respects the engine value rule (0 or ≥ 1): ArrowUp from 0 jumps straight to 1, otherwise +0.1; ArrowDown from 1 collapses to 0, otherwise −0.1, never producing an invalid value in (0, 1). The native spinner is hidden on these inputs (it would produce invalid intermediates); armament keeps its native step 1.
2. Calculator area — derived results: empty/loaded mass, empty/ loaded speed, attack, defence, bombing (per ship), cargo capacity. A load toggle (empty / full / custom) sets the cargo load (in cargo units) that the loaded-column results use. At full the toggle shows the ship's cargo capacity; a custom load over that capacity is flagged as an error. With a zero cargo block there is no hold, so the load is pinned to empty and the toggle is disabled.
3. Planet area — when an own planet is selected on the map, shows its MAT (overridable) and the single-turn build rate (ships per turn, turns per ship). The MAT follows the same lock idiom as the tech cells: the planet number renders with an open padlock, clicking opens an input with a closed padlock, and the closed padlock resets to the planet value. The realistic multi-turn forecast with CAP/COL supply is planned (see ../ROADMAP.md).

Locks and goal-seek

Two distinct lock semantics share one padlock affordance. Both follow the same idiom — an open padlock (🔓) means value is inherited / derived, click to override; a closed padlock (🔒) means value is pinned by the player, click to reset:

• Override locks on inputs that have a default — the four techs and the planet MAT. By default the cell shows the inherited number plus an open padlock; clicking it switches to an input plus a closed padlock for typing the override. Closing (clicking the closed padlock) resets to the default. Any number may be overridden at once. Tech overrides are floored at the player's current tech on this turn — a lower value is flagged as invalid. The same floor applies to the modernization target tech.

• Goal-seek locks on derived results. Pinning a result back-solves the single input it claims, which then renders read-only (computed):

  result	claims
  attack	weapons block
  defence	shields block
  empty speed	drive block
  loaded speed	drive block
  empty mass	cargo block
  loaded mass	cargo load

  Only one result may be locked at a time (the others' lock affordances disable with a tooltip). An unreachable target — e.g. a speed above the stripped-hull ceiling 20 × driveTech, or a solved block that fails the value rules — leaves the locked cell in a red error state and does not apply. Inverse solving lives in pkg/calc/solve.go; the bisection for defence → shields is the only non-analytic case. Locking a speed is disabled when the drive block is zero (a deliberately immobile ship has no speed to back-solve). With the drive block as the only non-zero mass the displayed speed equals the ceiling exactly (every positive drive gives the same speed), so the solver accepts that ceiling target as a feasible lock and any positive drive solves it.

Validation and display

Every numeric input is validated independently and an offending one gets a red border and a hover/tap tooltip with the reason: no value may be negative, the five blocks follow the engine value rules (pkg/calc/validator.go, surfaced per-field by shipClassFieldErrors), and a custom load may not exceed cargo capacity.

Every displayed number — the derived results and the goal-seek back-solved input — is rounded up to three decimals through the shared pkg/calc/number.go.Ceil3 (bridged as core.ceil3), so a value is never shown lower than it is (a speed of 5.0003 reads 5.001). The engine keeps its own round-to-nearest util.Fixed*; Ceil3 is a display-only helper that lives in pkg/calc so the UI and Go share one implementation.

Create / load / delete

The name field is a combobox over the player's existing classes. Picking an existing class loads it as a template (so you can tweak and Create a new one); Create is disabled while the name is invalid or duplicate (reusing lib/util/ship-class-validation.ts). When a saved class is loaded, a Delete affordance appears. Create / Delete reuse the existing createShipClass / removeShipClass order-draft flow, so the optimistic overlay reflects the change immediately. Ship classes are immutable after creation (per game/rules.txt), so there is no edit — only Create-new and Delete.

Reach circles

When an own planet is selected in calculator mode, the calculator publishes the planet origin and the design's loaded speed to a shared store (lib/calculator/reach.svelte). The map view (lib/active-view/map.svelte) reads it and draws 1–3 thin concentric reach circles (map/reach-circles.ts) for 1/2/3 turns. The ring count shrinks as speed grows: a ring is dropped once the previous one reaches the torus wrap-midpoint (half the shorter side) or the no-wrap map edge (farthest corner). The circles clear when the selection clears or the design is invalid.

State preservation and history

Calculator inputs are component-local state. The sidebar keeps the tab mounted while the player navigates between active views, so inputs persist across view switches per the global state-preservation rule (ui/docs/navigation.md). Tech levels track the rendered report, so in history mode the calculator computes against the viewed snapshot's tech.

The ship-classes table and the view/bottom menus open the calculator via a shared request store (lib/calculator/load-request.svelte): the in-game layout flips the sidebar to the calculator tab and the calculator loads the requested class (or starts a fresh design).

Layout and mobile

Everything stacks vertically to fit the 18 rem sidebar; the design and result rows use compact two-column (ship/tech, empty/loaded) grids. On mobile the sidebar is the existing bottom-sheet/overlay; the calc bottom tab opens it.

Runtime note

The new bridge functions are only present after make wasm rebuilds ui/frontend/static/core.wasm (needs TinyGo). Vitest injects a fake Core (tests/fake-core.ts) mirroring pkg/calc, so unit/component tests do not need the rebuild; the Playwright suite and the live app do.