galaxy-game/ui/docs/calc-bridge.md

Calc bridge

The Galaxy frontend renders predictive numbers (free production potential, forecast output for a chosen production type, ship build progress, tech progress) that depend on the same formulas the engine uses at turn cutoff. To keep one source of truth, those formulas live in Go under pkg/calc/ and are surfaced to the UI through a Go → WASM → TypeScript bridge mounted under ui/core/calc/ and a matching TS adapter in ui/frontend/src/platform/core/.

The bridge covers the ship-math slice (everything the ship-class designer needs to render its preview pane), BlockUpgradeCost (for the ship-group inspector's modernize-cost preview), and the combat, planet-build, and goal-seek slice for the ship-class calculator: EffectiveAttack, EffectiveDefence, BombingPower, ShipBuildCost, ProduceShipsInTurn, and the inverse solvers from pkg/calc/solve.go. Other slices (production/science forecast, the realistic multi-turn planet projection) remain deferred. This document is the running audit trail of what is live, what is missing, and how each function maps to its pkg/calc/ source.

Live bridge surface

The Go module galaxy/core/calc (ui/core/calc/ship.go) exposes thin wrappers around pkg/calc/ship.go. Each is a one-line passthrough — the bridge contains zero math. The same names appear on the JS-side globalThis.galaxyCore (registered in ui/wasm/main.go) and on the typed Core interface (ui/frontend/src/platform/core/index.ts).

Bridge function	pkg/calc/ source	JS return shape	Used by
driveEffective	calc.DriveEffective(drive, driveTech)	number	designer preview (Speed input)
emptyMass	calc.EmptyMass(drive, weapons, armament, …)	number|null	designer preview (mass row)
weaponsBlockMass	calc.WeaponsBlockMass(weapons, armament)	number|null	designer preview, modernize cost preview
fullMass	calc.FullMass(emptyMass, carryingMass)	number	designer preview (full-load row)
speed	calc.Speed(driveEffective, fullMass)	number	designer preview (speed + range)
cargoCapacity	calc.CargoCapacity(cargo, cargoTech)	number	designer preview (cargo row)
carryingMass	calc.CarryingMass(load, cargoTech)	number	designer preview (full-load mass)
blockUpgradeCost	calc.BlockUpgradeCost(blockMass, currentTech, target)	number	ship-group inspector + modernization mode
effectiveAttack	calc.EffectiveAttack(weapons, weaponsTech)	number	calculator (attack result)
effectiveDefence	calc.EffectiveDefence(shields, shieldsTech, fullMass)	number	calculator (defence result)
bombingPower	calc.BombingPower(weapons, weaponsTech, armament, n)	number	calculator (bombing result, n = 1)
shipBuildCost	calc.ShipBuildCost(shipMass, material, resources)	number	calculator (planet build)
produceShipsInTurn	calc.ProduceShipsInTurn(L, material, resources, mass)	{ships,…}	calculator (planet ships/turn)
weaponsForAttack	calc.WeaponsForAttack(targetAttack, weaponsTech)	number|null	calculator goal-seek (attack → weapons)
driveForSpeed	calc.DriveForSpeed(targetSpeed, driveTech, restMass)	number|null	calculator goal-seek (speed → drive)
shieldsForDefence	calc.ShieldsForDefence(targetDefence, sTech, restMass)	number|null	calculator goal-seek (defence → shields)
cargoForEmptyMass	calc.CargoForEmptyMass(targetEmptyMass, restMass)	number|null	calculator goal-seek (mass → cargo)
loadForFullMass	calc.LoadForFullMass(targetFullMass, emptyMass, cTech)	number|null	calculator goal-seek (loaded mass → load)
ceil3	calc.Ceil3(value) (pkg/calc/number.go)	number	calculator display rounding (round up to 3 dp)

BombingPower and the per-turn build loop are no longer engine-only: BombingPower was extracted from game/internal/model/game/group.go and the per-iteration build math from controller.ProduceShip into pkg/calc (ProduceShipsInTurn); the engine now delegates to both — a true refactor, not a mirror. The inverse solvers (pkg/calc/solve.go) invert the forward formulas for single-target goal-seek and return null when infeasible; shieldsForDefence uses bisection, the rest are analytic. Parity and round-trip tests live in ui/core/calc/{ship,planet,solve}_test.go.

number|null returns mirror the Go (float64, bool) signature: the upstream validator rejects weapons/armament pairings with one zero side and the other non-zero, so the bridge returns null instead of silently zeroing. The ship-class form gates the preview behind its own validateShipClass so a user-visible null is the safety net, not the common path.

Composition (e.g., "full-load mass = fullMass(emptyMass, carryingMass(cargoCapacity, cargoTech))") happens in the TS preview component, not in the bridge — the Go side stays purely a marshalling adapter. Parity is exercised by ui/core/calc/ship_test.go, which calls each wrapper alongside the direct pkg/calc/ function on the same inputs and asserts byte-equal outputs.

Still-deferred slices

The Go-side bridge is intentionally narrow: it covers ship math and the combat/planet-build/goal-seek slice. Production forecasts, science, and reach (FligthDistance) still depend on either inline TS arithmetic or the engine-shipped fields on GameReport. See the table further down for what is missing and the per-feature waivers below for the rationale on each deferral.

Current pkg/calc/ exports

Function	Purpose
ShipProductionCost(shipEmptyMass float64) float64	Production units required per unit of ship empty mass (×10).
PlanetProduceShipMass(L, Mat, Res float64) float64	Ship mass produced per turn given free production L, material stockpile Mat, resources Res.
DriveEffective, Speed, EmptyMass, FullMass, …	Ship-level derivations (pkg/calc/ship.go).
BlockUpgradeCost(blockMass, currentTech, target)	Production cost of upgrading a single ship block (migrated from controller).
FligthDistance(driveTech), VisibilityDistance(...)	Race-level reach formulas (pkg/calc/race.go).
ValidateShipTypeValues, CheckShipTypeValueDWSC	Ship-design validators (pkg/calc/validator.go).

Nothing else lives in pkg/calc/ today. Production-side formulas (industry / materials / per-tech research / production capacity) sit in game/internal/model/game/planet.go and …/science.go and have never been exported.

Required calc functions per UI feature

The table below tracks what UI features need from the bridge and whether the underlying Go function exists.

UI feature	Go formula	In pkg/calc/?	Surfaced to TS?
Ship-class designer preview	EmptyMass, FullMass, Speed, DriveEffective, CargoCapacity, CarryingMass, WeaponsBlockMass (pkg/calc/ship.go)	yes	yes
Ship-group modernize cost preview	BlockUpgradeCost (pkg/calc/ship.go, migrated from game/internal/controller/ship_group_upgrade.go)	yes	yes
Ship calculator combat	EffectiveAttack, EffectiveDefence, BombingPower (pkg/calc/ship.go; BombingPower extracted from model/game/group.go)	yes	yes
Ship calculator goal-seek	inverse solvers in pkg/calc/solve.go	yes	yes
Free production potential (freeIndustry)	Planet.ProductionCapacity → industry*0.75 + population*0.25 (game/internal/model/game/planet.go)	no	no
Industry production output per turn	Planet.ProduceIndustry(freeProduction) (planet.go); freeProduction/5 modulo material constraint	no	no
Materials production output per turn	Planet.ProduceMaterial(freeProduction) (planet.go); freeProduction * resources	no	no
Per-tech research progress (DRIVE/WEAPONS/…)	ResearchTech (game/internal/model/game/science.go); freeProduction / 5000 per tech level	no	no
Custom-science progress	weighted form of ResearchTech driven by Race.Sciences[].(Drive|Weapons|Shields|Cargo) (science.go)	no	no
Ship build progress / planet build rate	ProduceShipsInTurn(L, Mat, Res, mass) (pkg/calc/planet.go, extracted from controller.ProduceShip); ShipBuildCost	yes	yes

partial means the Go primitives exist in pkg/calc/ but the composition (and the conversion of TS-side ReportPlanet/ ShipClass to the formula inputs) is not implemented anywhere.

Production forecast waiver

The inspector's planet production controls (segmented control + sub-pickers + collapse-by-planetNumber order command) do not surface the per-type forecast number. The inspector renders the existing freeIndustry row (free production potential) — that number is computed engine-side and ships in the report payload, so no calc-bridge access is required for it. The per-type forecast number is deferred pending promotion of the relevant formulas into pkg/calc/.

Reach formula waiver

Ship-reach filtering for the cargo-route destination picker uses a trivial engine formula:

flightDistance = driveTech * 40

The Go-side reference lives in pkg/calc/race.go as FligthDistance(driveTech) float64 (alongside the matching VisibilityDistance for in-space group reports). The engine call sites (game/internal/model/game/race.go.FlightDistance, game/internal/controller/route.go.PlanetRouteSet) still wrap the Go formula directly; promoting them to call pkg/calc/ is a pending cleanup.

Implementing the WASM glue for one constant-time multiplication would be premature scaffolding, so the picker computes reach inline in TypeScript using torusShortestDelta(planet.x, candidate.x, mapWidth) and Math.hypot against 40 * report.localPlayerDrive, where localPlayerDrive is decoded from the report's Player block by matching Player.name to report.race (api/game-state.ts.findLocalPlayerDrive).

When the remaining bridge work ships, the inline formula will be replaced with a single call into the bridge — calc.FligthDistance(driveTech) becomes the source of truth for both the picker and the cargo-route auto-removal at turn cutoff. Until then, the UI duplicates flightDistance knowingly — same precedent as the production forecast deferral above.

Planned bridge growth

The canonical bridge layout is established (Go subpackage + WASM registration + typed Core interface + parity tests). Future calc work follows the same shape:

1. Promote any still-engine-only formula from the table above into pkg/calc/ so the engine and the UI share one Go-side implementation. The engine continues to call them through its game/internal/... wrappers.
2. Add a thin one-line wrapper in ui/core/calc/ (new file per topic, e.g. ui/core/calc/planet.go for production forecasts). No math in the bridge.
3. Register the function in ui/wasm/main.go under globalThis.galaxyCore.
4. Extend the Core interface in ui/frontend/src/platform/core/index.ts with a typed signature and add the passthrough in wasm.ts.adaptBridge.
5. Add a parity test in ui/core/calc/<topic>_test.go and a feature-level test under ui/frontend/tests/.
6. Update this document — move the row from "missing" to the live surface table and link the test files.