shrike/flow.py

Part of SHRIKE.

"""The run lifecycle: the menu, the run, the Gate, the collapse and the ledger.

This module owns everything outside a single sector's second-to-second play:

* **Scene switching.** Every screen is a root scene handed to
  ``tree.change_scene``: :class:`MainMenuScene`, :class:`RunSetupScene`,
  :class:`DoctrineScene`, :class:`RunScene`, :class:`LedgerScene` and
  :class:`SettingsScene`. Each one
  declares ``input_context``, so the action map stays in force across every
  swap (an entry both scenes declare is continuous), and the
  meta-scoped nodes (the save system, the doctrine profile) are tree singletons
  that outlive them all. :class:`PauseScene` and :class:`DepotScene` are the
  exceptions that prove it: Escape and undocking both have to be able to come
  back, so the pause menu and the shop are overlays inside the live run rather
  than screens that replace it.
* **Run setup.** A hull and at most ``balance.DOCTRINE_MAX_ACTIVE_KEYSTONES``
  keystones, chosen before launch and frozen into a :class:`RunConfig`.
* **Depot delivery.** The depot sells; the run receives. Docking raises
  :class:`DepotScene`, the shop that shows the six items and the pity slot with
  their categories, prices and effects, the standing scrap offer at its honest
  rate, and the reroll at its doubling price. A purchase gate refuses, before
  payment, anything the hull cannot take, and every paid ``item_purchased``
  lands its goods: modules socket themselves, weapons mount or stow,
  consumables apply to the run state on the spot.
* **Spending Cores.** :class:`DoctrineScene` is the sixty-node tree drawn as
  one grid of five branches, reachable from the front door and from the ledger
  that pays the Cores out. Buying and the free respec both go through
  ``meta.MetaProfile`` and are written to the profile at once.
* **The two endings and the collapse.** Extraction through the Deep Gate pays
  ``balance.CONVERT_RATE_EXTRACTION``; death pays the punitive rate; and the
  Last Stand, offered the moment no warp on the chart is affordable, pays
  ``balance.LAST_STAND_CONVERT_RATE`` on scrap earned after the trigger, capped
  at ``balance.LAST_STAND_CORES_CAP`` Cores, while everything carried into the
  collapse still settles at the death rate. Both clauses are load-bearing: a
  collapse that paid the full rate on the whole hold would beat extraction and
  skip the Gate's toll.
* **The ledger.** Death is a deposit and a lesson, never a fail screen. The
  ledger itemises the conversion, pays the milestone bounties, scores the run,
  compares it against the hull's personal best, and prints one generated
  sentence naming the bet that ended it.
* **Settings.** Remapping, the shake, flash and hit-stop sliders, the
  photosensitivity mode, UI scale, hold-versus-toggle, and the Steady Wake
  assist panel, all persisted on the meta profile and all marked on the ledger.

``shrike.onboarding`` owns the staged first three runs; this module mounts its
director and asks it what is unlocked.
"""

from __future__ import annotations

import math
import random
import sys
from dataclasses import dataclass, field

from simvx.core import (
    Anchor,
    Button,
    CheckBox,
    Colour,
    Control,
    DeviceButton,
    DirectionalLight3D,
    Input,
    InputBinding,
    Key,
    Label,
    Node,
    Panel,
    PointerFilter,
    Property,
    Signal,
    Slider,
    UpdateMode,
    VBoxContainer,
    Vec2,
    Vec3,
)
from simvx.core.text.measure import LOGICAL_EM, measure_text_width
from simvx.core.ui import SizingMode

from . import artkit, balance, roost, runtime, save
from .bounty import Notoriety
from .chart import ChartGraph, StarChart
from .combat import DamageRouter
from .events import SignalEventDeck
from .hud import CONTROLS_BAR_SECOND_ROW, CONTROLS_BAR_TEXT, Hud
from .hunter import LANTERN_BLOW_ID, Hunter, HunterDirector, killing_blow
from .juice import JuiceDirector
from .meta import BRANCHES, DOCTRINE_TREE, HULLS, DoctrineNode, MetaProfile, branch_nodes, prerequisites_of
from .modules import MODULE_CATALOGUE, ModulePool, SocketRack, module_spec, sockets_for_hull
from .onboarding import Lessons as OnboardingLessons
from .onboarding import Onboarding, OnboardingDirector
from .power import Generator, PowerSystem, SignalWiring, SolarWings
from .runtime import PLANE_Y, CameraRig, Groups, Services, SignalNames, from_plane
from .sector import Sector
from .ship import PlayerShip
from .signature import SignatureMeter
from .trading import (
    CONSUMABLE_EFFECTS,
    CONSUMABLES,
    INTERACT_SELL_HOLD_S,
    REFIT_PREVIEW_PICK_MOUNT,
    REFIT_PREVIEW_SLOT_BARE,
    REFIT_PREVIEW_SLOT_FULL,
    REFIT_REFUSE_GUN_IN_SOCKET,
    REFIT_REFUSE_MODULE_ON_HARDPOINT,
    REFIT_REFUSE_TOO_LARGE,
    REFIT_REFUSE_TURRETS_FULL,
    REFIT_SLOT_EMPTY,
    Broker,
    Depot,
    Economy,
    category_label,
    effect_line,
    fit_panel_lines,
    item_name,
    item_summary,
    refit_preview,
)
from .waves import WaveComposer
from .weapons import HARDPOINT_OFFSETS, WeaponRack

# ============================================================================
# Module-local constants
#
# Everything here is a tuning number balance.py does not price. They are
# declared once, at the top, rather than inlined.
# ============================================================================

#: Run score's depth term: the sector-depth bonus, per sector reached.
SCORE_DEPTH_BONUS_PER_SECTOR = 25

#: Seconds a stranding must hold before the HUD offers the Last Stand, so a
#: momentarily empty tank beside a fuel comet is not a death sentence.
LAST_STAND_OFFER_GRACE_S = 3.0
#: Seconds after the offer before it accepts itself. A stranded run must not be
#: able to sit in an unwinnable crawl, which is the whole point of the rule.
LAST_STAND_AUTO_ACCEPT_S = 15.0

#: Photosensitivity mode's ceiling on bloom intensity, and its damping of the
#: warp distortion and every flash the juice layer drives.
PHOTOSENSITIVE_BLOOM_INTENSITY = 0.30
PHOTOSENSITIVE_FLASH = 0.25

#: UI scale slider bounds, from authored size up to 150 percent.
UI_SCALE_MIN = 1.0
UI_SCALE_MAX = 1.5

#: The three mix sliders, as fractions of full scale; ``shrike.audio`` owns the
#: decibel arithmetic they land as. Eight tenths rather than full, because the
#: bank is baked at a level that leaves headroom for the klaxon and a player
#: who wants the game louder than the room has somewhere to go.
VOLUME_DEFAULT = 0.8
VOLUME_MASTER = "volume_master"
VOLUME_SFX = "volume_sfx"
VOLUME_MUSIC = "volume_music"
VOLUME_SETTINGS: tuple[tuple[str, str], ...] = (
    (VOLUME_MASTER, "Master volume"),
    (VOLUME_SFX, "SFX volume"),
    (VOLUME_MUSIC, "Music volume"),
)

#: The resolved-modifier key, and the doctrine node behind it, that lift the
#: death rate from ``balance.CONVERT_RATE_DEATH`` to the upgraded rate. Both
#: names are meta.py's; they are read here so a run launched without a resolved
#: effect bag still settles at the rate the player bought.
DEATH_RATE_MODIFIER = "death_convert_rate"
DEATH_RATE_NODE_ID = "salvage_underwriting"

#: The starter fit. Two hardpoints, one gun and the harvest tool.
STARTER_WEAPONS: tuple[str, ...] = ("pulse_blaster", "mining_laser")

#: Starter power, in preference order: the first module that fits the hull is
#: socketed on the stern-most mount that takes it. Wings for any hull with a
#: large socket (they boot retracted; unfolding them is the game's first
#: posture choice), the RTG trickle for a hull too small to carry them.
STARTER_POWER: tuple[str, ...] = ("solar_wings", "rtg")

#: The sun that lights every sector.
SUN_DIRECTION = Vec3(-0.45, -1.0, -0.35)
SUN_COLOUR = (0.86, 0.90, 1.00)
SUN_INTENSITY = 1.15

#: Menu look. Near-black panels under warm text, the same contract the run uses.
MENU_BACKDROP = (0.01, 0.02, 0.03, 1.0)
MENU_PANEL = (0.06, 0.08, 0.11, 0.96)
MENU_TITLE_COLOUR = (1.00, 0.86, 0.42, 1.0)
MENU_TEXT_COLOUR = (0.84, 0.88, 0.95, 1.0)
MENU_DIM_COLOUR = (0.55, 0.60, 0.70, 1.0)
MENU_WIDTH_PX = 620.0
MENU_ROW_HEIGHT_PX = 30.0
#: Rough advance width of one glyph as a share of its point size, used to wrap
#: a panel's prose to the width of its own buttons before the labels exist.
MENU_GLYPH_ADVANCE_FRACTION = 0.56
MENU_SEPARATION_PX = 6.0
#: Pixels of panel around the column of rows, on all four sides.
MENU_PADDING_PX = 16.0
#: The gutter between a panel and the edge of the window. A panel that reaches
#: the edge reads as a screen that has already overflowed.
MENU_WINDOW_MARGIN_PX = 8.0
#: How far a column may be shrunk to fit a small window before the type stops
#: being worth reading. A screen that still overflows at the floor keeps the
#: floor: losing size is recoverable, losing the buttons off the edge is not.
MENU_MIN_FIT_SCALE = 0.5
#: How many times the fit is measured and re-applied. Type has minimum sizes
#: of its own, so a column scaled by a half does not come out half as tall, so
#: the fit converges rather than solving. Too few passes leave a screen a few
#: pixels short of its own gutter, where it reads as a screen that has already
#: overflowed. The extra passes cost a few measurements once, at build time,
#: and nothing per frame.
MENU_FIT_PASSES = 9
#: The window a panel assumes when it is measured with no backdrop and no
#: tree behind it, which only a test that builds one by hand ever does.
MENU_FALLBACK_WINDOW_PX = (1280.0, 720.0)
#: The focus ring, drawn as type. A row the cursor stands on is bracketed and
#: warmed: both, rather than either, so the selection survives a greyscale
#: screenshot and a player who cannot separate those two colours.
MENU_CURSOR_LEFT = ">"
MENU_CURSOR_RIGHT = "<"
MENU_SELECTED_COLOUR = (1.00, 0.86, 0.42, 1.0)
#: The footer every menu screen prints, so the keyboard is never a secret. The
#: second line is for the screens Escape actually backs out of.
MENU_CONTROLS_LINE = "MOVE: W/S OR ARROWS   CHOOSE: F, ENTER OR CLICK"
MENU_CONTROLS_LINE_BACK = f"{MENU_CONTROLS_LINE}   BACK: ESC"
#: The doctrine grid navigates on two axes, so it gets its own legend rather
#: than the column screens' one: it is the one screen in the game where the
#: controls are not the controls every other screen uses.
DOCTRINE_CONTROLS_LINE = "MOVE: WASD OR ARROWS   BUY: F, ENTER OR CLICK   BACK: ESC"

#: The run setup screen's hull row, and what pressing it says.
#:
#: It is one row, and the row cycles. A row per unlocked hull would be, on a
#: fresh profile, one row that looks exactly like a selector, brackets and all,
#: and answers the confirm key with nothing at all, so "> HULL: VAGRANT <"
#: would read as a broken control. With a single hull unlocked the row cannot
#: cycle, so it says so and names what would
#: unlock the others, which are feats rather than a rank: the screen also
#: prints them under the row, because the answer to "can I fly something else"
#: should not need a keypress to find.
SETUP_HULL_ROW = "HULL: {name} ({sockets} SOCKETS)"
SETUP_HULL_ROW_CYCLE = "HULL: {name} ({sockets} SOCKETS)   F: NEXT OF {count}"
SETUP_HULL_ONLY = "THE {name} IS YOUR ONLY HULL: THE OTHER {count} ARE EARNED IN FLIGHT, NOT BOUGHT"
SETUP_HULL_ONLY_ONE = "THE {name} IS THE ONLY HULL IN THE GAME"
SETUP_HULL_PICKED = "{name}: {description}"
SETUP_HULL_LOCKED_HEAD = "LOCKED HULLS, AND WHAT EARNS THEM:"
SETUP_HULL_LOCKED_ROW = "{name}: {feat}"

#: Settings rows that carry a value. A row that names only its verb
#: ("DAMAGE TAKEN: CYCLE") or only its name ("Screen shake") leaves the player
#: pressing it repeatedly to find out what it is set to.
SETTINGS_DAMAGE_ROW = "DAMAGE TAKEN: {percent:.0f}%   (CYCLE)"
SETTINGS_SLIDER_ROW = "{name}: {percent:.0f}%"
SETTINGS_SCALE_ROW = "{name}: {value:.2f}x"

#: The frame cap the player can choose, in frames per second. Zero follows the
#: display, which is what an uncapped vsync-gated loop does. Uncapped is not
#: free: a 144 Hz panel does two and a half times the work of a sixty-frame cap
#: for a twin-stick game that reads no better for it, and spends the difference
#: in heat and battery.
FRAME_CAP_OPTIONS: tuple[int, ...] = (0, 30, 60, 90, 120)
#: The row carries no NEXT LAUNCH warning: ``App.target_fps`` is read/write
#: mid-run, so the cap applies on the next frame like every other row on this
#: screen.
SETTINGS_FRAME_CAP_ROW = "FRAME CAP: {value}   (CYCLE)"
SETTINGS_FRAME_CAP_FOLLOW = "FOLLOW DISPLAY"

#: Boot straight into a run instead of the main menu. The game opens on its
#: front door, which is what a player expects and what the menu is for; the
#: switch survives because a debug session that wants a hull in the air one
#: keypress sooner should not have to edit the entry point to get one.
BOOT_STRAIGHT_INTO_RUN = False

#: What the HUD says when the chart is asked for in a run that has not earned
#: one yet, when the drive is spooled with nowhere to spool to, and when the
#: only depot in reach is a jump away. All three answer a key press, so they go
#: on the toast line rather than into the caption queue a kill chime shares.
#: A refusal saying only "THE CHART IS OFFLINE THIS RUN" would tell a pilot
#: neither why nor what to do instead. Run one flies a surveyed route: the
#: drive already holds it, so the answer to M is the key that takes it.
#: It names the flight and never a jump, because the gate is the run counter
#: and nothing else (:meth:`shrike.onboarding.Onboarding.chart_open`). A
#: refusal promising a chart "AFTER YOUR FIRST JUMP" would refuse a pilot who
#: did exactly what it asked again in the same words, for the whole run: a
#: condition run one cannot meet must never be printed as one it can. It
#: borrows its verb from the other schedule refusal the pilot meets,
#: :data:`shrike.power.SILENT_RUNNING_LOCKED_TOAST`, so the two locked keys
#: read as one schedule rather than as two unrelated excuses.
CHART_OFFLINE_TOAST = "STAR CHART COMES ONLINE NEXT FLIGHT: R FLIES THIS RUN'S SURVEYED ROUTE"
WARP_NO_DESTINATION_TOAST = "SELECT A DESTINATION: M"
WARP_UNAFFORDABLE_TOAST = "NOT ENOUGH FUEL FOR THAT JUMP: M"
DEPOT_ONE_JUMP_TOAST = "DEPOT: 1 jump (M)"
#: The affordance channel's fallback lines. Every other prompt belongs to a
#: thing in the world; these belong to the hull, so they are offered wherever
#: the ship is whenever a breach is open and nothing nearer wants the same key.
#: The second is the one the pilot with an empty hold needs: the patch channel
#: is priced, and an unpayable price must not answer a one-second hold with
#: nothing whatever.
PATCH_PROMPT = f"HOLD F: PATCH BREACH, {balance.BREACH_PATCH_SCRAP:.0f} scrap"
PATCH_PROMPT_BROKE = f"BREACH OPEN: patching needs {balance.BREACH_PATCH_SCRAP:.0f} scrap"
PATCH_PROMPT_RUNNING = "PATCHING BREACH: hold still"

#: The warp chip's states, in the order a pilot meets them. The last is run
#: one's: with no chart to pick from, the chip must not name the chart's key.
#: The ready line names the destination as well as the price, because every
#: arrival arms one: a chip quoting a bare number would leave the pilot no way to
#: know where the drive key was about to take them without opening the chart
#: to look, and the first line is the only place the answer can live.
WARP_STATUS_PICK = "WARP: pick destination (M)"
WARP_STATUS_READY = "WARP READY (R): {name} for {fuel} fuel"
#: The dry tank names where more comes from, because this is the one line the
#: pilot reads at the moment the tank is the problem. A pilot can fly a run to
#: a stop without ever finding a screen that says fuel is for sale: a
#: refusal that quotes the shortfall and stops there is a wall with the way
#: round it written somewhere else.
WARP_FUEL_SOURCE = "depots sell fuel cells"
WARP_STATUS_NO_FUEL = f"NO FUEL FOR WARP: need {{need}}, have {{have:.0f}} ({WARP_FUEL_SOURCE})"
WARP_STATUS_SURVEYED = "WARP READY (R): the route is already surveyed"
#: A jump's price, itemised whenever it is more than the base fare. A quoted
#: 22 where the base fare is 15 is a number a pilot cannot check and cannot
#: plan against: the surcharge is the whole reason to jump before the hunter
#: arrives rather than after it, so it is never charged without being named.
WARP_PRICE_PLAIN = "{total:.0f}"
WARP_PRICE_ITEMISED = "{total:.0f} ({base:.0f}{parts})"
WARP_PRICE_HUNTED = " +{extra:.0f} HUNTED"
WARP_PRICE_SKIP = " +{extra:.0f} SKIP"
WARP_PRICE_TOLL = " +{extra:.0f} TOLL"

#: The objective channel: one sentence per sector saying what the run wants of
#: this one. Run one is scripted because the pilot has no chart to plan with;
#: after that the line is read off the state the run is really in.
OBJECTIVE_RUN_1 = "OBJECTIVE: MINE THE GLOWING VEINS, SCOOP THE SCRAP, THEN PRESS R TO JUMP ON"
OBJECTIVE_BANK = "OBJECTIVE: BANK YOUR SCRAP AT THE DEPOT BEFORE THE SIGNATURE LOCKS"
OBJECTIVE_GATE = "OBJECTIVE: THE DEEP GATE IS ONE JUMP EAST, {fuel:.0f} FUEL. GET OUT WITH THE HOLD"
OBJECTIVE_ONWARD = "OBJECTIVE: FILL THE HOLD, THEN JUMP EAST. {columns} SECTORS TO THE DEEP GATE"
#: Scrap in the hold that makes banking the sector's objective.
OBJECTIVE_BANK_SCRAP = 60.0

#: How the HUD's key strip separates its entries, so flow can filter one out
#: without restating the strip.
CONTROLS_BAR_SEPARATOR = "   "
#: How the strip spells silent running before run three unlocks the posture.
#: The key stays on the bar, marked, rather than appearing out of nowhere on
#: run three: a strip that grows entries is a strip nobody reads twice.
CONTROLS_BAR_SILENT_LOCKED = "C SILENT (locked)"

#: How the pause panel joins the HUD's resource cells into one line.
PAUSE_RESOURCE_SEPARATOR = "   "

#: The action the persistent controls bar is hidden and shown with.
CONTROLS_BAR_ACTION = "toggle_controls"
CONTROLS_BAR_ON_TOAST = "CONTROLS BAR ON"
CONTROLS_BAR_OFF_TOAST = "CONTROLS BAR OFF: H BRINGS IT BACK"

#: Every bound gameplay key answers within :data:`KEY_ANSWER_WINDOW_S`, with an
#: effect or with a refusal that says why. A player who presses X, Z, Q, E,
#: Tab, Shift, F and G in an empty sector and gets nothing back from any of
#: them concludes the game is broken: a key that presses into silence is
#: indistinguishable from a key that is not bound. The run scene owns the
#: answers, because it is the one place that can see every system at once.
#:
#: The wings and the generator move real state, so their answers name the state
#: they moved to (including "already out", which is the answer a redundant press
#: earns and the one a player most needs). The scoop is passive and always
#: on; the answer says so rather than pretending the key toggles something.
KEY_ANSWER_WINDOW_S = 0.2
WINGS_DEPLOYING_TOAST = "SOLAR WINGS UNFOLDING"
WINGS_RETRACTING_TOAST = "SOLAR WINGS FOLDING IN"
WINGS_ALREADY_OUT_TOAST = "WINGS ALREADY OUT: FOLDING THEM IN"
WINGS_NONE_TOAST = "NO SOLAR WINGS FITTED: depots stock them"
GENERATOR_ON_TOAST = "GENERATOR RUNNING: loud, and it burns fuel"
GENERATOR_OFF_TOAST = "GENERATOR OFF"
GENERATOR_NONE_TOAST = "NO GENERATOR FITTED: depots stock them"
GENERATOR_REFUSED_TOAST = "GENERATOR WILL NOT START: no fuel, or running silent"
SCOOP_PASSIVE_TOAST = "TRACTOR SCOOP IS ALWAYS ON: fly over scrap to take it aboard"
SHIELD_MOVED_TOAST = "SHIELD PAD: Q AND E SWING IT ROUND THE HULL"
AFTERBURNER_TOAST = "AFTERBURNER: burns capacitor while it is held"
AFTERBURNER_FLAT_TOAST = "AFTERBURNER NEEDS POWER: the capacitor is flat"
INTERACT_NOTHING_TOAST = "NOTHING IN REACH"
JETTISON_NOTHING_TOAST = "NOTHING TO JETTISON: the hold is empty"
JETTISON_NO_HUNTER_TOAST = "NOTHING OUT THERE TO BAIT: jettisoned scrap only buys time from the Shrike"
JETTISON_DONE_TOAST = "SCRAP JETTISONED AS BAIT"

#: The sector arrival card: the place's name and one line about what it is for.
#: Without it a warp would land the ship in an unnamed field of rocks
#: indistinguishable from the last one, and nothing about travelling would read
#: as travel. The name is
#: derived from the biome id the way the chart derives its own labels; only the
#: flavour is authored, and it is authored here because balance.py's biome notes
#: are written for whoever is tuning the drop tables.
SECTOR_FLAVOUR: dict[str, str] = {
    "debris_field": "old wrecks, loose scrap, nothing that was not already broken",
    "solar_shallows": "open starlight: the wings pay double and make you a target",
    "ice_field": "frozen air in the rocks; poor scrap, full lungs",
    "nebula": "no light for the wings and no bearing on what is coming",
    "wreck_graveyard": "a fleet died here; the hulls are still worth taking apart",
    "vent_field": "fuel and air venting from the seams, and mines drifting in them",
    "broker_claim": "someone else's market, guarded, and it deals in what depots will not",
    "roost": "the nest. There is no jumping out of this one",
}

#: What the Wake's swept ground costs, once the chart lets a pilot back into
#: it. Red columns are jumpable at the ordinary price and the bill falls here
#: instead: the meter starts most of the way to a lock, and whatever the
#: arrival count, the Shrike gives the short warning. Both numbers live in this
#: module rather than in balance.py because they are the run scene's reading of
#: a chart state, not a table the sector generator or the ladder consults. The
#: signature start sits above every act floor (0 / 20 / 40) so the price is
#: real in the Shallows and still real in the Deep, and the telegraph matches
#: the nebula's, which is the shortest warning the game already gives.
WAKE_TERRITORY_SIGNATURE_START = 65.0
WAKE_TERRITORY_TELEGRAPH_S = balance.SHRIKE_TELEGRAPH_NEBULA_S
#: How the arrival reads. The stamp is the moment, the flavour is the arrival
#: card's second line, and the toast is the sentence that names the deal.
WAKE_TERRITORY_STAMP = "SHRIKE TERRITORY"
WAKE_TERRITORY_FLAVOUR = "swept ground: it has already hunted here, and it knows the shape of these rocks"
WAKE_TERRITORY_TOAST = "SHRIKE TERRITORY: IT IS WAITING. SIGNATURE HIGH, WARNING SHORT"
#: And the same deal arriving the other way round: the front catching a pilot
#: who spent their jumps going backwards, in the sector they are standing in.
WAKE_CAUGHT_STAMP = "THE WAKE HAS YOU"
WAKE_CAUGHT_TOAST = "THE WAKE HAS TAKEN THIS SECTOR: JUMP ON, OR MEET IT HERE"

#: Seconds of scooped motes one "+N SCRAP" label speaks for. A scoop pass over
#: a kill's confetti is one pickup to the player and a dozen to the sector, so
#: the labels merge inside this window rather than stacking.
SCRAP_TOAST_WINDOW_S = 0.6

#: The label floated when a whole box's worth of scooped rounds is stowed.
AMMO_BOX_FLOAT = "+1 AMMO BOX ({name})"

#: Signature past this fraction of the lock threshold makes a death with an
#: affordable exit an "overstayed" story on the ledger. Below it the meter was
#: never the bet that lost, so the recap tells the combat story instead.
RECAP_OVERSTAY_SIGNATURE_FRACTION = 0.5

#: Seconds a hit stays attributable: past this, a death is not that hit's fault.
KILLER_ATTRIBUTION_WINDOW_S = 3.0
#: How closely an enemy has to sit on the bearing of the last hit taken before
#: the ledger will name it. About 57 degrees either side of the bearing, which
#: is wide enough for a mover and narrow enough to never name the wrong side.
KILLER_BEARING_COS = 0.55
#: How close an enemy has to be, in world units, to be named for a killing blow
#: no earlier hit set a bearing for. Inside this it was on top of the hull.
KILLER_NEAR_UNITS = 25.0
#: What the ledger calls a killer it could not name.
KILLER_UNKNOWN = "enemy_fire"

#: How long the world keeps running after the hull reaches zero, before the
#: ledger replaces it. A run settled inside ``Ship.apply_damage``, on the same
#: frame the blow landed, would never show a pilot killed by the Shrike's
#: lantern the burn: the last frame of the game would be the pink pre-burn cone
#: and the next one a table of numbers. Long enough to read the blow that did
#: it, short enough that nobody sits waiting for a screen they have earned.
DEATH_SETTLE_S = 0.6

#: Headlines for the deaths that are not a named archetype. Everything else is
#: "DESTROYED BY <NAME>": the pilot must always leave knowing what did it.
DEATH_HEADLINES: dict[str, str] = {
    "suffocation": "LIFE SUPPORT EXHAUSTED",
    "hunter": "THE SHRIKE TOOK YOU",
    LANTERN_BLOW_ID: "THE SHRIKE'S LANTERN BURNED YOU",
    "abandoned": "RUN ABANDONED",
    KILLER_UNKNOWN: "DESTROYED BY ENEMY FIRE",
}
#: The ledger's headline and recap type, in pixels. The headline is the first
#: thing read and the recap the second, so neither is a menu row.
LEDGER_HEADLINE_FONT_PX = 40.0
LEDGER_RECAP_FONT_PX = 18.0
#: The standard panel title size, which the ledger's headline overrides.
MENU_TITLE_FONT_PX = 24.0

# ============================================================================
# The doctrine screen
#
# Sixty nodes in five branches of twelve, drawn as a tree. A grid of five
# columns of twelve labels stacked in reading order is a page of buttons
# rather than a map, and it hides the one thing the tree is for. The
# branch shape is a spine and a shoulder, the spine being the cheap route to a
# keystone, and nothing on a grid says so, because a grid cannot draw the line
# between a node and the node that unlocks it.
#
# So the branches are drawn as they are shaped: a lane per fork, a row per
# tier, and a connector between every node and its prerequisite. Depth down the
# screen is depth into the branch, and a locked node is locked by something the
# eye can follow back up the line.
# ============================================================================

DOCTRINE_CELL_FONT_PX = 10.0
DOCTRINE_DETAIL_FONT_PX = 13.0
#: One node on the tree, and the gaps that make the shape readable: between the
#: two lanes of one branch, between branches, and between tiers.
DOCTRINE_NODE_WIDTH_PX = 140.0
#: A node is two lines of type tall (see DOCTRINE_CELL_LINES). The plate is
#: deliberately taller than the two lines need, because a caption laid tight
#: against the plate's own edge loses its bottom pixels to the plate's border
#: ring, because a repainted panel draws over a later sibling label.
DOCTRINE_NODE_HEIGHT_PX = 38.0
DOCTRINE_LANE_GAP_PX = 6.0
#: The two gaps below are what the tree spends to buy the type its captions are
#: really drawn at. The engine will not draw text below
#: :data:`DOCTRINE_CELL_MIN_FONT_PX`, so the drawn scale a node needs before a
#: priced line fits between its borders is fixed rather than negotiable, and
#: reaching it inside a 1280x720 window meant giving the gaps back to the
#: nodes. Both are still wider than a connector, which is all either of them
#: has to carry, and the branch gap stays the larger of the two so five
#: branches still read as five.
DOCTRINE_BRANCH_GAP_PX = 20.0
DOCTRINE_TIER_GAP_PX = 7.0
#: Clear space inside a node's plate, either side of its line of type. Kept
#: small on purpose: ten lanes of nodes across a 1280-pixel window leave a node
#: a little over a hundred drawn pixels of type at the one size the renderer
#: will honour, and every pixel of padding is a character of the title.
DOCTRINE_NODE_PAD_PX = 3.0
#: The branch heading strip above the first tier, and how much louder than a
#: cell its type is. The multiplier is applied to the size the cells are really
#: drawn at, so the heading stays the larger of the two at every draw scale
#: instead of both landing on the renderer's own floor.
DOCTRINE_HEADING_HEIGHT_PX = 22.0
DOCTRINE_HEADING_FONT_MULT = 1.1
#: Connector thickness, and the ring drawn round a node.
DOCTRINE_LINK_WIDTH_PX = 2.0
DOCTRINE_BORDER_PX = 2.0
#: A cell's caption is two lines, not one. A node holds a couple of dozen
#: characters at the one size the renderer will draw, and a title with its
#: price beside it is longer than that often enough that a single line spent a
#: third of the branch on "Ammunition Sov... 40": the vocabulary the tree is
#: read for was the part being thrown away. The plate has the height for two
#: lines, so the title wraps onto the second and the cost rides with it, and
#: only a title too long for both is cut at all. Both lines live in one label,
#: because ``Label`` stacks an embedded newline on a 1.2 pitch and centres the
#: block in its rect: two controls would have to be kept vertically in step
#: with the plate at every draw scale, and any drift between them hangs the
#: second line over the plate's bottom border. Characters the state marks and
#: their space take off the first line, which the second line is normally
#: indented by to sit under the title rather than under the mark. Normally,
#: because that indent is the first thing to give way when the second line is
#: full: see :func:`_cell_indent`.
DOCTRINE_CELL_MARK_CHARS = 3
#: The smallest type the renderer will actually put on the glass. Below it the
#: draw call raises the size it draws at, so a caption laid out at anything
#: under this floor is painted a quarter wider than the rect it was placed in:
#: a cell budgeted at ten points times the draw scale, about seven and a half,
#: would draw "Sovereignty 40 Cores" straight out through the plate's own
#: border while the layout believed it had room to spare. Every measurement of
#: a cell is taken at this size, and every cell is drawn at it, so the two
#: cannot disagree.
DOCTRINE_CELL_MIN_FONT_PX = 10.0
#: The widest caption budget a cell is ever asked to hold, in characters. The
#: budget itself is measured rather than assumed (:meth:`DoctrineScene.cell_chars`);
#: this is only where the search for it starts, set well past the longest
#: priced caption the tree can produce so that a wide window is answered by the
#: type rather than clipped by this ceiling.
DOCTRINE_CELL_CHARS_MAX = 40
#: Vertical room the caption is given beyond its plate, centred on it. A label
#: is drawn inside the bounds it was placed at, and two lines of the smallest
#: type the engine will draw come to more than a node's plate at the smallest
#: scale the tree is drawn at: without the overhang the second line would lose
#: its bottom third to the plate's own edge, the same truncation the two-line
#: caption exists to end.
DOCTRINE_CELL_ROOM_PX = 12.0
#: The smallest the tree is ever drawn at. Below this the panel stops shrinking
#: the drawing and starts panning it under the cursor instead: a tree fitted
#: into a 500-pixel window by scale alone is a diagram nobody can read, and the
#: point of drawing it as a tree is that it can be read. The floor is set by
#: the type rather than by taste: a cell drawn smaller than this cannot hold a
#: priced line between its own borders at :data:`DOCTRINE_CELL_MIN_FONT_PX`,
#: which is the one size the renderer will honour, so below it the tree would
#: be shrinking the plates around type that is not shrinking with them.
DOCTRINE_MIN_DRAW_SCALE = 0.80

#: Bought, out of reach, and the two states between. Every one of them also
#: carries a text mark, so the state survives a greyscale screenshot and a
#: player who cannot separate those colours.
DOCTRINE_OWNED_COLOUR = (0.56, 0.94, 0.62, 1.0)
DOCTRINE_BLOCKED_COLOUR = (0.42, 0.46, 0.55, 1.0)
DOCTRINE_COSTLY_COLOUR = (0.78, 0.70, 0.50, 1.0)
DOCTRINE_KEYSTONE_COLOUR = (0.88, 0.70, 1.00, 1.0)
#: The node plates, by state, and the ring the cursor draws round one.
DOCTRINE_NODE_OWNED_FILL = (0.09, 0.22, 0.15, 1.0)
DOCTRINE_NODE_OPEN_FILL = (0.10, 0.13, 0.18, 1.0)
DOCTRINE_NODE_LOCKED_FILL = (0.05, 0.06, 0.08, 1.0)
DOCTRINE_NODE_EDGE_COLOUR = (0.28, 0.34, 0.44, 1.0)
DOCTRINE_CURSOR_COLOUR = (1.00, 0.86, 0.42, 1.0)
#: A connector, and a connector whose upper end is already bought: the lit line
#: is the route the Cores have actually opened.
DOCTRINE_LINK_COLOUR = (0.20, 0.25, 0.32, 1.0)
DOCTRINE_LINK_LIT_COLOUR = (0.34, 0.66, 0.46, 1.0)

#: The marks every cell carries. The cursor mark and one state mark, so the
#: four states are told apart without colour: bought, buyable now, priced out
#: of the purse, and locked behind a prerequisite further up the branch.
DOCTRINE_MARK_CURSOR = ">"
DOCTRINE_MARK_OWNED = "*"
DOCTRINE_MARK_BUYABLE = "+"
DOCTRINE_MARK_COSTLY = "$"
DOCTRINE_MARK_LOCKED = "-"
DOCTRINE_LEGEND_LINE = f"{DOCTRINE_MARK_OWNED} OWNED   {DOCTRINE_MARK_BUYABLE} BUY NOW   "
DOCTRINE_LEGEND_LINE += f"{DOCTRINE_MARK_COSTLY} COSTS MORE THAN YOU HAVE   {DOCTRINE_MARK_LOCKED} LOCKED"
#: The four states, spelled once each way: the mark, the type colour and the
#: plate under it. Three channels rather than one, because the difference
#: between "not yet affordable" and "locked further up the branch" is the
#: difference between saving and buying something else first.
DOCTRINE_STATE_OWNED_ID = "owned"
DOCTRINE_STATE_BUYABLE_ID = "buyable"
DOCTRINE_STATE_COSTLY_ID = "costly"
DOCTRINE_STATE_LOCKED_ID = "locked"
DOCTRINE_STATE_MARKS: dict[str, str] = {
    DOCTRINE_STATE_OWNED_ID: DOCTRINE_MARK_OWNED,
    DOCTRINE_STATE_BUYABLE_ID: DOCTRINE_MARK_BUYABLE,
    DOCTRINE_STATE_COSTLY_ID: DOCTRINE_MARK_COSTLY,
    DOCTRINE_STATE_LOCKED_ID: DOCTRINE_MARK_LOCKED,
}
DOCTRINE_STATE_COLOURS: dict[str, tuple[float, float, float, float]] = {
    DOCTRINE_STATE_OWNED_ID: DOCTRINE_OWNED_COLOUR,
    DOCTRINE_STATE_BUYABLE_ID: MENU_TEXT_COLOUR,
    DOCTRINE_STATE_COSTLY_ID: DOCTRINE_COSTLY_COLOUR,
    DOCTRINE_STATE_LOCKED_ID: DOCTRINE_BLOCKED_COLOUR,
}
DOCTRINE_STATE_FILLS: dict[str, tuple[float, float, float, float]] = {
    DOCTRINE_STATE_OWNED_ID: DOCTRINE_NODE_OWNED_FILL,
    DOCTRINE_STATE_BUYABLE_ID: DOCTRINE_NODE_OPEN_FILL,
    DOCTRINE_STATE_COSTLY_ID: DOCTRINE_NODE_OPEN_FILL,
    DOCTRINE_STATE_LOCKED_ID: DOCTRINE_NODE_LOCKED_FILL,
}
#: The detail block's prerequisite line, which is the answer to the question a
#: locked node raises and a plain grid of labels cannot answer.
DOCTRINE_REQUIRES_LINE = "REQUIRES: {names}"
DOCTRINE_REQUIRES_NONE = "NO PREREQUISITE: THE BRANCH OPENS HERE"
#: Said only while the drawing is bigger than the window it is drawn in.
DOCTRINE_PAN_NOTE = "THE TREE IS WIDER THAN THIS WINDOW: THE VIEW FOLLOWS THE CURSOR"

#: The three rows under the grid, and the two doors onto the screen.
DOCTRINE_ACTION_BUY = "BUY THE SELECTED NODE"
DOCTRINE_ACTION_RESPEC = "FREE RESPEC: REFUND THE WHOLE TREE"
DOCTRINE_ACTION_BACK = "BACK"
DOCTRINE_MENU_ENTRY = "FLEET DOCTRINE ({cores} Cores)"
#: Front-door rows, by the prefix a returning screen names them with. The
#: doctrine row carries a live Cores count, so it is named by its prefix.
MENU_ENTRY_SETTINGS = "SETTINGS"
MENU_ENTRY_DOCTRINE = "FLEET DOCTRINE"
MENU_ENTRY_RESUME = "RESUME RUN"
MENU_ENTRY_NEW_RUN = "NEW RUN"
LEDGER_DOCTRINE_ENTRY = "SPEND YOUR CORES: FLEET DOCTRINE"
#: The price a node's cell prints, as one token. The digits and their unit
#: travel together or not at all: a cell that shed the unit to make room would
#: read "Sovereignty 40" under a column of siblings reading "NN Cores", which
#: is a stat, not a price.
DOCTRINE_CELL_COST = "{cost} Cores"
#: The doctrine screen's own lines: what a node is worth, and what just happened.
DOCTRINE_STATE_OWNED = "OWNED"
DOCTRINE_STATE_BUYABLE = "F: BUY FOR {cost} CORES"
#: The state line for a node whose only blocker is an unowned prerequisite.
#: The REQUIRES line right below already names what is missing, so echoing the
#: blocker there would print the same fact twice and cost the pane the one thing
#: the prerequisite line cannot say: the price against the purse.
DOCTRINE_STATE_PRICED = "COSTS {cost} CORES, YOU HAVE {cores}"
DOCTRINE_BOUGHT = "BOUGHT {title} FOR {cost} CORES"
DOCTRINE_RESPEC_DONE = "TREE REFUNDED: {refund} CORES BACK IN THE PURSE"
DOCTRINE_RESPEC_EMPTY = "NOTHING BOUGHT YET: THE PURSE IS ALREADY WHOLE"
DOCTRINE_SUBTITLE = "{cores} Cores unspent, {spent} spent, keystones {active}/{max_active} armed of {owned} bought"
#: Where Cores come from, printed on both screens that show a Core balance.
#:
#: A player can reach the tree with nothing to spend and be told the cheapest
#: node costs fifteen, so the game has to name every source of Cores somewhere.
#: Every number here is read off ``balance``'s conversion rates
#: rather than written out, so a rebalance moves the sentence with it: scrap
#: banked at a post, scrap run through a Refinery in flight, scrap carried out
#: through the Deep Gate, and the fraction of a hold a death still pays. All
#: four are the rates ``settle_conversion``, :mod:`shrike.trading` and
#: :mod:`shrike.modules` actually charge. The milestone bounties are the one
#: source that is not a conversion, so they are named rather than priced.
#: The standard menu label draws at fourteen pixels, which is what these wrap at.
MENU_LINE_FONT_PX = 14.0
CORES_SOURCE_LINE = (
    "Cores are banked scrap: sell the hold at a depot ({post:.1f} Cores per {unit:.0f} scrap), "
    "run a Refinery in flight ({refinery:.1f}, and it is loud), carry it out through the "
    "Deep Gate ({gate:.1f}), or die holding it and keep {death:.1f}. "
    "First-time milestones pay a bounty on top."
)

# ============================================================================
# The dock screen
#
# What the bay sells, what it pays for a hold, and the way out. It is an
# overlay inside the run rather than a scene, for the same reason the pause
# menu is: undocking has to put the pilot back exactly where they docked.
# ============================================================================

#: A shelf row is the widest line in the game: a mark, a name, a category, a
#: price, the fit the depot folded in, the mechanical summary and a state
#: mark, all on one line. The row is cut to :data:`DEPOT_ROW_CHARS` so it can
#: never run out through both sides of its own button, which is what the
#: longest module row would otherwise do.
DEPOT_ROW_WIDTH_PX = 1100.0
DEPOT_ROW_HEIGHT_PX = 22.0
DEPOT_ROW_FONT_PX = 13.0
DEPOT_ROW_CHARS = int(DEPOT_ROW_WIDTH_PX / (DEPOT_ROW_FONT_PX * MENU_GLYPH_ADVANCE_FRACTION))
DEPOT_ROW_ELLIPSIS = "..."

#: The shelf itself is a grid of cards rather than a stack of sentences. A row
#: that carries a name, a category, a price, a fit, a mechanical summary and a
#: state mark on one line is a line nobody reads to the end of: the price sits
#: in the middle of it and the reason a thing cannot be bought sits at the far
#: right, past a hundred characters of prose. A card puts the three questions
#: on three lines (what is it and what does it cost, what does it do, and can I
#: have it) and two of them fit side by side.
DEPOT_GRID_COLUMNS = 2
DEPOT_CARD_GAP_PX = 12.0
DEPOT_CARD_PAD_PX = 6.0
DEPOT_CARD_LINE_PX = 17.0
DEPOT_CARD_LINES = 3
DEPOT_CARD_HEIGHT_PX = DEPOT_CARD_LINES * DEPOT_CARD_LINE_PX + 2.0 * DEPOT_CARD_PAD_PX
DEPOT_CARD_BORDER_PX = 2.0
DEPOT_CARD_HEAD_FONT_PX = 13.0
DEPOT_CARD_BODY_FONT_PX = 12.0
#: The plate the whole shop stands on, which the shelf needs and the other
#: screens do not. :data:`MENU_PANEL` is a shade of blue-grey at ninety-six
#: percent, which is right over a menu nebula and wrong over a docking bay: the
#: barge is a lit object a few metres away, so the four percent would come
#: through as a drum and a mooring ring drawn across the cards, and the cards
#: would be a slightly different blue-grey on top of it. The bay gets its own
#: plate, opaque and nearly black, so a card is the brightest thing on the
#: screen rather than one of three greys competing.
DEPOT_PANEL_FILL = (0.014, 0.020, 0.030, 1.0)
#: The card plates. A card the hold cannot pay for is drawn on a darker plate
#: in a dimmer type *and* says how short it is: the grey alone would only tell
#: a player who already knew the shelf greys what it cannot sell.
DEPOT_CARD_FILL = (0.10, 0.14, 0.20, 1.0)
DEPOT_CARD_SHORT_FILL = (0.04, 0.05, 0.07, 1.0)
DEPOT_CARD_SOLD_FILL = (0.05, 0.11, 0.08, 1.0)
DEPOT_CARD_EDGE_COLOUR = (0.36, 0.44, 0.56, 1.0)
DEPOT_CARD_FOCUS_COLOUR = (1.00, 0.86, 0.42, 1.0)
DEPOT_CARD_BUY_COLOUR = (0.72, 0.92, 0.78, 1.0)
DEPOT_CARD_SHORT_COLOUR = (0.94, 0.66, 0.54, 1.0)
DEPOT_CARD_SOLD_COLOUR = (0.56, 0.80, 0.62, 1.0)
#: The card's middle line. Not :data:`MENU_DIM_COLOUR`, the shade the footers
#: and the FIT block are written in, which would put the one line saying what
#: a thing *does* in the quietest type on the screen.
DEPOT_CARD_BODY_COLOUR = (0.78, 0.84, 0.93, 1.0)
#: The card's three lines. The head carries the mark, the name, the price and
#: the category; the body is the mechanical effect; the foot is the answer to
#: "can I buy this", which is a verb, a shortfall or a refusal, never blank.
DEPOT_CARD_HEAD = "{mark}{flag}{name}   {price:.0f} SCRAP   [{category}]"
DEPOT_CARD_BUY = "F: BUY FOR {price:.0f} SCRAP"
DEPOT_CARD_SOLD = "SOLD, ALREADY ABOARD"
DEPOT_CARD_SHORT = "NEED {short:.0f} MORE SCRAP"
#: The one line under the grid: everything the focused card had to cut.
DEPOT_DETAIL_PREFIX = "SELECTED: "
#: The shortest window that prints the FIT panel under the shelf. Below it the
#: shelf and the fit block together cannot both be readable, and the shelf is
#: the half that spends scrap; the pause overlay mirrors the fit either way.
DEPOT_FIT_PANEL_MIN_WINDOW_PX = 600.0
DEPOT_FIT_ELSEWHERE = "FIT: ESC SHOWS WHAT IS BOLTED WHERE"
DEPOT_TITLE = "DRIFT DEPOT"
BROKER_TITLE = "BROKER BARGE"
#: The bay's own legend. The shelf is a grid, so it has a second axis and
#: needs a line that says so.
DEPOT_CONTROLS_LINE = "MOVE: W/S OR ARROWS   ROW: A/D   BUY: F, ENTER OR CLICK   SELL: HOLD F   LEAVE: ESC"
DEPOT_HOLD_SUBTITLE = "{scrap:.0f} scrap in the hold"
DEPOT_SELL_ROW = "SELL THE HOLD: {scrap:.0f} scrap for {cores:.1f} Cores at rate {rate:.1f} (or hold F)"
DEPOT_SELL_EMPTY_ROW = "SELL THE HOLD: nothing aboard to sell"
#: The door onto the refit panel. It carries the locker count because that is
#: what a pilot is deciding on: a bay with nothing stowed still refits (a gun
#: can come off), but a bay with three things waiting is a bay worth opening.
DEPOT_REFIT_ROW = "REFIT THE HULL: mount guns and modules ({stowed} stowed)"
#: The same row once a purchase has actually put something in the locker. A
#: gun that is bought and stowed does nothing at all until it is mounted, and
#: the bay is the only place it can be, so the door onto the refit panel says
#: so in its own label rather than leaving the news on a status line that the
#: next press will overwrite.
DEPOT_REFIT_ROW_WAITING = "REFIT THE HULL: {stowed} IN THE LOCKER WAITING FOR A MOUNT, FIT THEM HERE"
DEPOT_REROLL_ROW = "REROLL THE SHELF: {price} scrap"
DEPOT_UNDOCK_ROW = "UNDOCK AND FLY ON"
#: The shelf's per-row state marks.
DEPOT_MARK_SOLD = "SOLD"
DEPOT_MARK_SHORT = "NEED {short:.0f} MORE"
#: The canister's flag, the subtitle's warning, and what the bay says when the
#: air is short and this visit's ration is already spent. A shelf without a
#: canister on it at all is not a state the game can reach: air and fuel
#: are ``trading.GUARANTEED_CONSUMABLES`` and every bay carries both.
DEPOT_O2_ITEM_ID = "o2_canister"
DEPOT_MARK_AIR = "AIR"
DEPOT_LOW_AIR_SUBTITLE = "AIR LOW, {seconds:.0f} seconds left"
DEPOT_NO_CANISTER = "this visit's canister is spent; ice fields refill"
#: The same three for the other clock. A tank is read in jumps rather than in
#: units, because the number a pilot is deciding with is how many more times
#: the drive will fire, and the jump price is the one the chart is quoting.
DEPOT_FUEL_ITEM_ID = "fuel_cell"
DEPOT_MARK_FUEL = "FUEL"
DEPOT_LOW_FUEL_SUBTITLE = "FUEL LOW, {jumps:.0f} jumps left"
DEPOT_NO_FUEL_CELL = "this visit's cells are spent"
#: Jumps left in the tank at or under which the bay says so. One is a bay you
#: must buy at; two is a bay you should.
DEPOT_LOW_FUEL_JUMPS = 2.0
#: What a refused action says on the screen's own status line.
DEPOT_REROLL_REFUSED = "NOT ENOUGH SCRAP TO REROLL"
DEPOT_BUY_SHORT = "NOT ENOUGH SCRAP FOR THE {name}"
DEPOT_BUY_SOLD = "THE {name} IS ALREADY SOLD"
DEPOT_BUY_DONE = "BOUGHT THE {name} FOR {price:.0f} SCRAP"
#: What a purchase says once it has landed. A receipt that only names the price
#: leaves the pilot to go and look for what changed; these name the change
#: itself, read off the hull before and after the payment, so a gun that went
#: straight onto a bare hardpoint and a gun that went into the locker are two
#: different sentences rather than the same one.
DEPOT_BUY_MOUNTED = "BOUGHT THE {name} FOR {price:.0f} SCRAP: MOUNTED ON HARDPOINT {hardpoint}"
DEPOT_BUY_INSTALLED = "BOUGHT THE {name} FOR {price:.0f} SCRAP: INSTALLED IN THE {slot}"
DEPOT_BUY_STOWED = "BOUGHT THE {name} FOR {price:.0f} SCRAP: IN THE LOCKER, MOUNT IT AT REFIT THE HULL"
DEPOT_BUY_APPLIED = "BOUGHT THE {name} FOR {price:.0f} SCRAP: {effect}"
DEPOT_SOLD_HOLD = "SOLD THE HOLD FOR {cores:.1f} CORES"
DEPOT_SOLD_NOTHING = "THE HOLD IS EMPTY"
DEPOT_REROLLED = "FRESH SHELF, NEXT REROLL {price} SCRAP"
#: What a committed mount reports. Written here rather than on the panel that
#: shows it, because the depot's own ``swap_weapon`` is the other way a gun
#: reaches a hardpoint and both have to report themselves in the same words.
DEPOT_SWAP_DONE = "MOUNTED THE {name} ON HARDPOINT {hardpoint}"
DEPOT_SWAP_DONE_DISPLACED = "MOUNTED THE {name} ON HARDPOINT {hardpoint}, {displaced} STOWED"

#: The Doctrine Kits: the free pick the first dock of a profile prints above
#: its shelf, one of three. The choice is the run's first
#: build fork; it is taken exactly once per profile and delivery rides the same
#: paths a paid purchase takes, so a kit part obeys every fitting rule.
KIT_SOLAR = "solar"
KIT_FORGE = "forge"
KIT_ARSENAL = "arsenal"
#: The contents table is balance data (``balance.KIT_CONTENTS``); this module
#: owns only the delivery and the wording.
KIT_CONTENTS: dict[str, tuple[str, ...]] = dict(balance.KIT_CONTENTS)
#: Boxes riding with the Arsenal Kit's cannon, keyed to it in the locker even
#: while the cannon waits stowed for a refit.
KIT_ARSENAL_AMMO_BOXES = balance.KIT_ARSENAL_FLAK_ROUNDS // balance.AMMO_BOX_ROUNDS
KIT_NAMES: dict[str, str] = {KIT_SOLAR: "SOLAR KIT", KIT_FORGE: "FORGE KIT", KIT_ARSENAL: "ARSENAL KIT"}
#: What one kit contains. Written as a list of parts and never as a choice
#: between them: a row reading "FREE, PICK ONE: solar wings <> signature
#: dampener" invites a pilot to read the separator as the fork rather than the
#: three rows above it. A kit is one free box with everything in it; the pick
#: is which box.
KIT_EFFECTS: dict[str, str] = {
    KIT_SOLAR: "solar wings AND a signature dampener",
    KIT_FORGE: "a generator AND a sentry turret",
    KIT_ARSENAL: f"a flak cannon AND {balance.KIT_ARSENAL_FLAK_ROUNDS} rounds for it",
}
KIT_ROW = "{name} [doctrine kit] FREE, ONE KIT OF THE THREE, BOTH PARTS: {effects}"
KIT_TAKEN = "{name} ABOARD: {effects}. THE DOCTRINE PICK IS MADE"


# ============================================================================
# The refit panel
#
# Where a fit is changed. A block of sentences under the shelf, one row per
# stowed weapon per hardpoint, reads as a cursor moving over prose rather than
# as a ship: nothing on it says where hardpoint 2 is, a socket cannot be
# reached at all, and eight rows say the same four words.
#
# This is the hull drawn as a hull. The mounts are boxes where they really sit
# on the plan, each carrying what is bolted to it; the locker is a column beside
# it; and the two are joined by picking one of each. Every geometry number here
# is in hull units (the same frame the sockets and hardpoints are laid out in)
# or a fraction of the panel, so one scale factor fits the whole screen to the
# window and nothing has to be re-authored for a small one.
# ============================================================================

#: The size the panel is authored at, and the floor it may be shrunk to. Both
#: axes are fitted by the same factor, because the schematic is a drawing: a
#: hull squashed on one axis is a different ship.
REFIT_BASE_WIDTH_PX = 1180.0
REFIT_BASE_HEIGHT_PX = 660.0
REFIT_MIN_SCALE = 0.5
#: Panel padding, the gap between the two columns, and the type, at full scale.
REFIT_PAD_PX = 16.0
REFIT_GAP_PX = 18.0
REFIT_TITLE_FONT_PX = 22.0
REFIT_ROW_FONT_PX = 14.0
REFIT_SLOT_FONT_PX = 12.0
REFIT_LINE_HEIGHT_PX = 26.0
#: The smallest type the engine will draw: a label asked for less is silently
#: given this, so a character budget worked out from the smaller number would
#: promise room the text does not have. Everything here is fitted to this floor
#: rather than to what the scale asked for.
REFIT_MIN_FONT_PX = 8.0
#: How much of the body the schematic takes; the locker column takes the rest.
REFIT_DIAGRAM_FRACTION = 0.56
#: A mount's box on the plan, and the ring drawn round the focused one.
REFIT_MARKER_PX = 15.0
REFIT_BORDER_PX = 2.0
#: Hull units of clear space either side of the drawing, for the mount labels.
#: The schematic is scaled to fit its box *including* this, so a label can be
#: cut to the room it has rather than run out through the side of the panel.
REFIT_LABEL_ROOM_UNITS = 1.9
#: A mount within this of the centreline is drawn as a bow or stern mount, with
#: its label above or below rather than out to one side.
REFIT_CENTRELINE_UNITS = 0.25

#: The hull, as centred boxes in hull units: ``(x, z, width, depth)``. Nose
#: along -Z, starboard along +X, the same frame ``modules.Socket.offset`` and
#: ``weapons.HARDPOINT_OFFSETS`` are written in, so the mounts land on the
#: drawing without a second convention to keep in step.
REFIT_HULL_SHAPES: tuple[tuple[float, float, float, float], ...] = (
    (0.0, -1.35, 0.60, 1.20),
    (0.0, 0.00, 1.15, 3.10),
    (0.0, 1.45, 1.70, 0.90),
    (-1.25, -0.10, 1.10, 1.45),
    (1.25, -0.10, 1.10, 1.45),
)

#: The look. The hull is a plate under the mounts, so a mount reads as a thing
#: bolted on rather than as a box floating in the dark.
REFIT_HULL_COLOUR = (0.13, 0.17, 0.23, 1.0)
REFIT_HULL_EDGE_COLOUR = (0.28, 0.36, 0.46, 1.0)
REFIT_SLOT_BARE_COLOUR = (0.10, 0.13, 0.18, 1.0)
REFIT_SLOT_FILLED_COLOUR = (0.30, 0.45, 0.40, 1.0)
REFIT_SLOT_EDGE_COLOUR = (0.45, 0.52, 0.62, 1.0)
REFIT_ROW_COLOUR = (0.09, 0.12, 0.16, 1.0)
#: The focus ring and the armed pick. Two colours *and* two text marks, so the
#: state survives a greyscale screenshot and a player who cannot separate them.
REFIT_FOCUS_COLOUR = (1.00, 0.86, 0.42, 1.0)
REFIT_ARMED_COLOUR = (0.45, 0.90, 0.70, 1.0)
REFIT_MARK_ARMED = "*"
REFIT_REFUSED_COLOUR = (0.90, 0.55, 0.45, 1.0)

REFIT_TITLE = "REFIT BAY"
REFIT_SUBTITLE = "PICK A MOUNT, THEN PICK WHAT GOES ON IT"
#: How a mount is named in a sentence. The socket keeps the hull's own word for
#: it ("PORT QUARTER SOCKET"), which is the word the shelf already promises a
#: purchase to, so a row and a mount cannot be read as two different places.
REFIT_HARDPOINT_LABEL = "HARDPOINT {index}"
REFIT_SOCKET_LABEL = "{label} SOCKET"
REFIT_HULL_HEADING = "THE HULL"
REFIT_LOCKER_HEADING = "IN THE LOCKER"
REFIT_LOCKER_EMPTY = "NOTHING STOWED: UNMOUNT SOMETHING, OR BUY IT ON THE SHELF"
REFIT_CONTROLS_LINE = "MOVE: W/S OR ARROWS   HULL/LOCKER: A/D   CHOOSE: F, ENTER OR CLICK   BACK: ESC"
#: The locker column's rows, and the two action rows under everything.
REFIT_LOCKER_ROW = "{name} [{kind}] {summary}"
REFIT_ACTION_UNMOUNT = "UNMOUNT THE PICKED MOUNT"
REFIT_ACTION_DONE = "DONE: BACK TO THE SHELF"
REFIT_ACTIONS_ELLIPSIS = "..."
#: What the panel says once a press has actually moved something. The mounting
#: lines are the depot's, so a refit made here and a refit made from a script
#: report themselves identically.
REFIT_INSTALL_DONE = "INSTALLED THE {name} IN THE {slot}"
REFIT_INSTALL_DISPLACED = "INSTALLED THE {name} IN THE {slot}, {displaced} STOWED"
REFIT_UNMOUNT_DONE = "{name} OFF {slot} AND INTO THE LOCKER"
REFIT_UNMOUNT_BARE = "{slot} IS ALREADY BARE"
REFIT_UNMOUNT_NOTHING = "PICK A MOUNT FIRST: THE UNMOUNT ROW STRIPS IT"
REFIT_REFUSED = "THE BAY CANNOT MAKE THAT REFIT"


# ============================================================================
# Settings: accessibility, remapping and the Steady Wake panel
# ============================================================================

#: The chart action, and the pause action split out of it.
#:
#: Escape and M are two actions. Bound together, the key every other game
#: uses to back out of something would be a sector jump taken with no
#: confirmation and no way back. ``runtime.INPUT_ACTIONS`` carries the
#: split: Escape (Start on the pad) raises the pause overlay, M (Back) opens
#: the chart. These names are how this module refers to the two halves.
CHART_ACTION = "star_chart"
PAUSE_ACTION = "pause_menu"


#: Menu navigation, on the keys a player reaches for without being told.
#:
#: The thrust actions move a menu cursor and ``interact`` commits, which is
#: what the pad wants and what the run's own keys are; nobody arriving at a
#: title screen guesses either. These three actions carry the arrows, Enter and
#: the d-pad alongside them; the bindings live in ``runtime.INPUT_ACTIONS``
#: with every other action, these names are how this module refers to them.
MENU_UP_ACTION = "menu_up"
MENU_DOWN_ACTION = "menu_down"
MENU_CONFIRM_ACTION = "menu_confirm"


def base_input_actions() -> dict[str, list]:
    """A fresh copy of ``runtime.INPUT_ACTIONS``, safe for remapping to edit."""
    return {name: list(bindings) for name, bindings in runtime.INPUT_ACTIONS.items()}


#: Actions the remapping screen offers. The stick and trigger axes are not on
#: it: they are bound to the pad's geometry, not to a choice.
REMAPPABLE_ACTIONS: tuple[str, ...] = (
    "thrust_up",
    "thrust_down",
    "thrust_left",
    "thrust_right",
    "fire_primary",
    "mining_beam",
    "shield_left",
    "shield_right",
    "afterburner",
    "silent_running",
    "solar_wings",
    "generator",
    "interact",
    "jettison_scrap",
    "warp_spool",
    "tractor_scoop",
    CHART_ACTION,
    PAUSE_ACTION,
    CONTROLS_BAR_ACTION,
)

#: Actions that may be held or toggled, under the accessibility settings.
HOLD_OR_TOGGLE_ACTIONS: tuple[str, ...] = ("fire_primary", "shield_left", "silent_running")


def encode_binding(binding) -> str | None:
    """A binding as a profile-safe token, or None when it does not encode.

    Axis bindings (:class:`InputBinding`) describe pad geometry rather than a
    choice, so they are not encoded; :func:`resolve_input_actions` keeps them
    from the defaults instead of losing them.
    """
    if isinstance(binding, DeviceButton) and binding in Key and binding.name is not None:
        return f"Key.{binding.name.upper()}"
    if isinstance(binding, DeviceButton):
        return f"Button.{binding}"
    return None


def decode_binding(token: str):
    """The binding a :func:`encode_binding` token names.

    Raises ``ValueError`` on anything it does not recognise: a settings file
    that has drifted should say so, not silently unbind a control.
    """
    kind, _, member = str(token).partition(".")
    if kind == "Button" and member:
        return DeviceButton.parse(member)
    if kind == "Key" and member:
        key = getattr(Key, member, None)
        if not isinstance(key, DeviceButton):
            raise ValueError(f"Key has no member {member!r}")
        return key
    raise ValueError(f"Unknown binding token {token!r}")


@dataclass
class Settings:
    """Everything the options screens own, as one persisted record.

    The three sliders are 0 to 1 multipliers; ``damage_taken`` is one of
    ``balance.ASSIST_DAMAGE_TAKEN_STEPS``. ``bindings`` maps an action to the
    keyboard or mouse bindings that replace its defaults; anything absent keeps
    ``runtime.INPUT_ACTIONS``.
    """

    # Accessibility
    shake: float = 1.0
    flash: float = 1.0
    hit_stop: float = 1.0
    ui_scale: float = UI_SCALE_MIN
    # The mix, as fractions of full scale
    volume_master: float = VOLUME_DEFAULT
    volume_sfx: float = VOLUME_DEFAULT
    volume_music: float = VOLUME_DEFAULT
    photosensitive: bool = False
    aim_assist: bool = True
    #: The persistent controls bar along the bottom of the HUD. On by default,
    #: for every run and every profile: the onboarding lessons stop after run
    #: three and never come back, and the keys still have to be somewhere.
    controls_bar: bool = True
    hold_actions: dict[str, bool] = field(default_factory=lambda: dict.fromkeys(HOLD_OR_TOGGLE_ACTIONS, True))
    bindings: dict[str, list[str]] = field(default_factory=dict)

    # Display. The cap is applied at boot (main.resolve_frame_cap on desktop,
    # the front door in the browser) and live from the settings screen; vsync
    # is live too, through App.set_vsync.
    frame_cap: int = 0
    vsync: bool = True

    # The Steady Wake assist panel
    slow_signature: bool = False
    damage_taken: float = 1.0
    slow_lantern: bool = False
    spool_immunity: bool = False

    # -- assists -----------------------------------------------------------

    def assist_settings(self) -> balance.AssistSettings:
        """The panel as the record ship.py and hunter.py already read."""
        return balance.AssistSettings(
            slow_signature=self.slow_signature,
            damage_taken_mult=self.damage_taken,
            slow_lantern=self.slow_lantern,
            spool_immunity=self.spool_immunity,
        )

    def assists_in_use(self) -> tuple[str, ...]:
        """Assist ids currently on, in the order the ledger prints them."""
        on: list[str] = []
        if self.slow_signature:
            on.append("slow_signature")
        if self.damage_taken < 1.0:
            on.append(f"damage_taken_{int(round(self.damage_taken * 100))}")
        if self.slow_lantern:
            on.append("slow_lantern")
        if self.spool_immunity:
            on.append("spool_immunity")
        return tuple(on)

    # -- the mix -----------------------------------------------------------

    def bus_volumes(self) -> tuple[float, float, float]:
        """The three sliders as ``(master, sfx, music)`` fractions of full scale."""
        return (_clamp01(self.volume_master), _clamp01(self.volume_sfx), _clamp01(self.volume_music))

    def apply_volumes(self, audio) -> None:
        """Hand the mix sliders to *audio*, the run's live ``AudioDirector``.

        The director owns the decibel arithmetic: its ``set_bus_volumes`` lays
        the sliders over the authored cue gains and its own music duck rather
        than writing the shared bus layout, so neither side can clobber the
        other. With no director live there is nothing playing to trim; the
        values persist on the profile and land at the next run start.
        """
        if audio is not None:
            audio.set_bus_volumes(*self.bus_volumes())

    @property
    def effective_flash(self) -> float:
        """The flash multiplier after the photosensitivity clamp."""
        return min(self.flash, PHOTOSENSITIVE_FLASH) if self.photosensitive else self.flash

    def hold_to_use(self, action: str) -> bool:
        """Whether *action* is held (True) or toggled (False)."""
        return bool(self.hold_actions.get(action, True))

    # -- persistence -------------------------------------------------------

    def as_dict(self) -> dict:
        return {
            "shake": self.shake,
            "flash": self.flash,
            "hit_stop": self.hit_stop,
            "ui_scale": self.ui_scale,
            "volume_master": self.volume_master,
            "volume_sfx": self.volume_sfx,
            "volume_music": self.volume_music,
            "photosensitive": self.photosensitive,
            "aim_assist": self.aim_assist,
            "controls_bar": self.controls_bar,
            "hold_actions": dict(self.hold_actions),
            "bindings": {action: list(tokens) for action, tokens in self.bindings.items()},
            "frame_cap": self.frame_cap,
            "vsync": self.vsync,
            "slow_signature": self.slow_signature,
            "damage_taken": self.damage_taken,
            "slow_lantern": self.slow_lantern,
            "spool_immunity": self.spool_immunity,
        }

    @classmethod
    def from_dict(cls, payload: dict | None) -> Settings:
        payload = payload or {}
        blank = cls()
        return cls(
            shake=_clamp01(payload.get("shake", blank.shake)),
            flash=_clamp01(payload.get("flash", blank.flash)),
            hit_stop=_clamp01(payload.get("hit_stop", blank.hit_stop)),
            ui_scale=min(UI_SCALE_MAX, max(UI_SCALE_MIN, float(payload.get("ui_scale", blank.ui_scale)))),
            volume_master=_clamp01(payload.get("volume_master", blank.volume_master)),
            volume_sfx=_clamp01(payload.get("volume_sfx", blank.volume_sfx)),
            volume_music=_clamp01(payload.get("volume_music", blank.volume_music)),
            photosensitive=bool(payload.get("photosensitive", blank.photosensitive)),
            aim_assist=bool(payload.get("aim_assist", blank.aim_assist)),
            controls_bar=bool(payload.get("controls_bar", blank.controls_bar)),
            hold_actions={**blank.hold_actions, **dict(payload.get("hold_actions", {}))},
            bindings={str(k): [str(t) for t in v] for k, v in dict(payload.get("bindings", {})).items()},
            frame_cap=_frame_cap_of(payload.get("frame_cap", blank.frame_cap)),
            vsync=bool(payload.get("vsync", blank.vsync)),
            slow_signature=bool(payload.get("slow_signature", blank.slow_signature)),
            damage_taken=_nearest_step(payload.get("damage_taken", blank.damage_taken)),
            slow_lantern=bool(payload.get("slow_lantern", blank.slow_lantern)),
            spool_immunity=bool(payload.get("spool_immunity", blank.spool_immunity)),
        )

    @classmethod
    def from_profile(cls, profile: dict | None) -> Settings:
        return cls.from_dict((profile or {}).get("settings"))

    def store(self, profile: dict) -> dict:
        """Write these settings onto *profile* and hand it back."""
        profile["settings"] = self.as_dict()
        return profile

    # -- application -------------------------------------------------------

    def input_actions(self) -> dict[str, list]:
        """The effective action map: the defaults with the remapping applied."""
        return resolve_input_actions(self)

    def apply_to_run(self, scene: RunScene) -> None:
        """Push every setting into the live run that consumes it."""
        assists = self.assist_settings()
        self.apply_volumes(scene.audio)
        if scene.ship is not None:
            scene.ship.assists = assists
        if scene.juice is not None:
            scene.juice.shake_scale = self.shake
            scene.juice.hit_stop_scale = self.hit_stop
        if scene.signature is not None:
            multiplier = balance.ASSIST_SIGNATURE_FILL_MULT if self.slow_signature else 1.0
            scene.signature.set_gain_multiplier("assist", multiplier)
        if scene.hud is not None:
            scene.hud.ui_scale = self.ui_scale
            scene.hud.controls_bar_visible = self.controls_bar
        if scene.chart_screen is not None:
            scene.chart_screen.ui_scale = self.ui_scale
        if scene.environment is not None:
            # Every flash in this game is an emissive picked up by bloom, so
            # the flash slider is the bloom's gain and photosensitivity mode
            # is a hard ceiling on top of it.
            intensity = float(scene.environment.bloom_intensity) * self.effective_flash
            if self.photosensitive:
                intensity = min(intensity, PHOTOSENSITIVE_BLOOM_INTENSITY)
            scene.environment.bloom_intensity = intensity


def resolve_input_actions(settings: Settings | None) -> dict[str, list]:
    """:func:`base_input_actions` with *settings*' remapping folded in.

    A remapped action keeps every axis binding it had (those are pad geometry,
    not a choice) and replaces the rest with the player's tokens, so remapping
    the keyboard never costs the pad its stick.
    """
    actions = base_input_actions()
    if settings is None:
        return actions
    for action, tokens in settings.bindings.items():
        if action not in actions:
            raise ValueError(f"Cannot rebind unknown action {action!r}")
        axes = [b for b in actions[action] if isinstance(b, InputBinding)]
        actions[action] = [decode_binding(token) for token in tokens] + axes
    return actions


def _clamp01(value: float) -> float:
    return min(1.0, max(0.0, float(value)))


def _nearest_step(value: float) -> float:
    """The nearest damage-taken step, so a drifted file cannot invent one."""
    value = float(value)
    return min(balance.ASSIST_DAMAGE_TAKEN_STEPS, key=lambda step: abs(step - value))


def _apply_vsync(on: bool) -> None:
    """Push vsync at the running window, where there is one.

    Guarded rather than assumed: every test and every headless probe runs this
    module with no App at all, and a settings screen must work in both.
    """
    try:
        from simvx.graphics import App
    except Exception:
        return
    app = App.current()
    if app is not None:
        app.set_vsync(bool(on))


#: Whether this is the browser build, where the page boots the front door
#: directly and ``main()`` never runs.
_IN_BROWSER = sys.platform == "emscripten"


def _apply_frame_cap(cap: int) -> None:
    """Push a frame cap at the running window, where there is one.

    Guarded the same way as :func:`_apply_vsync`, and for the same reason: this
    module runs under tests and headless probes with no ``App`` at all. Zero is
    this game's FOLLOW DISPLAY, which is ``None`` in the engine's vocabulary,
    where a cap must be ``>= 1``.
    """
    try:
        from simvx.graphics import App
    except Exception:
        return
    app = App.current()
    if app is not None:
        app.target_fps = int(cap) or None


def _frame_cap_of(value) -> int:
    """A stored frame cap, read defensively: anything unreadable follows the display.

    A cap the game cannot parse must never stop it booting, and a negative one
    must never reach ``App(target_fps=...)``, so the fallback is zero, which is
    the same thing as having chosen FOLLOW DISPLAY.
    """
    try:
        return max(0, int(value or 0))
    except TypeError, ValueError:
        return 0


# ============================================================================
# The ledger
# ============================================================================


@dataclass(frozen=True)
class ConversionEntry:
    """One line of the death screen's conversion breakdown."""

    label: str
    scrap: float
    rate: float
    cores: float
    capped: bool = False

    def as_dict(self) -> dict:
        return {
            "label": self.label,
            "scrap": self.scrap,
            "rate": self.rate,
            "cores": self.cores,
            "capped": self.capped,
        }

    def line(self) -> str:
        """The row as the screen prints it."""
        text = f"{self.label}: {self.scrap:.0f} scrap at {self.rate:.1f} per 10 = {self.cores:.1f} Cores"
        return f"{text} (capped)" if self.capped else text


@dataclass
class RunLedger:
    """Everything a finished run is judged on, and everything it teaches.

    Filled from the live services as the run ends. ``scrap_carried`` is what
    was in the hold at the end, ``scrap_after_last_stand`` the part of it earned
    after the collapse trigger, and the two are what the conversion breakdown
    prices apart.
    """

    run_number: int = 1
    hull_id: str = save.STARTER_HULL
    seed: int = 0
    outcome: str = ""
    killed_by: str = ""
    elapsed_s: float = 0.0

    scrap_earned: float = 0.0
    scrap_carried: float = 0.0
    scrap_after_last_stand: float = 0.0
    cores_banked_in_run: float = 0.0

    kills: int = 0
    elite_kills: int = 0
    vaults_cracked: int = 0
    arrivals_survived: int = 0
    quills: int = 0
    deepest_sector: int = 1
    sectors_visited: int = 1
    notoriety: int = 0

    hull_left: float = 0.0
    fuel_left: float = 0.0
    o2_left: float = 0.0
    open_breaches: int = 0
    signature: float = 0.0
    loudest_gain: str = ""
    cheapest_exit_fuel: float = 0.0
    last_stand: bool = False

    conversion: list[ConversionEntry] = field(default_factory=list)
    cores_from_conversion: float = 0.0
    cores_from_milestones: float = 0.0
    milestones: list[str] = field(default_factory=list)
    assists: tuple[str, ...] = ()
    score: int = 0
    best_score: int = 0
    new_best: bool = False
    recap: str = ""

    @property
    def cores_total(self) -> float:
        """Every Core the run produced: in-run banking, settlement, bounties."""
        return self.cores_banked_in_run + self.cores_from_conversion + self.cores_from_milestones

    def as_dict(self) -> dict:
        payload = {
            key: value for key, value in self.__dict__.items() if key not in ("conversion", "assists", "milestones")
        }
        payload["conversion"] = [entry.as_dict() for entry in self.conversion]
        payload["assists"] = list(self.assists)
        payload["milestones"] = list(self.milestones)
        payload["cores_total"] = self.cores_total
        return payload


def death_conversion_rate(profile: dict | None, modifiers: dict | None = None) -> float:
    """The Cores-per-10 a death pays, after the training-wheels doctrine node."""
    if modifiers and DEATH_RATE_MODIFIER in modifiers:
        return float(modifiers[DEATH_RATE_MODIFIER])
    owned = ((profile or {}).get("doctrine") or {}).get("owned") or []
    return balance.CONVERT_RATE_DEATH_UPGRADED if DEATH_RATE_NODE_ID in owned else balance.CONVERT_RATE_DEATH


def settle_conversion(ledger: RunLedger, *, death_rate: float = balance.CONVERT_RATE_DEATH) -> list[ConversionEntry]:
    """Price the hold at the end of a run, itemised the way the screen shows it.

    Extraction pays ``balance.CONVERT_RATE_EXTRACTION`` on everything carried.
    A Last Stand pays ``balance.LAST_STAND_CONVERT_RATE`` on scrap earned after
    the trigger, up to ``balance.LAST_STAND_CORES_CAP`` Cores, and *death rate*
    on the rest, which is what stops an engineered collapse from beating the
    Deep Gate. Any other death pays the death rate on the whole hold.
    """
    carried = max(0.0, float(ledger.scrap_carried))
    if carried <= 0.0:
        return []

    if ledger.outcome == "extraction":
        rate = balance.CONVERT_RATE_EXTRACTION
        return [ConversionEntry("Extracted", carried, rate, balance.cores_from_scrap(carried, rate))]

    entries: list[ConversionEntry] = []
    remainder = carried
    if ledger.last_stand:
        rate = balance.LAST_STAND_CONVERT_RATE
        post = min(max(0.0, float(ledger.scrap_after_last_stand)), carried)
        cap_scrap = balance.LAST_STAND_CORES_CAP * balance.CONVERT_SCRAP_UNIT / rate
        paid = min(post, cap_scrap)
        if paid > 0.0:
            entries.append(
                ConversionEntry(
                    "Last Stand",
                    paid,
                    rate,
                    balance.cores_from_scrap(paid, rate),
                    capped=post > cap_scrap,
                )
            )
            remainder = carried - paid
    if remainder > 0.0:
        entries.append(
            ConversionEntry("Carried", remainder, death_rate, balance.cores_from_scrap(remainder, death_rate))
        )
    return entries


def run_score(ledger: RunLedger) -> int:
    """Scrap earned, plus Cores by ten, plus quills by a hundred, plus depth."""
    return int(
        round(
            ledger.scrap_earned
            + ledger.cores_total * balance.SCORE_CORES_WEIGHT
            + ledger.quills * balance.SCORE_QUILLS_WEIGHT
            + ledger.deepest_sector * SCORE_DEPTH_BONUS_PER_SECTOR
        )
    )


def recap_sentence(ledger: RunLedger) -> str:
    """One generated sentence naming the bet that ended the run.

    The rules run most specific first, so the sentence always names the thing
    the player could have done differently rather than restating the obvious.
    """
    sector = ledger.deepest_sector
    if ledger.outcome == "extraction":
        return (
            f"You made the Gate from sector {sector} with {ledger.scrap_carried:.0f} scrap "
            f"and {ledger.fuel_left:.0f} fuel to spare."
        )
    if ledger.last_stand:
        return (
            f"You stranded yourself in sector {sector} with {ledger.fuel_left:.0f} fuel; "
            f"the cheapest way out wanted {ledger.cheapest_exit_fuel:.0f}, so the Last Stand paid "
            f"{ledger.cores_from_conversion:.0f} Cores."
        )
    if ledger.killed_by == "suffocation":
        return (
            f"Your air ran out in sector {sector} with {ledger.open_breaches} unpatched "
            f"breach{'es' if ledger.open_breaches != 1 else ''} bleeding it."
        )
    if ledger.killed_by == LANTERN_BLOW_ID:
        return (
            f"The Shrike's lantern burned you down in sector {sector}; the cone holds dim "
            f"for a full second before it fires, and that second is the dodge."
        )
    if ledger.killed_by == "hunter":
        return (
            f"The Shrike caught you in sector {sector} at signature {ledger.signature:.0f}, "
            f"{ledger.scrap_carried:.0f} scrap still unbanked."
        )
    overstayed = (
        ledger.cheapest_exit_fuel > 0.0
        and ledger.fuel_left >= ledger.cheapest_exit_fuel
        and ledger.signature >= balance.SIGNATURE_MAX * RECAP_OVERSTAY_SIGNATURE_FRACTION
    )
    if overstayed:
        loud = ledger.loudest_gain or "the harvest"
        return (
            f"You overstayed sector {sector} with {ledger.fuel_left:.0f} fuel; the safe exit cost "
            f"{ledger.cheapest_exit_fuel:.0f} and {loud} was what filled the meter."
        )
    killer = (ledger.killed_by or "the sector").replace("_", " ").capitalize()
    if ledger.open_breaches > 0:
        plural = "es" if ledger.open_breaches != 1 else ""
        return (
            f"{killer} finished you in sector {sector} with {ledger.open_breaches} open "
            f"breach{plural} already bleeding the air."
        )
    return f"{killer} finished you in sector {sector} at signature {ledger.signature:.0f}."


def personal_best(profile: dict | None, hull_id: str) -> int:
    """The stored best score for *hull_id*, zero when the hull has no run yet."""
    return int(((profile or {}).get("best_scores") or {}).get(hull_id, 0))


def record_best(profile: dict, hull_id: str, score: int) -> tuple[int, bool]:
    """Store *score* if it beats the hull's best. Returns ``(best, is_new)``."""
    bests = profile.setdefault("best_scores", {})
    previous = int(bests.get(hull_id, 0))
    if int(score) > previous:
        bests[hull_id] = int(score)
        return int(score), True
    return previous, False


def earned_milestones(ledger: RunLedger, profile: dict) -> list[str]:
    """Milestone ids this run earned that the profile has not yet paid."""
    flags = profile.get("milestones") or {}
    reached = {
        "first_extraction": ledger.outcome == "extraction",
        "first_vault": ledger.vaults_cracked > 0,
        "first_elite_kill": ledger.elite_kills > 0,
        "first_act3_entry": ledger.deepest_sector >= balance.ACT_3_FIRST_SECTOR,
        "first_arrival_survived": ledger.arrivals_survived > 0,
    }
    return [name for name, hit in reached.items() if hit and not flags.get(name, False)]


# ============================================================================
# Run configuration and state
# ============================================================================


@dataclass
class RunConfig:
    """The frozen choices a run launches with."""

    run_number: int = 1
    seed: int = 0
    hull_id: str = save.STARTER_HULL
    keystones: tuple[str, ...] = ()
    modifiers: dict = field(default_factory=dict)
    deep_insertion: bool = False

    def as_dict(self) -> dict:
        return {
            "run_number": self.run_number,
            "seed": self.seed,
            "hull_id": self.hull_id,
            "keystones": list(self.keystones),
            "modifiers": dict(self.modifiers),
            "deep_insertion": self.deep_insertion,
        }

    @classmethod
    def from_dict(cls, payload: dict | None) -> RunConfig:
        payload = payload or {}
        return cls(
            run_number=int(payload.get("run_number", 1)),
            seed=int(payload.get("seed", 0)),
            hull_id=str(payload.get("hull_id", save.STARTER_HULL)),
            keystones=tuple(payload.get("keystones", ()))[: balance.DOCTRINE_MAX_ACTIVE_KEYSTONES],
            modifiers=dict(payload.get("modifiers", {})),
            deep_insertion=bool(payload.get("deep_insertion", False)),
        )


class RunState:
    """The live run: where it is on the chart, and what it has done so far.

    Also the object :class:`~shrike.chart.StarChart` reads, which is why
    ``chart``, ``current_node_id``, ``jumps_taken``, ``notoriety`` and ``fuel``
    are spelled exactly as it expects them.
    """

    def __init__(self, config: RunConfig):
        self.config = config
        self.seed = int(config.seed)
        self.run_number = int(config.run_number)
        self.chart = ChartGraph(self.seed)
        self.current_node_id = self.chart.start_id
        self.jumps_taken = 0
        self.sector_index = 1
        self.biome_id = self.chart.nodes[self.current_node_id].biome
        self.elapsed_s = 0.0
        self.kit = ""
        self.deck = SignalEventDeck(self.seed, set())
        self.ledger = RunLedger(run_number=self.run_number, hull_id=config.hull_id, seed=self.seed)
        #: Mirror of the run tally, so the chart prices routes with no service up.
        self.notoriety = 0
        #: Mirror of the tank, same reason.
        self.fuel = balance.FUEL_MAX
        #: The suspend payload a resume still has to apply to the live world
        #: (meters, hold, hull, harvest progress); None on a fresh run.
        self.restore: dict | None = None
        #: The lane the drive was pointed at when the run was written out, so a
        #: resume comes back holding the pilot's own choice rather than the
        #: default an arrival would arm. The live value is the chart's own
        #: selection; this is only the carrier across the suspend slot.
        self.armed_node_id = ""
        #: Every chart node this run has already *left behind*. Lanes run both
        #: ways, so a second arrival has to be tellable from a first one, and
        #: departure rather than arrival is what makes that true across a
        #: suspend: the sector a saved run is sitting in has not been left, so
        #: resuming into it deals the layout it saved rather than a stripped
        #: one, while a node it really did leave and fly back to stays stripped
        #: whether or not the pilot quit in between.
        self.visited: set[str] = set()
        #: What has already been bought at each node's dock, by node id. A
        #: revisited depot is the same depot: its shelf is stable from the same
        #: seed, and the counter that marks a row sold has to be too, or a
        #: round trip re-stocks the once-per-visit O2 canister.
        self.depot_purchases: dict[str, dict[str, int]] = {}

    @property
    def act(self) -> int:
        return balance.act_for_sector(self.sector_index)

    def sector_seed(self) -> int:
        """A stable per-node seed, so a node's danger and payout are learnable.

        Keyed on the node rather than on the sector index, for two reasons the
        mirrored chart makes load-bearing. Walking back into a node has to deal
        the place the pilot remembers, not whatever the index says, since
        escalation does not follow the column. And a seed per column would give
        two nodes in one column the same seed, so a fork would offer the
        identical layout twice under two biome names.
        """
        node = self.chart.nodes.get(self.current_node_id)
        key = (node.column + 1) * 7919 + node.row * 104_729 if node is not None else self.sector_index * 7919
        return (self.seed * 1_000_003 + key) & 0x7FFF_FFFF

    def as_suspend(self) -> dict:
        """This run as a ``save.blank_suspend`` payload, ready to write."""
        payload = save.blank_suspend()
        payload["run"].update(
            {
                "run_number": self.run_number,
                "seed": self.seed,
                "elapsed_s": self.elapsed_s,
                "kit": self.kit,
                "keystones": list(self.config.keystones),
                "sector_index": self.sector_index,
                "sector_seed": self.sector_seed(),
                "biome_id": self.biome_id,
            }
        )
        payload["ship"]["hull_id"] = self.config.hull_id
        payload["chart"].update(
            {
                "seed": self.seed,
                "current_node": self.current_node_id,
                "wake_column": self.chart.wake_column,
                "jumps_taken": self.jumps_taken,
                "visited": sorted(self.visited),
                "armed_target": self.armed_node_id,
            }
        )
        payload["notoriety"]["value"] = int(self.notoriety)
        payload["ledger"].update(
            {
                "scrap_earned": self.ledger.scrap_earned,
                "kills": self.ledger.kills,
                "deepest_sector": self.ledger.deepest_sector,
            }
        )
        return payload

    @classmethod
    def from_suspend(cls, payload: dict) -> RunState:
        """Rebuild a run from a suspend save. The chart regenerates from its seed."""
        run = payload.get("run") or {}
        chart = payload.get("chart") or {}
        config = RunConfig(
            run_number=int(run.get("run_number", 1)),
            seed=int(run.get("seed", chart.get("seed", 0))),
            hull_id=str((payload.get("ship") or {}).get("hull_id", save.STARTER_HULL)),
            keystones=tuple(run.get("keystones", ())),
        )
        state = cls(config)
        state.sector_index = max(1, int(run.get("sector_index", 1)))
        state.elapsed_s = float(run.get("elapsed_s", 0.0))
        state.kit = str(run.get("kit", ""))
        state.jumps_taken = int(chart.get("jumps_taken", 0))
        node_id = str(chart.get("current_node", "")) or state.chart.start_id
        if node_id in state.chart.nodes:
            state.current_node_id = node_id
            state.biome_id = state.chart.nodes[node_id].biome
        state.visited = {str(v) for v in chart.get("visited", ()) if str(v) in state.chart.nodes}
        armed = str(chart.get("armed_target", ""))
        state.armed_node_id = armed if armed in state.chart.nodes else ""
        here = state.chart.nodes.get(state.current_node_id)
        state.chart.advance_wake(
            state.jumps_taken,
            int((payload.get("notoriety") or {}).get("value", 0)),
            pilot_column=here.column if here is not None else None,
        )
        state.notoriety = int((payload.get("notoriety") or {}).get("value", 0))
        # Replay the event deck to just before the suspended sector's own draw,
        # so regenerating that sector deals the card it actually held.
        draws = int((payload.get("sector") or {}).get("event_draws", 0))
        for _ in range(max(0, draws - 1)):
            state.deck.draw()
        ledger = payload.get("ledger") or {}
        state.ledger.scrap_earned = float(ledger.get("scrap_earned", 0.0))
        state.ledger.kills = int(ledger.get("kills", 0))
        state.ledger.deepest_sector = max(state.sector_index, int(ledger.get("deepest_sector", 0)), 1)
        state.restore = payload
        return state


# ============================================================================
# Menu furniture
# ============================================================================


class PressLatch:
    """One action's press and release edges, deaf to a press it did not see start.

    A screen raised by a key press is mounted while that key is still down, so
    the first frame's ``just_pressed`` belongs to whatever opened the
    screen rather than to the player answering it: read naively, the doctrine
    grid buys a node the instant it appears and the dock screen sells the hold
    on the press that docked. The latch is primed with the action's state on
    its first poll, and reports no edge on that frame, so the first edge it ever
    reports is a press made on the screen that owns it. It is not primed when
    it is made, because a screen builds its latches in its constructor, before
    it is in the tree whose input actions name the action.

    :attr:`hold_s` measures the press that is down, and survives the release
    frame, which is what lets the dock screen tell a tap from the three-second
    sell hold on the same button.
    """

    def __init__(self, action: str):
        self.action = action
        self.held: bool | None = None
        self.hold_s = 0.0
        self._seen = False

    def poll(self, dt: float) -> tuple[bool, bool]:
        """This frame's ``(pressed, released)`` edges. Call once per update."""
        held = Input.pressed(self.action)
        if self.held is None:
            self.held = held
            return False, False
        pressed = released = False
        if held and not self.held:
            self._seen = True
            self.hold_s = 0.0
            pressed = True
        elif held:
            self.hold_s += dt
        elif self.held:
            released = self._seen
            self._seen = False
        self.held = held
        return pressed, released


class MenuList:
    """Keyboard, pad and mouse selection over a column of buttons.

    One dispatch path, not two. The rows are buttons, but a button's own press
    signal is not what runs them: the list reads the pointer and the action map
    itself and runs the row the pointer is actually over. Two paths would
    disagree. A click is a press and a release with a frame or two between
    them, which is every click a person makes, and the press would fire the row
    the keyboard cursor happened to be on: on a cold boot SETTINGS and FLEET
    DOCTRINE would both open the run setup screen, and the pause menu's
    SETTINGS would resume the run, because that cursor is still on row one.

    So the cursor follows a moving pointer, which makes the highlighted row and
    the row a click runs the same row by construction, and a click over no row
    at all chooses nothing. Selection is bracketed and warmed rather than only
    warmed, so a player who never touches the mouse can see where they are.

    That is why each row declares ``PointerFilter.IGNORE``. A widget that is
    hit-testable claims the press it is under, and a claimed press writes no
    action state, so leaving the rows hit-testable would take
    ``fire_primary`` away from the one path that reads it and no click would
    choose anything at all. The rows here are drawn furniture the list hit-tests
    itself, and IGNORE is how a control says so. The screens whose rows are a
    mix of buttons and drawn plates say it for the same reason: a second
    dispatch path for the half that happens to be a button is what this class
    exists to prevent.
    """

    def __init__(self, box: VBoxContainer):
        self.box = box
        self.entries: list[tuple[str, object]] = []
        self.buttons: list[Button] = []
        self.index = 0
        self._click = PressLatch("fire_primary")
        self._commit = PressLatch("interact")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._pointer: tuple[float, float] | None = None
        self._marked: int | None = None

    def add(self, text: str, action) -> Button:
        """Append a row running *action* when it is chosen."""
        button = self.box.add_child(Button(text, size_y=MENU_ROW_HEIGHT_PX))
        button.size_x = MENU_WIDTH_PX
        button.pointer_filter = PointerFilter.IGNORE
        self.entries.append((text, action))
        self.buttons.append(button)
        self._marked = None
        self.mark()
        return button

    @property
    def selected(self) -> str:
        return self.entries[self.index][0] if self.entries else ""

    def move(self, step: int) -> None:
        if self.entries:
            self.index = (self.index + int(step)) % len(self.entries)

    def activate(self) -> bool:
        """Run the selected row's action. False when the list is empty."""
        if not self.entries:
            return False
        self.entries[self.index][1]()
        return True

    def relabel(self, index: int, text: str) -> None:
        """Rewrite one row's label in place, keeping its action and the cursor.

        A row whose label carries a value ("DAMAGE TAKEN: 80%") has to be able
        to say the new one the moment the row changes it, or the setting is
        readable only by looking somewhere else for it.
        """
        _old, action = self.entries[index]
        self.entries[index] = (str(text), action)
        self._marked = None
        self.mark()

    def focus(self, text: str) -> bool:
        """Put the cursor on the row labelled *text*. False when there is none.

        Matches a whole label or a prefix of one, because the rows that carry a
        live value in their label ("FLEET DOCTRINE (12 Cores)") are named by a
        caller that does not know the value.
        """
        if not text:
            return False
        for index, (label, _action) in enumerate(self.entries):
            if label == text or label.startswith(text):
                self.index = index
                self.mark()
                return True
        return False

    def reset(self) -> None:
        """Put the cursor on row one and re-prime the press latches.

        An overlay is raised in the middle of a run, with whatever the pilot
        was holding still held. Priming the latches at that moment is what
        stops the trigger that was down when Escape was pressed from choosing
        the first thing the pause menu offers.
        """
        self.index = 0
        self._click = PressLatch("fire_primary")
        self._commit = PressLatch("interact")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._pointer = None
        self.mark()

    def pointed_at(self) -> tuple[int | None, bool]:
        """The row under the pointer, and whether the pointer has just moved.

        Only a pointer that moved takes the cursor: a mouse left resting over a
        row must not fight the keyboard for it. A click takes it either way.
        """
        position = Input.mouse_position
        point = (float(position.x), float(position.y))
        moved = self._pointer is not None and point != self._pointer
        self._pointer = point
        for index, button in enumerate(self.buttons):
            if _rect_holds(button.get_global_rect(), point):
                return index, moved
        return None, moved

    def mark(self) -> None:
        """Draw the focus ring on the selected row, when it has moved."""
        if self._marked == self.index:
            return
        self._marked = self.index
        for index, (text, _) in enumerate(self.entries):
            button = self.buttons[index]
            chosen = index == self.index
            _set_text(button, f"{MENU_CURSOR_LEFT} {text} {MENU_CURSOR_RIGHT}" if chosen else text)
            button.text_colour = Colour.coerce(MENU_SELECTED_COLOUR if chosen else MENU_TEXT_COLOUR, name="menu_row")

    def poll(self, dt: float = 0.0) -> None:
        """Read this frame's navigation input and run a chosen row.

        Call from ``on_update``, passing that frame's *dt*.
        """
        if Input.just_pressed("thrust_down") or Input.just_pressed(MENU_DOWN_ACTION):
            self.move(1)
        elif Input.just_pressed("thrust_up") or Input.just_pressed(MENU_UP_ACTION):
            self.move(-1)

        under, moved = self.pointed_at()
        if under is not None and moved:
            self.index = under
        clicked, _ = self._click.poll(dt)
        committed, _ = self._commit.poll(dt)
        confirmed, _ = self._confirm.poll(dt)
        if clicked and under is not None:
            self.index = under
        self.mark()
        if committed or confirmed or (clicked and under is not None):
            self.activate()


class MenuPanel(Panel):
    """A panel sized to its column, placed before that column is ever laid out.

    The column is built detached and mounted by :meth:`settle` once the panel
    knows the rect it will keep. That order is load-bearing rather than tidy. A
    control's retained draw bakes the absolute transform it was first captured
    at, and the engine does not rewrite a child's transform row when an
    *ancestor* moves, so a panel that resizes and recentres after its rows are
    already placed leaves every one of them painted at its old position: a
    blank gap opens under the subtitle, the buttons slide out through the
    bottom of the panel, and the footer draws over what is left. Measuring
    the finished column, placing the panel, and only then mounting the column
    means nothing under a menu ever moves after it is built.

    The panel is anchored to the top left of its backdrop, and :meth:`recentre`
    sets its size and its inset from that corner together, so the rect is
    always whole: centred in the window, or pinned against the top-left gutter
    when it does not fit (see :func:`_placed`).

    A column too big for the window is shrunk uniformly to fit
    (:data:`MENU_MIN_FIT_SCALE` is the floor) and then placed against the top
    gutter, so a long shelf loses type size rather than losing its title above
    the window and its buttons below it.
    """

    def __init__(self, **kwargs):
        super().__init__(anchor=Anchor.TOP_LEFT, **kwargs)
        self.column: VBoxContainer | None = None
        self.padding = MENU_PADDING_PX
        #: What the type and the row heights were fitted by; 1.0 when they fit.
        self.fit_scale = 1.0
        #: What the row widths were fitted by. Never below :attr:`fit_scale`, so
        #: shrinking a column never costs a row characters it used to hold.
        self.fit_width_scale = 1.0

    # -- mounting ----------------------------------------------------------

    def settle(self) -> None:
        """Fit and place the panel, then mount the finished column on it."""
        column = self.column
        if column is None:
            return
        if column.parent is not self:
            self._shrink_to_fit(column)
            self.recentre()
            self.add_child(column)
            tree = self.tree
            if tree is not None:
                # Containers reflow on the tree's dirty set, which drains at the
                # end of the tick. Draining it here keeps that reflow on the
                # near side of the first draw.
                tree.flush_layout()
        # Mounting is the first time the rows are measured in the tree, and a
        # grid measures differently once its cells are laid out there, so the
        # panel is fitted again to what the column really came out at. Both
        # passes land before the frame is drawn: nothing is ever painted at a
        # rect it is about to leave.
        self.recentre()

    def _shrink_to_fit(self, column: VBoxContainer) -> None:
        """Scale *column* down until it fits the window, or until the floor.

        Iterated rather than solved: type has minimum sizes of its own, so a
        column scaled by a half does not come out half as tall, and one pass
        leaves a shelf still hanging out of the window it was fitted to.

        The two axes are fitted separately, because a column that is too tall
        is not thereby too wide: a settings screen shrunk on both axes to fit
        its own height would sit as a narrow strip in the middle of a window
        with four hundred spare pixels either side of it. Row widths never
        shrink further than the type does, so a row can only ever gain
        characters by being fitted, never lose them.
        """
        for _ in range(MENU_FIT_PASSES):
            width_step, height_step = self.fit_to_window()
            step = max(min(1.0, width_step, height_step), MENU_MIN_FIT_SCALE / self.fit_scale)
            width_step = max(min(1.0, width_step), step)
            if step >= 1.0 and width_step >= 1.0:
                return
            _scale_controls(column, step, width_step)
            self.padding *= step
            self.fit_scale *= step
            self.fit_width_scale *= width_step

    @property
    def settled(self) -> bool:
        """Whether the column has been measured, placed and mounted."""
        return self.column is not None and self.column.parent is self

    def on_update(self, dt: float):
        del dt
        if not self.visible_in_tree:
            # The pause overlay is mounted for the whole run with visible=False,
            # so re-measuring and re-placing its column every frame behind the
            # flying game would be wasted work: recentre() calls fitted_size(),
            # which calls get_minimum_size() on the whole column.
            # Nothing is owed while it is down, because PauseScene._build
            # rebuilds and settles the panel on every open.
            return
        if not self.settled:
            # The safety net for a screen that forgot to settle its own panel:
            # this still runs before the frame is drawn, so the rows are never
            # painted at anything but their final coordinates.
            self.settle()
            return
        self.recentre()

    # -- geometry ----------------------------------------------------------

    def window_rect(self) -> tuple[float, float, float, float]:
        """The rect the panel has to sit inside: its backdrop, or the screen."""
        parent = self.parent
        if isinstance(parent, Control):
            return tuple(parent.get_global_rect())
        size = getattr(self.tree, "screen_size", None) or MENU_FALLBACK_WINDOW_PX
        return (0.0, 0.0, float(size[0]), float(size[1]))

    def fit_to_window(self) -> tuple[float, float]:
        """The shrink each axis still needs for this column to fit the window."""
        width, height = self.fitted_size()
        _, _, room_width, room_height = self.window_rect()
        room_width = max(1.0, room_width - 2.0 * MENU_WINDOW_MARGIN_PX)
        room_height = max(1.0, room_height - 2.0 * MENU_WINDOW_MARGIN_PX)
        return (room_width / max(1.0, width), room_height / max(1.0, height))

    def recentre(self) -> None:
        """Fit the panel to its column and place it inside the window."""
        width, height = self.fitted_size()
        _, _, room_width, room_height = self.window_rect()
        self.size = (width, height)
        self.inset = (_placed(room_width, width), _placed(room_height, height))

    def fitted_size(self) -> tuple[float, float]:
        """The size the column wants, plus :attr:`padding` on all four sides."""
        pad = 2.0 * self.padding
        if self.column is None:
            return (MENU_WIDTH_PX + pad, MENU_ROW_HEIGHT_PX + pad)
        measured = self.column.get_minimum_size()
        return (max(MENU_WIDTH_PX * self.fit_width_scale, float(measured.x)) + pad, float(measured.y) + pad)


def _placed(room: float, extent: float) -> float:
    """Where *extent* sits in *room*: centred, or against the top-left gutter.

    A panel that has outgrown the window is pinned rather than centred, so what
    falls off the end is the bottom of a list and never the title above it.

    A panel that fits the window but not the window's margins is placed to fit
    the window: the gutter is a preference and staying on screen is not, and
    the column's shrink-to-fit stops at a readability floor, so a full screen
    can come out a few pixels taller than the margins would like. Pinning it at
    the gutter would push the last row off the bottom of a panel that fits.
    """
    if extent >= room:
        return MENU_WINDOW_MARGIN_PX
    return min(max(MENU_WINDOW_MARGIN_PX, (room - extent) / 2.0), room - extent)


def _scale_controls(root: Control, scale: float, width_scale: float) -> None:
    """Shrink *root* and every control under it: type by *scale*, widths by
    *width_scale*.

    Type, row heights and the gaps between rows move together, because a row's
    height is its type; widths are a container measurement and are fitted on
    their own axis. A column too big for the window loses size rather than
    losing its ends off the edges. Applied while the column is still detached,
    so it costs one layout rather than a reflow per control.
    """
    root.margin_left *= scale
    root.margin_top *= scale
    stack: list[Control] = [root]
    while stack:
        control = stack.pop()
        if control.size_x > 0.0:
            control.size_x *= width_scale
        if control.size_y > 0.0:
            control.size_y *= scale
        font = getattr(control, "font_size", 0.0)
        if font:
            control.font_size = float(font) * scale
        separation = getattr(control, "separation", 0.0)
        if separation:
            control.separation = float(separation) * scale
        stack.extend(child for child in control.children if isinstance(child, Control))


def build_menu_panel(
    parent,
    title: str,
    subtitle: str = "",
    *,
    title_size: float = MENU_TITLE_FONT_PX,
    width: float = MENU_WIDTH_PX,
) -> VBoxContainer:
    """Mount the standard backdrop and panel on *parent*, and open its column.

    Every piece of furniture here declares ``PointerFilter.IGNORE``, because
    every screen built on it hit-tests its own rows against the pointer and
    reads ``fire_primary`` for the click. A control that takes part in the hit
    test claims the press it is under, and a claimed press writes no action
    state, so a scrim that is merely drawn would take the click away from the
    only path that reads it and nothing on the screen would be choosable.

    Returns the column to fill with rows. The column comes back **detached**:
    it is laid out for the first time by :func:`settle_menu_panel`, once every
    row it will ever hold is in it and the panel knows its final rect. Shared
    by every flow screen and by the in-run pause overlay, which is a
    :class:`Control` rather than a scene and so cannot inherit
    :meth:`ShrikeScene.build_panel`. *title_size* is the one thing a screen may
    raise its voice with: the death ledger names the killer in type nobody has
    to look for. *width* is the column's own width, which the wide screens (the
    doctrine grid, the dock shelf) set here rather than after the fact.
    """
    backdrop = parent.add_child(Panel(name="Backdrop", anchor=Anchor.FULL_RECT))
    backdrop.bg_colour = MENU_BACKDROP
    backdrop.pointer_filter = PointerFilter.IGNORE

    panel = backdrop.add_child(MenuPanel(name="Panel"))
    panel.bg_colour = MENU_PANEL
    panel.pointer_filter = PointerFilter.IGNORE

    box = VBoxContainer(name="Rows")
    box.sizing = SizingMode.CONTENT
    box.separation = MENU_SEPARATION_PX
    box.size_x = float(width)
    box.margin_left = box.margin_top = MENU_PADDING_PX
    box.pointer_filter = PointerFilter.IGNORE
    panel.column = box

    heading = box.add_child(Label(title, name="Title"))
    heading.font_size = float(title_size)
    heading.text_colour = Colour.coerce(MENU_TITLE_COLOUR, name="title")
    heading.pointer_filter = PointerFilter.IGNORE
    if subtitle:
        add_menu_line(box, subtitle, dim=True)
    return box


def menu_panel_of(root) -> MenuPanel | None:
    """The live panel a screen built on *root*, or None before it has one.

    A rebuilt screen (the dock, the pause) destroys its old backdrop and mounts
    a new one in the same breath, and the engine's removal is deferred to the
    end of the frame, so both are children for the rest of it. The one on its
    way out is skipped: settling it, or hanging a reference on it, would put
    the screen's rows on a panel that is about to be carried away.
    """
    for backdrop in root.children:
        if getattr(backdrop, "destroying", False):
            continue
        for child in getattr(backdrop, "children", ()):
            if isinstance(child, MenuPanel):
                return child
    return None


def settle_menu_panel(root) -> None:
    """Place *root*'s panel and mount the column it has finished filling.

    Called once, at the end of building a screen. Everything the column holds
    is laid out at that moment, at the coordinates it keeps for the life of the
    screen: a row is never drawn at a position it is about to leave.
    """
    panel = menu_panel_of(root)
    if panel is not None:
        panel.settle()


def add_menu_line(box: VBoxContainer, text: str, *, dim: bool = False) -> Label:
    """One text row in a panel column. Drawn only: see :func:`build_menu_panel`."""
    label = box.add_child(Label(text))
    label.text_colour = Colour.coerce(MENU_DIM_COLOUR if dim else MENU_TEXT_COLOUR, name="line")
    label.pointer_filter = PointerFilter.IGNORE
    return label


def warp_price(quote) -> str:
    """A jump's fuel price, itemised whenever it is more than the base fare.

    "22 fuel" where every other quote in the game says 15 is a number the
    pilot cannot check, and the surcharge it hides is a decision: a jump made
    before the hunter tears in costs the base fare, and the same jump made
    after it costs half as much again. So the chip prints the sum whenever
    there is one, and each part says what charged it.

    The multiplier is the awkward one, because it is applied to the drive half
    of the price rather than added to it; quoting it as the difference it
    makes is the form a pilot can add up.
    """
    base = float(getattr(quote, "base", 0.0))
    skip = float(getattr(quote, "skip_surcharge", 0.0))
    toll = float(getattr(quote, "toll", 0.0))
    total = float(getattr(quote, "total", base))
    hunted = (base + skip) * (balance.EMERGENCY_WARP_FUEL_MULT - 1.0) if getattr(quote, "emergency", False) else 0.0
    parts = ""
    if skip >= 0.5:
        parts += WARP_PRICE_SKIP.format(extra=skip)
    if hunted >= 0.5:
        parts += WARP_PRICE_HUNTED.format(extra=hunted)
    if toll >= 0.5:
        parts += WARP_PRICE_TOLL.format(extra=toll)
    if not parts:
        return WARP_PRICE_PLAIN.format(total=total)
    return WARP_PRICE_ITEMISED.format(total=total, base=base, parts=parts)


def cores_source_line(profile: dict | None = None) -> str:
    """The one sentence naming where Cores come from, at this profile's rates.

    Printed by both screens that show a Core balance: the tree, where the
    balance is what a purchase is measured against, and the ledger, where it
    has just been paid. The death rate is the profile's own, because the
    doctrine tree sells a node that raises it and a screen quoting the base
    rate to a player who has bought that node is quoting a stale number.
    """
    return CORES_SOURCE_LINE.format(
        post=balance.CONVERT_RATE_TRADING_POST,
        unit=balance.CONVERT_SCRAP_UNIT,
        refinery=balance.CONVERT_RATE_REFINERY,
        gate=balance.CONVERT_RATE_EXTRACTION,
        death=death_conversion_rate(profile),
    )


def wrap_prose(text: str, font_px: float, width_px: float = MENU_WIDTH_PX) -> list[str]:
    """*text* broken into lines that fit *width_px* at *font_px*.

    A panel grows to fit its widest child, so one long generated sentence would
    stretch the death ledger's panel out past its own buttons: the recap would
    run off both sides of the column it is supposed to be a caption for. The
    advance is estimated rather than measured because the wrap has to be
    decidable before the labels exist, and a slightly conservative estimate
    costs a wrap point rather than a clipped word.
    """
    limit = max(1, int(width_px / max(1.0, font_px * MENU_GLYPH_ADVANCE_FRACTION)))
    lines: list[str] = []
    current = ""
    for word in str(text).split():
        candidate = f"{current} {word}" if current else word
        if len(candidate) <= limit or not current:
            current = candidate
        else:
            lines.append(current)
            current = word
    if current:
        lines.append(current)
    return lines


def ellipsise(text: str, limit: int) -> str:
    """*text* cut to *limit* characters, marked where it was cut.

    The blunt companion to :func:`wrap_prose`, for the rows that cannot wrap:
    a button is one line tall, and a line that outgrows it does not clip, it
    runs out through both sides of the button and over whatever is beside it.
    """
    text = str(text)
    if limit <= 0 or len(text) <= limit:
        return text
    if limit <= len(DEPOT_ROW_ELLIPSIS):
        return text[:limit]
    return text[: limit - len(DEPOT_ROW_ELLIPSIS)].rstrip() + DEPOT_ROW_ELLIPSIS


def _cell_indent(tail: str, chars: int) -> int:
    """How far a doctrine cell's second line is set in, given what it carries.

    The first line spends :data:`DOCTRINE_CELL_MARK_CHARS` on the state mark
    and its space, and the second is set in by the same amount so the wrapped
    half of a title reads under the first half rather than under the mark.
    That alignment is a nicety and the price on the line is not, so when the
    two compete the indent is what gives: a cell that dropped a word to keep
    its left edge would have traded the thing it is read for against a thing
    nobody would have noticed.
    """
    return max(0, min(DOCTRINE_CELL_MARK_CHARS, int(chars) - len(tail)))


def _set_text(control, text: str) -> None:
    """Write *text* onto a control, and only when it has actually changed.

    The two live screens redraw their rows every frame from the profile and the
    hold, and an unconditional write would dirty sixty controls a frame for a
    tree nobody is spending in.
    """
    if control.text != text:
        control.text = text


def _strip_without(row: str, word: str) -> str:
    """*row* with every entry naming *word* taken out of it."""
    parts = row.split(CONTROLS_BAR_SEPARATOR)
    return CONTROLS_BAR_SEPARATOR.join(part for part in parts if word not in part.upper())


def _strip_relabel(row: str, word: str, entry: str) -> str:
    """*row* with the entry naming *word* rewritten as *entry*, in place."""
    parts = row.split(CONTROLS_BAR_SEPARATOR)
    return CONTROLS_BAR_SEPARATOR.join(entry if word in part.upper() else part for part in parts)


def controls_bar_without_chart() -> str:
    """The HUD's key strip with the chart key taken out of it.

    Run one has no chart, and a strip that offers M anyway is the one place a
    pilot is certain to read the key off. Filtered rather than restated, so the
    strip stays the HUD's to write.
    """
    return _strip_without(CONTROLS_BAR_TEXT, "CHART")


def controls_bar_rows(schedule: Onboarding) -> tuple[str, str]:
    """Both key-strip rows, as the schedule has them at this point in the game.

    The chart key goes with the chart: before run two there is none, and a
    strip is the one place a pilot is certain to read a key off, so it must
    never name one whose answer is "not yet".

    Silent running is a run-3 unlock, and it is *marked* rather than dropped.
    A key that vanishes from the strip and reappears three runs later reads as
    a bar that cannot be trusted; a key marked locked reads as something to
    come back for, and C still answers on the toast line meanwhile.

    The scoop leaves the strip outright. It is passive, always on and has
    nothing to press: naming Tab would tell a pilot to toggle a thing that does not
    toggle, which is the one job a key strip must not do.
    """
    first = CONTROLS_BAR_TEXT if schedule.chart_open() else controls_bar_without_chart()
    second = _strip_without(CONTROLS_BAR_SECOND_ROW, "SCOOP")
    if not schedule.silent_running_available():
        second = _strip_relabel(second, "SILENT", CONTROLS_BAR_SILENT_LOCKED)
    return first, second


def _rect_holds(rect, point: tuple[float, float]) -> bool:
    """Whether a global rect contains a screen point."""
    x, y, width, height = rect
    return x <= point[0] <= x + width and y <= point[1] <= y + height


class ShrikeScene(Node):
    """Base for every flow screen: settings, the profile, and scene switching.

    Every screen declares the action map so a swap never leaves the game
    unbound, and reaches the save system through the tree singleton this class
    creates on first use.
    """

    input_context = base_input_actions()

    def __init__(self, *, settings: Settings | None = None, profile: dict | None = None, **kwargs):
        super().__init__(**kwargs)
        self._settings = settings
        self._profile = profile

    # -- meta services -----------------------------------------------------

    def save_system(self) -> save.SaveSystem:
        """The tree's save singleton, created on first use."""
        tree = self.tree
        system = tree.singletons.get(Services.SAVE)
        if not isinstance(system, save.SaveSystem):
            system = save.SaveSystem(name="SaveSystem")
            tree.add_singleton(Services.SAVE, system)
        return system

    def meta_profile(self) -> MetaProfile:
        """The doctrine singleton, created on first use.

        The save system is created first because the profile node loads through
        it the moment it is mounted.
        """
        tree = self.tree
        node = tree.singletons.get(Services.META)
        if not isinstance(node, MetaProfile):
            self.save_system()
            node = MetaProfile(name="MetaProfile")
            tree.add_singleton(Services.META, node)
        return node

    def profile(self) -> dict:
        """The one live profile dictionary, owned by :class:`meta.MetaProfile`.

        A profile handed to this screen's constructor (a test, a debug console)
        is adopted by the singleton rather than kept beside it, so there is
        never a second dictionary for Cores to be banked into.
        """
        node = self.meta_profile()
        if self._profile is not None and self._profile is not node.profile:
            node.adopt(self._profile)
        self._profile = node.profile
        return self._profile

    def settings(self) -> Settings:
        if self._settings is None:
            self._settings = Settings.from_profile(self.profile())
        return self._settings

    def modifiers(self) -> dict:
        """The resolved effect bag the run reads at launch."""
        return dict(self.meta_profile().modifiers())

    # -- switching ---------------------------------------------------------

    def go(self, scene: Node) -> None:
        """Swap to *scene*, carrying the settings and profile across.

        A screen owned by another module (the Roost) still gets the action map,
        so a swap never leaves the game unbound.
        """
        if isinstance(scene, ShrikeScene):
            scene._settings = self.settings()
            scene._profile = self.profile()
        scene.input_context = self.settings().input_actions()
        self.tree.change_scene(scene)

    def quit(self) -> None:
        """Leave the game the way the engine expects."""
        app = self.app
        if app is not None:
            app.quit()

    # -- layout ------------------------------------------------------------

    def build_panel(
        self,
        title: str,
        subtitle: str = "",
        *,
        title_size: float = MENU_TITLE_FONT_PX,
        width: float = MENU_WIDTH_PX,
    ) -> VBoxContainer:
        """A column under a title, detached until :meth:`settle_panel` mounts it."""
        return build_menu_panel(self, title, subtitle, title_size=title_size, width=width)

    def add_line(self, box: VBoxContainer, text: str, *, dim: bool = False) -> Label:
        """One text row in a panel column."""
        return add_menu_line(box, text, dim=dim)

    def settle_panel(self) -> None:
        """Place the panel and mount the column, once the rows are all in it."""
        settle_menu_panel(self)

    def menu_panel(self) -> MenuPanel | None:
        """This screen's centred panel, or None before it is built."""
        return menu_panel_of(self)


# ============================================================================
# The screens
# ============================================================================


class MainMenuScene(ShrikeScene):
    """The front door: launch, resume, settings, quit.

    The nebula behind it is the same procedural sky the run uses, which is what
    a Roost kill permanently mutates.
    """

    def __init__(self, *, focus_entry: str = "", **kwargs):
        kwargs.setdefault("name", "MainMenu")
        super().__init__(**kwargs)
        self.menu: MenuList | None = None
        #: The row to open on, named by whichever screen sent the player back
        #: here. Backing out of a submenu onto row one is how a player loses
        #: their place in a menu they have been in three times this session.
        self.focus_entry = str(focus_entry)
        #: Escape leaves the game from here, and Escape is also how the screens
        #: behind this one are backed out of. The latch is what keeps the press
        #: that returned to the front door from walking straight out of it.
        self._back: PressLatch | None = None

    def on_ready(self):
        if _IN_BROWSER:
            # main() never runs in the browser: the page boots straight into this
            # scene, so the saved cap is applied here instead.
            _apply_frame_cap(_frame_cap_of(self.settings().frame_cap))
        self._back = PressLatch(PAUSE_ACTION)
        profile = self.profile()
        cores = int(profile.get("cores", 0))
        rank = int(profile.get("hunt_rank", 0))
        box = self.build_panel("SHRIKE", f"{cores} Cores banked, Hunt Rank {rank}")
        self.menu = MenuList(box)
        if self.save_system().has_suspend():
            self.menu.add("RESUME RUN", self.resume_run)
        self.menu.add("NEW RUN", self.new_run)
        self.menu.add(DOCTRINE_MENU_ENTRY.format(cores=cores), self.open_doctrine)
        self.menu.add("SETTINGS", self.open_settings)
        self.menu.add("QUIT", self.quit)
        self.add_line(box, MENU_CONTROLS_LINE, dim=True)
        self.menu.focus(self.focus_entry)
        self.settle_panel()

    def on_update(self, dt: float):
        if self._back is not None and self._back.poll(dt)[0]:
            self.quit()
            return
        if self.menu is not None:
            self.menu.poll(dt)

    # -- entries -----------------------------------------------------------

    def new_run(self) -> None:
        self.go(RunSetupScene())

    def resume_run(self) -> None:
        """Take the one suspend slot and drop straight back into the run."""
        payload = self.save_system().take_suspend()
        if payload is None:
            self.new_run()
            return
        state = RunState.from_suspend(payload)
        # The effect bag is not stored in the slot; it re-resolves from the
        # profile, which still carries the doctrine the run launched with.
        state.config.modifiers = self.modifiers()
        scene = RunScene(state.config.as_dict())
        scene.resume_state = state
        self.go(scene)

    def open_settings(self) -> None:
        self.go(SettingsScene(back_entry=MENU_ENTRY_SETTINGS))

    def open_doctrine(self) -> None:
        """The Cores door. Named with the balance, so the currency has a purpose."""
        self.go(DoctrineScene(back_factory=lambda: MainMenuScene(focus_entry=MENU_ENTRY_DOCTRINE)))


class RunSetupScene(ShrikeScene):
    """Hull and keystone choice, the two decisions a run launches with."""

    def __init__(self, **kwargs):
        kwargs.setdefault("name", "RunSetup")
        super().__init__(**kwargs)
        self.hull_id = save.STARTER_HULL
        self.keystones: list[str] = []
        self.menu: MenuList | None = None
        #: The answer to the last press, which the hull row needs and the
        #: keystone rows want too: a refusal has to be readable.
        self.status = ""
        self._status: Label | None = None
        self._message: Label | None = None
        self._back: PressLatch | None = None

    # -- choices -----------------------------------------------------------

    def unlocked_hulls(self) -> list[str]:
        hulls = (self.profile().get("hulls") or {}).get("unlocked") or [save.STARTER_HULL]
        return [hull for hull in hulls if hull in balance.HULL_SOCKETS]

    def available_keystones(self) -> list[str]:
        """Keystones the doctrine tree has actually bought."""
        owned = set((self.profile().get("doctrine") or {}).get("owned") or [])
        return [node for node in balance.DOCTRINE_KEYSTONES.values() if node in owned]

    def locked_hulls(self) -> list[str]:
        """The hulls this profile has not earned yet, in catalogue order."""
        unlocked = set(self.unlocked_hulls())
        return [hull for hull in balance.HULL_SOCKETS if hull not in unlocked and hull in HULLS]

    def select_hull(self, hull_id: str) -> None:
        if hull_id not in self.unlocked_hulls():
            raise ValueError(f"hull {hull_id!r} is not unlocked")
        self.hull_id = hull_id
        self._refresh()

    def cycle_hull(self) -> bool:
        """Step to the next unlocked hull. False, and a reason, when there is one.

        The row is a selector, so it has to answer the key that selects. A
        profile with a second hull cycles onto it; a profile with one gets the
        sentence that explains why, because a control that does nothing and
        says nothing reads as a broken control rather than as a locked one.
        """
        hulls = self.unlocked_hulls()
        if len(hulls) <= 1:
            name = HULLS[self.hull_id].title.upper() if self.hull_id in HULLS else self.hull_id.upper()
            locked = len(self.locked_hulls())
            self.status = (
                SETUP_HULL_ONLY.format(name=name, count=locked) if locked else SETUP_HULL_ONLY_ONE.format(name=name)
            )
            self._refresh()
            return False
        index = hulls.index(self.hull_id) if self.hull_id in hulls else -1
        self.hull_id = hulls[(index + 1) % len(hulls)]
        spec = HULLS.get(self.hull_id)
        if spec is not None:
            self.status = SETUP_HULL_PICKED.format(name=spec.title.upper(), description=spec.description)
        self._refresh()
        return True

    def hull_row_text(self) -> str:
        """The selector row: the hull it is on, and whether F can move it."""
        hulls = self.unlocked_hulls()
        spec = HULLS.get(self.hull_id)
        name = spec.title.upper() if spec is not None else self.hull_id.upper()
        sockets = hull_socket_count(self.hull_id)
        if len(hulls) <= 1:
            return SETUP_HULL_ROW.format(name=name, sockets=sockets)
        return SETUP_HULL_ROW_CYCLE.format(name=name, sockets=sockets, count=len(hulls))

    def toggle_keystone(self, node_id: str) -> bool:
        """Arm or disarm a keystone. False when the two slots are already full."""
        if node_id in self.keystones:
            self.keystones.remove(node_id)
            self._refresh()
            return True
        if len(self.keystones) >= balance.DOCTRINE_MAX_ACTIVE_KEYSTONES:
            self._refresh()
            return False
        self.keystones.append(node_id)
        self._refresh()
        return True

    def config(self) -> RunConfig:
        """Freeze the choices, committing them to the doctrine profile first.

        The effect bag is resolved against the selected hull and the armed
        keystones, so the choice has to reach the profile before it is read.
        """
        profile = self.profile()
        meta = self.meta_profile()
        meta.select_hull(self.hull_id)
        meta.set_active_keystones(self.keystones)
        return RunConfig(
            run_number=int(profile.get("runs_started", 0)) + 1,
            seed=random.randrange(1, 2**31),
            hull_id=self.hull_id,
            keystones=tuple(self.keystones),
            modifiers=self.modifiers(),
        )

    def launch(self) -> None:
        self.go(RunScene(self.config().as_dict()))

    # -- screen ------------------------------------------------------------

    def on_ready(self):
        self._back = PressLatch(PAUSE_ACTION)
        hulls = self.unlocked_hulls()
        self.hull_id = (self.profile().get("hulls") or {}).get("selected", hulls[0])
        if self.hull_id not in hulls:
            self.hull_id = hulls[0]
        box = self.build_panel("PREPARE THE RUN", f"at most {balance.DOCTRINE_MAX_ACTIVE_KEYSTONES} keystones")
        self.menu = MenuList(box)
        # One row for the hull, whatever the profile has unlocked. It cycles.
        self.menu.add(self.hull_row_text(), self.cycle_hull)
        for keystone in self.available_keystones():
            self.menu.add(f"KEYSTONE: {keystone.upper()}", _bind(self.toggle_keystone, keystone))
        self.menu.add("LAUNCH", self.launch)
        self.menu.add("BACK", self.back)
        self._status = self.add_line(box, "", dim=True)
        self._message = self.add_line(box, "", dim=True)
        locked = self.locked_hulls()
        if locked:
            self.add_line(box, SETUP_HULL_LOCKED_HEAD, dim=True)
            for hull in locked:
                spec = HULLS[hull]
                row = SETUP_HULL_LOCKED_ROW.format(name=spec.title.upper(), feat=spec.feat or "")
                self.add_line(box, row, dim=True)
        self.add_line(box, MENU_CONTROLS_LINE_BACK, dim=True)
        self._refresh()
        self.settle_panel()

    def back(self) -> None:
        """Return to the front door with the cursor on the row we came in by."""
        self.go(MainMenuScene(focus_entry=MENU_ENTRY_NEW_RUN))

    def on_update(self, dt: float):
        if self._back is not None and self._back.poll(dt)[0]:
            self.back()
            return
        if self.menu is not None:
            self.menu.poll(dt)

    def _refresh(self) -> None:
        if self.menu is not None and self.menu.entries:
            self.menu.relabel(0, self.hull_row_text())
        if self._status is not None:
            armed = ", ".join(self.keystones) if self.keystones else "none"
            self._status.text = f"hull {self.hull_id}, keystones: {armed}"
        if self._message is not None:
            _set_text(self._message, ellipsise(self.status, DEPOT_ROW_CHARS))


class DrawCanvas(Control):
    """A fixed-size surface inside a menu column, drawn on by absolute rects.

    A menu column lays its rows out one under another and measures each of them
    by what it says it needs. That is exactly right for a list and no use at
    all for a diagram, so a screen that wants to *draw* puts one of these in the
    column and places its own controls inside it at coordinates it works out
    itself.

    The one thing this has to do that a bare :class:`Control` does not is
    report its own size as its minimum. Both halves matter. The column sizes a
    row by its minimum, so a canvas that reported nothing would be laid out
    with no height at all; and the panel's fit pass shrinks a column by scaling
    every ``size`` under it, so a minimum read off ``size`` shrinks with it,
    which is what lets a diagram be fitted to a small window by the same one
    pass that fits the rows above and below it.

    Children are added *after* the panel has settled, at the rect the canvas
    finished with. That order is the same one :class:`MenuPanel` documents: a
    control's retained draw bakes the transform it was captured at, so nothing
    may be placed until the thing it is placed inside has stopped moving.
    """

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # A diagram drawn bigger than its window is panned, not shrunk, so the
        # part hanging past the edge has to be cut off rather than drawn over
        # the rows beneath.
        self.clip_contents = True
        # Drawn only. The screen that owns the canvas hit-tests the plates on
        # it against the pointer itself: see build_menu_panel.
        self.pointer_filter = PointerFilter.IGNORE

    def get_minimum_size(self) -> Vec2:
        return Vec2(max(self.size_x, self.min_size_x), max(self.size_y, self.min_size_y))

    def clear(self) -> None:
        """Drop everything drawn on the canvas, ready to be drawn again.

        Hidden before it is destroyed, because the engine's removal is deferred
        to the end of the frame: a redrawn canvas would otherwise paint the old
        drawing and the new one over each other for exactly one frame, which on
        a panning view is a ghost of where it just was.
        """
        for child in list(self.children):
            if isinstance(child, Control):
                child.visible = False
            child.destroy()


def branch_layout(branch_id: str) -> dict[int, tuple[int, int]]:
    """Where each slot of *branch_id* sits on the tree: ``slot -> (tier, lane)``.

    Derived from the prerequisites rather than authored beside them, so the
    drawing cannot disagree with the tree it is drawing. A node's tier is one
    past the deepest thing it requires, which puts every connector on the
    screen pointing down; its lane is 0 when it lies on the route to the
    branch's keystone (the spine) and the next free lane of its tier otherwise
    (the shoulder), which is the fork the branch is actually built around.
    """
    nodes = branch_nodes(branch_id)
    slot_of = {node.id: slot for slot, node in enumerate(nodes)}
    tier: dict[int, int] = {}
    for slot, node in enumerate(nodes):
        tier[slot] = 1 + max((tier[slot_of[required]] for required in node.requires), default=-1)
    keystone = next((slot for slot, node in enumerate(nodes) if node.kind == "keystone"), len(nodes) - 1)
    spine = {slot_of[node_id] for node_id in prerequisites_of(nodes[keystone].id)} | {keystone}
    lane: dict[int, int] = {}
    taken: dict[int, int] = {}
    # The spine first, so it always owns lane 0 and reads as one straight line
    # down the middle of its branch however the shoulder is shaped.
    for slot in sorted(range(len(nodes)), key=lambda index: (tier[index], index not in spine, index)):
        row = tier[slot]
        lane[slot] = 0 if slot in spine else max(1, taken.get(row, 0))
        taken[row] = lane[slot] + 1
    return {slot: (tier[slot], lane[slot]) for slot in range(len(nodes))}


class DoctrineScene(ShrikeScene):
    """The Fleet Doctrine tree: five branches, sixty nodes, drawn as a tree.

    This is where Cores stop being a number on the front door and become a
    build. A grid of five columns of twelve labels, stacked in reading order,
    would be a page of buttons rather than a map: every node would look
    exactly as reachable as every other one, the shape of a branch would be
    invisible, and the only way to find out why a node would not sell would
    be to walk the cursor onto it and read a refusal.

    So the branches are drawn the shape they are built: a spine down the
    cheapest route to the branch's keystone, a shoulder beside it for the rest,
    a row per tier, and a drawn connector from every node to the node that
    unlocks it. The connector lights once its upper end is bought, so the route
    the purse has actually opened is a lit path down the screen. Every node
    carries a state mark as well as a state colour, and the detail block under
    the tree names the cost, the effect and the prerequisite of whatever the
    cursor is on, before a single Core is spent.

    The whole tree is on one screen wherever there is room for it. Where there
    is not, the drawing stops shrinking at :data:`DOCTRINE_MIN_DRAW_SCALE` and
    the view pans under the cursor instead: a tree fitted into a small window by
    scale alone is a diagram nobody can read, and reading it is the point.

    That floor is set by the type and not by taste. The renderer will not put
    text on the glass below :data:`DOCTRINE_CELL_MIN_FONT_PX`, so a plate drawn
    any smaller is a plate shrinking around a caption that is not shrinking with
    it, and the price walks out through the border. Every cell is measured and
    drawn at that one size, the plates are kept wide enough to hold a priced
    line at it, and the gaps between branches and tiers are what paid for the
    width.

    Every control the rest of the game uses works here and nothing new is
    bound. The thrust actions move the cursor, left and right across branches
    and up and down through tiers and on into the three action rows beneath;
    ``interact`` buys what is under the cursor; the pointer selects whatever it
    is over and ``fire_primary`` commits that; and Escape is the way back.

    A purchase is written through the save system the moment it clears, and so
    is a respec, which is free and total by design: the tree is a loadout
    language, not a ratchet.
    """

    #: The rows under the tree, in the order they are drawn.
    ACTIONS: tuple[str, ...] = (DOCTRINE_ACTION_BUY, DOCTRINE_ACTION_RESPEC, DOCTRINE_ACTION_BACK)

    #: The four states a node is in, which are the four things a player needs
    #: to be able to tell apart at a glance.
    STATE_OWNED = DOCTRINE_STATE_OWNED_ID
    STATE_BUYABLE = DOCTRINE_STATE_BUYABLE_ID
    STATE_COSTLY = DOCTRINE_STATE_COSTLY_ID
    STATE_LOCKED = DOCTRINE_STATE_LOCKED_ID

    def __init__(self, *, back_factory=None, **kwargs):
        kwargs.setdefault("name", "Doctrine")
        super().__init__(**kwargs)
        #: What BACK and Escape return to. The ledger hands in a factory that
        #: rebuilds itself, so spending Cores on the way out of a run does not
        #: cost the player the ledger they were still reading.
        self.back_factory = back_factory or MainMenuScene
        self.branch_ids: list[str] = list(BRANCHES)
        self.slots = len(branch_nodes(self.branch_ids[0]))
        #: Where every slot of every branch sits, read off the prerequisites.
        self.layout: dict[str, dict[int, tuple[int, int]]] = {
            branch_id: branch_layout(branch_id) for branch_id in self.branch_ids
        }
        places = [place for branch in self.layout.values() for place in branch.values()]
        self.tiers = 1 + max(tier for tier, _lane in places)
        self.lanes = 1 + max(lane for _tier, lane in places)
        self.branch_index = 0
        #: The tree row the cursor last stood on, kept while the cursor is down
        #: among the action rows so BUY still knows what it is buying.
        self.slot_index = 0
        self.cursor = 0
        self.status = ""

        self._canvas: DrawCanvas | None = None
        self._cells: dict[tuple[int, int], Label] = {}
        self._plates: dict[tuple[int, int], Panel] = {}
        #: Every drawn connector, with the node whose purchase lights it.
        self._links: list[tuple[Panel, str]] = []
        self._headings: list[Label] = []
        self._action_rows: list[Button] = []
        self._detail: list[Label] = []
        self._subtitle: Label | None = None
        self._prereq: Label | None = None
        self._status_row: Label | None = None
        self._pan_row: Label | None = None
        #: How far the drawing is slid inside the canvas, and what the drawing
        #: standing on the canvas right now was placed for. A pan is a rebuild,
        #: never a move: a control's retained draw bakes the transform it was
        #: captured at, so a diagram that slid would paint where it used to be.
        self._pan: tuple[float, float] = (0.0, 0.0)
        self._drawn: tuple[float, float, float, float] | None = None
        #: The measured caption budget, and the room and type size it was
        #: measured for. Sixty cells at every budget is a real walk of the
        #: whole tree, and the tree asks for the answer once a frame.
        self._chars = 1
        self._chars_for: tuple[float, float] | None = None
        self._commit = PressLatch("interact")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._click = PressLatch("fire_primary")
        self._pointer: tuple[float, float] | None = None
        self._leaving = False

    # -- the tree ----------------------------------------------------------

    @property
    def rows(self) -> int:
        """Cursor positions: one per slot, then one per action row."""
        return self.slots + len(self.ACTIONS)

    def content_size(self) -> tuple[float, float]:
        """The tree's own size, in the pixels it is authored at."""
        branch_w = self.lanes * DOCTRINE_NODE_WIDTH_PX + (self.lanes - 1) * DOCTRINE_LANE_GAP_PX
        width = len(self.branch_ids) * branch_w + (len(self.branch_ids) - 1) * DOCTRINE_BRANCH_GAP_PX
        height = (
            DOCTRINE_HEADING_HEIGHT_PX + self.tiers * DOCTRINE_NODE_HEIGHT_PX + (self.tiers - 1) * DOCTRINE_TIER_GAP_PX
        )
        return width, height

    def grid_width(self) -> float:
        """How wide the tree comes out, which is the column's own width."""
        return self.content_size()[0]

    def branch_origin(self, branch_index: int) -> float:
        """The left edge of one branch's lanes, in authored pixels."""
        branch_w = self.lanes * DOCTRINE_NODE_WIDTH_PX + (self.lanes - 1) * DOCTRINE_LANE_GAP_PX
        return branch_index * (branch_w + DOCTRINE_BRANCH_GAP_PX)

    def node_box(self, branch_index: int, slot: int) -> tuple[float, float, float, float]:
        """One node's rect on the drawing, in authored pixels."""
        tier, lane = self.layout[self.branch_ids[branch_index]][slot]
        x = self.branch_origin(branch_index) + lane * (DOCTRINE_NODE_WIDTH_PX + DOCTRINE_LANE_GAP_PX)
        y = DOCTRINE_HEADING_HEIGHT_PX + tier * (DOCTRINE_NODE_HEIGHT_PX + DOCTRINE_TIER_GAP_PX)
        return x, y, DOCTRINE_NODE_WIDTH_PX, DOCTRINE_NODE_HEIGHT_PX

    def branch_id(self) -> str:
        return self.branch_ids[self.branch_index]

    def node_at(self, branch_index: int, slot: int) -> DoctrineNode:
        """The node in one branch's slot, which is where the tree draws it."""
        return branch_nodes(self.branch_ids[branch_index])[slot]

    def selected_node(self) -> DoctrineNode:
        """The node the detail block is describing and BUY would buy."""
        return self.node_at(self.branch_index, self.slot_index)

    def selected_action(self) -> str:
        """The action row under the cursor, empty while the cursor is on the tree."""
        if self.cursor < self.slots:
            return ""
        return self.ACTIONS[self.cursor - self.slots]

    def cores(self) -> int:
        return self.meta_profile().cores()

    def cell_lines(self, node: DoctrineNode, chars: int | None = None) -> tuple[str, str]:
        """*node*'s caption over the two lines its own cell prints it on.

        Ten lanes of nodes across a 1280-pixel window leave a couple of dozen
        characters a cell at the one size the renderer will draw, and a priced
        title runs past that often enough to matter. One line would mean cutting
        them ("Ammunition Sov... 40"), which throws away the branch's own
        vocabulary and keeps its punctuation. So the title wraps: whole words
        onto the first line, the rest onto the second with the price after it.

        The whole name goes on the first line whenever it fits, which leaves
        the price the second line to itself and is how all but the longest
        title in the tree reads: a name, then "NN Cores" under it. A title too
        long for one line takes its last words down with the price beside them,
        because the alternative at this size is cutting the name.

        The price is a token, never a loose number: "40 Cores" goes on whole or
        the line makes room for it. Reserving the digits alone would be enough
        to strand one cell reading "Sovereignty 40" in a column of siblings all
        reading "NN Cores", which prices nothing and looks like a stat. The
        room comes out of the second line's indent first (:func:`_cell_indent`)
        and only then out of the name, which is why nothing in this tree is cut
        at either 1280x720 or the 800x500 the pan floor takes over at.
        """
        if chars is None:
            chars = self.cell_chars()
        cost = DOCTRINE_CELL_COST.format(cost=node.cost)
        head_room = max(1, chars - DOCTRINE_CELL_MARK_CHARS)
        head = ""
        rest: list[str] = []
        for word in str(node.title).split():
            candidate = f"{head} {word}" if head else word
            if rest or (head and len(candidate) > head_room):
                rest.append(word)
            else:
                head = candidate
        tail = " ".join(rest)
        if not tail:
            # A title that fitted on one line leaves the price the whole
            # second, so it says what the number is rather than sitting there
            # as one.
            return ellipsise(head, head_room), cost
        # The name gives way to the price and not the other way round, and it
        # gives way against the whole cell, because the indent has already gone
        # by the time this bites.
        return ellipsise(head, head_room), f"{ellipsise(tail, max(1, chars - len(cost) - 1))} {cost}"

    def cell_text(self, branch_index: int, slot: int) -> str:
        """One cell's whole caption, both its lines joined, as it reads on screen."""
        cell = self._cells.get((branch_index, slot))
        if cell is None:
            return ""
        return " ".join(line.strip() for line in str(cell.text).split("\n") if line.strip())

    def cell_font(self) -> float:
        """The size a cell's caption is laid out at, which is the size it is drawn at.

        The renderer will not put type on the glass below
        :data:`DOCTRINE_CELL_MIN_FONT_PX`: asked for less it silently draws
        that instead. A tree that asked for ten points times its draw scale
        would therefore measure its captions a quarter narrower than they are
        painted, and draw a price through a plate's border while the layout
        believed the line had room. The floor is taken here
        instead, so what the cell budgets and what the cell shows are one size.
        """
        return max(DOCTRINE_CELL_MIN_FONT_PX, DOCTRINE_CELL_FONT_PX * self.draw_scale())

    def cell_room(self) -> float:
        """The drawn width a caption has inside its plate, in pixels."""
        return max(1.0, (DOCTRINE_NODE_WIDTH_PX - 2.0 * DOCTRINE_NODE_PAD_PX) * self.draw_scale())

    def cell_chars(self) -> int:
        """How many characters a node's cell holds at the drawn scale.

        Measured against the font rather than estimated from an average
        advance. An estimate is wrong in both directions at once: it takes the
        type to be smaller than the renderer will draw and every glyph to be
        wider than this face's letters are, and the two errors do not cancel.
        What the cell needs to know is whether the widest line the whole tree
        would print at a given budget fits between one plate's borders, and the
        font can answer exactly that, so the budget is the largest one whose
        answer is yes.

        Searched downward from :data:`DOCTRINE_CELL_CHARS_MAX` rather than
        solved, because the caption's own wrapping is not monotonic in the
        budget: one more character can lift a whole word onto the first line
        and leave the second line shorter than it was. The answer is cached
        against the room and the size it was found for, since it changes only
        when the window does and the tree asks for it on every frame.
        """
        room, font = self.cell_room(), self.cell_font()
        key = (round(room, 3), round(font, 3))
        if self._chars_for != key:
            self._chars_for = key
            self._chars = self._fitted_chars(room, font)
        return self._chars

    def _fitted_chars(self, room: float, font: float) -> int:
        """The widest caption budget every cell in the tree still fits inside."""
        marks = max(
            (f"{cursor}{mark}" for cursor in (DOCTRINE_MARK_CURSOR, " ") for mark in DOCTRINE_STATE_MARKS.values()),
            key=lambda text: measure_text_width(text, font / LOGICAL_EM),
        )
        for chars in range(DOCTRINE_CELL_CHARS_MAX, 1, -1):
            if self._caption_width(chars, marks, font) <= room:
                return chars
        return 1

    def _caption_width(self, chars: int, marks: str, font: float) -> float:
        """The widest line any cell would draw at this budget, in pixels."""
        widest = 0.0
        for branch_index in range(len(self.branch_ids)):
            for slot in range(self.slots):
                head, tail = self.cell_lines(self.node_at(branch_index, slot), chars)
                for line in (f"{marks} {head}", f"{' ' * _cell_indent(tail, chars)}{tail}"):
                    widest = max(widest, measure_text_width(line, font / LOGICAL_EM))
        return widest

    def node_state(self, node: DoctrineNode) -> str:
        """Which of the four states *node* is in, for the mark and the colour.

        The rules are ``meta.MetaProfile``'s; all that is decided here is which
        of its refusals is worth its own colour. "You cannot afford this yet"
        and "this is locked behind something else" are different problems with
        different answers, and a screen that greyed both the same way would
        tell a player with a full purse to go and find more Cores.
        """
        meta = self.meta_profile()
        if meta.is_owned(node.id):
            return self.STATE_OWNED
        if not meta.feat_met(node.feat) or any(not meta.is_owned(required) for required in node.requires):
            return self.STATE_LOCKED
        return self.STATE_BUYABLE if meta.cores() >= node.cost else self.STATE_COSTLY

    # -- moving ------------------------------------------------------------

    def move_cursor(self, step: int) -> None:
        """Step the cursor down (or up) through tiers and the action rows."""
        self.cursor = (self.cursor + int(step)) % self.rows
        if self.cursor < self.slots:
            self.slot_index = self.cursor

    def move_branch(self, step: int) -> None:
        """Step sideways to another branch, keeping the tier."""
        self.branch_index = (self.branch_index + int(step)) % len(self.branch_ids)

    def place_cursor(self, branch_index: int, cursor: int) -> None:
        """Put the cursor exactly here, which is what a pointer does."""
        self.branch_index = max(0, min(len(self.branch_ids) - 1, int(branch_index)))
        self.cursor = max(0, min(self.rows - 1, int(cursor)))
        if self.cursor < self.slots:
            self.slot_index = self.cursor

    # -- spending ----------------------------------------------------------

    def buy_selected(self) -> bool:
        """Buy the node under the cursor. False, and a reason, when it refuses."""
        node = self.selected_node()
        meta = self.meta_profile()
        blocker = meta.purchase_blocker(node.id)
        if blocker is not None:
            self.status = f"{node.title.upper()}: {blocker}"
            self._refresh()
            return False
        meta.buy_node(node.id)
        self.save_system().save_profile(self.profile())
        self.status = DOCTRINE_BOUGHT.format(title=node.title.upper(), cost=node.cost)
        self._refresh()
        return True

    def respec_all(self) -> int:
        """Refund the whole tree. Free, total, and written out at once."""
        refund = self.meta_profile().respec()
        self.save_system().save_profile(self.profile())
        self.status = DOCTRINE_RESPEC_DONE.format(refund=refund) if refund > 0 else DOCTRINE_RESPEC_EMPTY
        self._refresh()
        return refund

    def back(self) -> None:
        """Leave for whatever opened this screen."""
        self._leaving = True
        self.go(self.back_factory())

    def commit(self) -> bool:
        """Run whatever the cursor is on."""
        action = self.selected_action()
        if action in ("", DOCTRINE_ACTION_BUY):
            return self.buy_selected()
        if action == DOCTRINE_ACTION_RESPEC:
            self.respec_all()
            return True
        self.back()
        return True

    # -- screen ------------------------------------------------------------

    def on_ready(self):
        # Adopt any handed-in profile before a single node is priced: the tree
        # is drawn from Cores, and Cores live on the profile.
        self.profile()
        # A column lays its children out at its own width, so the drawing's
        # width has to reach the column rather than only the panel around it.
        box = self.build_panel("FLEET DOCTRINE", width=self.grid_width())
        self._subtitle = self.add_line(box, "", dim=True)
        # Directly under the balance, because this is the screen a player
        # reaches holding nought and is quoted fifteen for the cheapest node.
        # Wrapped to the grid rather than laid out as one row: a column grows to
        # fit its widest child, and one long generated sentence is enough to
        # push the whole panel out through the side of a small window.
        for line in wrap_prose(cores_source_line(self.profile()), MENU_LINE_FONT_PX, self.grid_width()):
            self.add_line(box, line, dim=True)

        width, height = self.content_size()
        self._canvas = box.add_child(DrawCanvas(name="Tree", size_x=width, size_y=height))

        for _ in range(2):
            line = self.add_line(box, "")
            line.font_size = DOCTRINE_DETAIL_FONT_PX
            self._detail.append(line)
        self._prereq = self.add_line(box, "", dim=True)
        self._prereq.font_size = DOCTRINE_DETAIL_FONT_PX
        state = self.add_line(box, "")
        state.font_size = DOCTRINE_DETAIL_FONT_PX
        self._detail.append(state)

        for action in self.ACTIONS:
            row = box.add_child(Button(action, size_x=self.grid_width(), size_y=MENU_ROW_HEIGHT_PX))
            # Drawn furniture this screen hit-tests itself, alongside the
            # plates, which are panels. See MenuList for why a row that claims
            # the press is a row nothing can click.
            row.pointer_filter = PointerFilter.IGNORE
            self._action_rows.append(row)
        self._status_row = self.add_line(box, "", dim=True)
        self.add_line(box, DOCTRINE_LEGEND_LINE, dim=True)
        self._pan_row = self.add_line(box, "", dim=True)
        self.add_line(box, DOCTRINE_CONTROLS_LINE, dim=True)
        self.settle_panel()
        # Only now is the canvas standing at the rect it will keep, which is
        # the rect the tree is drawn against.
        self._draw_tree()

    def on_update(self, dt: float):
        if self._leaving:
            return
        if Input.just_pressed(PAUSE_ACTION):
            self.back()
            return

        if Input.just_pressed("thrust_down") or Input.just_pressed(MENU_DOWN_ACTION):
            self.move_cursor(1)
        elif Input.just_pressed("thrust_up") or Input.just_pressed(MENU_UP_ACTION):
            self.move_cursor(-1)
        if Input.just_pressed("thrust_right"):
            self.move_branch(1)
        elif Input.just_pressed("thrust_left"):
            self.move_branch(-1)

        under, moved = self._pointed_at()
        if under is not None and moved:
            self.place_cursor(*under)
        pressed, _ = self._commit.poll(dt)
        confirmed, _ = self._confirm.poll(dt)
        clicked, _ = self._click.poll(dt)
        if clicked and under is not None:
            # A click commits what the pointer is over, whatever the keyboard
            # cursor was doing: the mouse does not have to move first.
            self.place_cursor(*under)
        if pressed or confirmed or (clicked and under is not None):
            self.commit()
        if self._leaving:
            return
        self._draw_tree()
        self._refresh()

    # -- pointing ----------------------------------------------------------

    def _pointed_at(self) -> tuple[tuple[int, int] | None, bool]:
        """What the pointer is over, and whether it has moved since last frame.

        Only a pointer that moved takes the cursor: a mouse left resting over a
        node must not fight the keyboard for it. A click commits what the
        pointer is over either way. A node half off the edge of a panned view
        answers only over the part of it that is actually drawn.
        """
        position = Input.mouse_position
        point = (float(position.x), float(position.y))
        moved = self._pointer is not None and point != self._pointer
        self._pointer = point
        canvas = self._canvas
        if canvas is not None and _rect_holds(canvas.get_global_rect(), point):
            for (branch_index, slot), plate in self._plates.items():
                if _rect_holds(plate.get_global_rect(), point):
                    return (branch_index, slot), moved
        for index, row in enumerate(self._action_rows):
            if _rect_holds(row.get_global_rect(), point):
                return (self.branch_index, self.slots + index), moved
        return None, moved

    # -- drawing -----------------------------------------------------------

    def draw_scale(self) -> float:
        """What the tree is drawn at: the canvas's own scale, with a floor.

        The panel has already fitted the whole column to the window, and the
        canvas came out of that fit at some fraction of the size it was
        authored at. Down to :data:`DOCTRINE_MIN_DRAW_SCALE` the drawing simply
        takes that fraction. Past it the drawing keeps the floor and hangs out
        of its own canvas, which is what the pan is for.
        """
        canvas = self._canvas
        if canvas is None:
            return 1.0
        _, _, view_w, view_h = (float(value) for value in canvas.get_global_rect())
        width, height = self.content_size()
        fitted = min(view_w / max(1.0, width), view_h / max(1.0, height))
        return max(min(1.0, fitted), DOCTRINE_MIN_DRAW_SCALE)

    def panning(self) -> bool:
        """Whether the drawing is larger than the canvas it is drawn on."""
        canvas = self._canvas
        if canvas is None:
            return False
        _, _, view_w, view_h = (float(value) for value in canvas.get_global_rect())
        scale = self.draw_scale()
        width, height = self.content_size()
        return width * scale > view_w + 1.0 or height * scale > view_h + 1.0

    def _pan_for_cursor(self, scale: float, view_w: float, view_h: float) -> tuple[float, float]:
        """Where the drawing has to sit for the focused node to be on screen."""
        width, height = (value * scale for value in self.content_size())
        x, y, node_w, node_h = self.node_box(self.branch_index, self.slot_index)
        pan_x = self._slide(self._pan[0], x * scale, (x + node_w) * scale, view_w, width)
        pan_y = self._slide(self._pan[1], y * scale, (y + node_h) * scale, view_h, height)
        return pan_x, pan_y

    @staticmethod
    def _slide(pan: float, near: float, far: float, view: float, content: float) -> float:
        """One axis of the pan: the least movement that shows ``near..far``."""
        if content <= view:
            return 0.0
        if -pan > near:
            pan = -near
        if -pan + view < far:
            pan = view - far
        return min(0.0, max(view - content, pan))

    def _draw_tree(self) -> None:
        """Place the branches, the connectors and the nodes on the canvas.

        Called once on mount and again only when the canvas has resized or the
        pan has moved, because it destroys everything it drew last time: a
        diagram is rebuilt rather than slid, for the same reason a menu column
        is placed once and never moves.
        """
        canvas = self._canvas
        if canvas is None:
            return
        _, _, view_w, view_h = (float(value) for value in canvas.get_global_rect())
        if view_w <= 1.0 or view_h <= 1.0:
            return
        scale = self.draw_scale()
        pan = self._pan_for_cursor(scale, view_w, view_h)
        drawn = (view_w, view_h, pan[0], pan[1])
        if drawn == self._drawn:
            return
        self._pan = pan
        self._drawn = drawn
        canvas.clear()
        self._cells.clear()
        self._plates.clear()
        self._links.clear()
        self._headings.clear()

        font = self.cell_font()
        heading_font = font * DOCTRINE_HEADING_FONT_MULT
        branch_w = (self.lanes * DOCTRINE_NODE_WIDTH_PX + (self.lanes - 1) * DOCTRINE_LANE_GAP_PX) * scale
        for branch_index, branch_id in enumerate(self.branch_ids):
            x = self.branch_origin(branch_index) * scale + pan[0]
            heading = self._text(
                BRANCHES[branch_id].title.upper(),
                x,
                pan[1],
                branch_w,
                DOCTRINE_HEADING_HEIGHT_PX * scale,
                heading_font,
                MENU_TITLE_COLOUR,
            )
            heading.alignment = "centre"
            self._headings.append(heading)
            self._draw_links(branch_index, scale, pan)
            self._draw_nodes(branch_index, scale, pan, font, view_w, view_h)
        self._refresh()

    def _draw_links(self, branch_index: int, scale: float, pan: tuple[float, float]) -> None:
        """A line from every node to the node that unlocks it."""
        nodes = branch_nodes(self.branch_ids[branch_index])
        slot_of = {node.id: slot for slot, node in enumerate(nodes)}
        thickness = max(1.0, DOCTRINE_LINK_WIDTH_PX * scale)
        for slot, node in enumerate(nodes):
            x, y, width, _height = (value * scale for value in self.node_box(branch_index, slot))
            head_x, head_y = x + width / 2.0 + pan[0], y + pan[1]
            for required in node.requires:
                px, py, pw, ph = (value * scale for value in self.node_box(branch_index, slot_of[required]))
                foot_x, foot_y = px + pw / 2.0 + pan[0], py + ph + pan[1]
                middle = (foot_y + head_y) / 2.0
                self._link(foot_x - thickness / 2.0, foot_y, thickness, middle - foot_y, required)
                if abs(head_x - foot_x) > thickness:
                    left, right = min(head_x, foot_x), max(head_x, foot_x)
                    self._link(left, middle - thickness / 2.0, right - left, thickness, required)
                self._link(head_x - thickness / 2.0, middle, thickness, head_y - middle, required)

    def _draw_nodes(
        self, branch_index: int, scale: float, pan: tuple[float, float], font: float, view_w: float, view_h: float
    ) -> None:
        """One plate and one line of type per node, where the branch puts it."""
        for slot in range(self.slots):
            x, y, width, height = (value * scale for value in self.node_box(branch_index, slot))
            x, y = x + pan[0], y + pan[1]
            if x < -0.5 or y < -0.5 or x + width > view_w + 0.5 or y + height > view_h + 0.5:
                # Off the canvas, or only half on it. Not drawn at all: a
                # control outside its parent's rect is still a control the
                # pointer can find, and half a node hanging over the edge is a
                # plate painted across whatever the canvas was standing on.
                # The pan always brings the focused node wholly inside first,
                # so nothing the cursor can reach is dropped by this.
                continue
            plate = self._place(Panel(), x, y, width, height)
            plate.bg_colour = DOCTRINE_NODE_OPEN_FILL
            plate.border_colour = DOCTRINE_NODE_EDGE_COLOUR
            plate.border_width = max(1.0, DOCTRINE_BORDER_PX * scale)
            pad = DOCTRINE_NODE_PAD_PX * scale
            # One label, two lines: the engine stacks an embedded newline on a
            # 1.2 pitch and centres the block, so the caption sits on the plate
            # at any scale without a second control to keep in step. The label
            # is taller than the plate and centred on it, per DOCTRINE_CELL_ROOM_PX.
            room = height + DOCTRINE_CELL_ROOM_PX * scale
            label = self._text(
                "", x + pad, y - (room - height) / 2.0, max(1.0, width - 2.0 * pad), room, font, MENU_TEXT_COLOUR
            )
            self._plates[(branch_index, slot)] = plate
            self._cells[(branch_index, slot)] = label

    def _link(self, x: float, y: float, width: float, height: float, required: str) -> None:
        """One segment of a connector, remembered by what lights it."""
        if width <= 0.0 or height <= 0.0:
            return
        panel = self._place(Panel(), x, y, width, height)
        panel.bg_colour = DOCTRINE_LINK_COLOUR
        self._links.append((panel, required))

    def _place(self, control: Control, x: float, y: float, width: float, height: float) -> Control:
        """Mount *control* on the canvas at a rect it keeps for its whole life."""
        control.margin_left, control.margin_top = float(x), float(y)
        control.size_x, control.size_y = float(width), float(height)
        control.pointer_filter = PointerFilter.IGNORE
        return self._canvas.add_child(control)

    def _text(self, text: str, x: float, y: float, width: float, height: float, font: float, colour=None) -> Label:
        """One placed line of type, never smaller than the engine will draw."""
        label = Label(text, size_x=width, size_y=height)
        self._place(label, x, y, width, height)
        label.font_size = _refit_font(font)
        label.text_colour = Colour.coerce(colour or MENU_TEXT_COLOUR, name="doctrine")
        return label

    def _refresh(self) -> None:
        meta = self.meta_profile()
        if self._subtitle is not None:
            _set_text(
                self._subtitle,
                DOCTRINE_SUBTITLE.format(
                    cores=meta.cores(),
                    spent=meta.spent_cores(),
                    active=len(meta.active_keystones()),
                    max_active=balance.DOCTRINE_MAX_ACTIVE_KEYSTONES,
                    owned=len(meta.owned_keystones()),
                ),
            )
        chars = self.cell_chars()
        for (branch_index, slot), cell in self._cells.items():
            node = self.node_at(branch_index, slot)
            state = self.node_state(node)
            on_cursor = branch_index == self.branch_index and self.cursor == slot
            marks = (DOCTRINE_MARK_CURSOR if on_cursor else " ") + DOCTRINE_STATE_MARKS[state]
            head, tail = self.cell_lines(node, chars)
            # The second line is indented past the marks, so it sits under the
            # title rather than under the state mark that owns the first, and
            # it gives that indent back rather than the price when it is full.
            _set_text(cell, f"{marks} {head}\n{' ' * _cell_indent(tail, chars)}{tail}")
            cell.text_colour = Colour.coerce(DOCTRINE_STATE_COLOURS[state], name="node")
            plate = self._plates[(branch_index, slot)]
            plate.bg_colour = DOCTRINE_STATE_FILLS[state]
            if on_cursor:
                plate.border_colour = DOCTRINE_CURSOR_COLOUR
            elif node.kind == "keystone":
                plate.border_colour = DOCTRINE_KEYSTONE_COLOUR
            else:
                plate.border_colour = DOCTRINE_NODE_EDGE_COLOUR
        for panel, required in self._links:
            panel.bg_colour = DOCTRINE_LINK_LIT_COLOUR if meta.is_owned(required) else DOCTRINE_LINK_COLOUR

        node = self.selected_node()
        blocker = meta.purchase_blocker(node.id)
        branch = BRANCHES[self.branch_ids[self.branch_index]]
        if self._detail:
            _set_text(self._detail[0], f"{node.title} ({branch.title}, {node.kind}, {node.cost} Cores)")
            _set_text(self._detail[1], node.description)
            if meta.is_owned(node.id):
                state = DOCTRINE_STATE_OWNED
            elif blocker is None:
                state = DOCTRINE_STATE_BUYABLE.format(cost=node.cost)
            elif meta.feat_met(node.feat) and any(not meta.is_owned(required) for required in node.requires):
                state = DOCTRINE_STATE_PRICED.format(cost=node.cost, cores=meta.cores())
            else:
                state = blocker.upper()
            _set_text(self._detail[2], state)
        if self._prereq is not None:
            names = ", ".join(DOCTRINE_TREE[required].title for required in node.requires)
            _set_text(self._prereq, DOCTRINE_REQUIRES_LINE.format(names=names) if names else DOCTRINE_REQUIRES_NONE)
        for index, row in enumerate(self._action_rows):
            on_cursor = self.cursor == self.slots + index
            _set_text(row, f"{DOCTRINE_MARK_CURSOR if on_cursor else ' '} {self.ACTIONS[index]}")
        if self._status_row is not None:
            _set_text(self._status_row, self.status)
        if self._pan_row is not None:
            _set_text(self._pan_row, DOCTRINE_PAN_NOTE if self.panning() else "")


class PauseScene(Control):
    """The in-run pause overlay: resume, settings, or abandon the run.

    An overlay rather than a root scene, despite its name:
    the run has to still be standing behind it for Resume to mean anything, so
    this is a child of :class:`RunScene` that holds the tree still, exactly the
    way :class:`~shrike.chart.StarChart` does. It runs on ``UpdateMode.ALWAYS``
    for the same reason the chart does: the screen that owns the pause is the
    only one that can lift it.

    Escape raises it and Escape lifts it. Nothing here ends the run except
    Abandon Run, which is worded as what it is and settles the hold at the
    death rate on the ledger, so backing out of the game never costs a sector
    jump the player did not ask for.
    """

    update_mode = Property(
        UpdateMode.ALWAYS,
        hint="Processing behaviour while the tree is paused",
        on_change="_invalidate_update_mode_cache",
    )

    def __init__(self, run: RunScene, **kwargs):
        kwargs.setdefault("name", "Pause")
        super().__init__(**kwargs)
        self.run = run
        self.menu: MenuList | None = None
        self._open = False
        self._box: VBoxContainer | None = None
        self._backdrop: Panel | None = None
        self._fit_rows: list[Label] = []
        #: The chart's update mode while this is not holding it shut.
        self._chart_update_mode: UpdateMode | None = None

    def on_ready(self):
        self.anchor = Anchor.FULL_RECT
        # The overlay is the host its panel hangs off, not a thing to click:
        # the menu hit-tests its own rows and reads ``fire_primary``, so a
        # press this control claimed would never reach the action that runs
        # the row.
        self.pointer_filter = PointerFilter.IGNORE
        self._build()
        self.visible = False

    def _build(self) -> None:
        """Mount the panel for this pause, rows and fit panel together.

        Rebuilt on every open rather than topped up: the fit changes between
        pauses, and a panel that grows after its rows are placed moves every
        one of them out from under its own retained draw.
        """
        if self._backdrop is not None:
            self._backdrop.destroy()
        self._fit_rows = []
        box = build_menu_panel(self, "PAUSED", "the run is holding its breath")
        self._backdrop = menu_panel_of(self).parent
        self.menu = MenuList(box)
        self.menu.add("RESUME", self.close)
        self.menu.add("SETTINGS", self.open_settings)
        self.menu.add("ABANDON RUN", self.abandon)
        add_menu_line(box, MENU_CONTROLS_LINE_BACK, dim=True)
        self._box = box
        self._show_fit()
        settle_menu_panel(self)

    def resource_line(self) -> str:
        """The HUD's resource strip, as one line, or empty when there is none.

        Read off the HUD rather than off the tanks: the paused panel and the
        flying HUD must be two views of one reading, never two readings.
        """
        hud = self.run.hud
        cells = hud.resource_lines() if hud is not None else ()
        return PAUSE_RESOURCE_SEPARATOR.join(cells)

    def _show_fit(self) -> None:
        """Mirror the dock's FIT panel, read-only, under the menu rows.

        The pause is the one place a pilot can see what is bolted to their
        ship without a bay in the sector, so the same three blocks the dock
        prints are written here on every open: the fit changes between pauses
        and the block lengths change with it.

        The hold, the tank and the air go above it, because the pause is also
        where a pilot works out whether the next jump is affordable, which a
        panel itemising every bolt on the hull without saying how much scrap
        was in it could not answer.
        """
        if self._box is None:
            return
        run = self.run
        resources = self.resource_line()
        if resources:
            label = add_menu_line(self._box, resources)
            label.font_size = DEPOT_ROW_FONT_PX
            self._fit_rows.append(label)
        for line in fit_panel_lines(run.rack, run.sockets, run.stowed_weapons, run.stowed_modules):
            label = add_menu_line(self._box, line, dim=True)
            label.font_size = DEPOT_ROW_FONT_PX
            self._fit_rows.append(label)

    @property
    def is_open(self) -> bool:
        return self._open

    # -- opening and closing ----------------------------------------------

    def open(self) -> None:
        """Raise the overlay and halt the simulation behind it."""
        if self._open:
            return
        self._open = True
        self.visible = True
        self._build()
        if self.menu is not None:
            self.menu.reset()
        chart = self.run.chart_screen
        if chart is not None:
            # The chart also runs while paused and also answers to a key. It
            # must not act on M from underneath this, so it is shut for the
            # duration and put back exactly as it was found: run one leaves it
            # disabled and a resume has to leave it disabled too.
            self._chart_update_mode = chart.update_mode
            chart.update_mode = UpdateMode.DISABLED
        if self.tree is not None:
            self.tree.paused = True

    def close(self) -> None:
        """Drop the overlay and let the run breathe again."""
        if not self._open:
            return
        self._open = False
        self.visible = False
        chart = self.run.chart_screen
        if chart is not None and self._chart_update_mode is not None:
            chart.update_mode = self._chart_update_mode
        self._chart_update_mode = None
        if self.tree is not None:
            self.tree.paused = False

    def toggle(self) -> None:
        self.close() if self._open else self.open()

    # -- entries -----------------------------------------------------------

    def open_settings(self) -> None:
        """Park the run in its suspend slot and open the options screen.

        The run cannot survive a ``change_scene``, so the way back to it is the
        slot the menu already resumes from: settings, then Back, then Resume
        Run puts the pilot down where they left off with the hold intact.
        """
        self.close()
        self.run.suspend()
        # Backing out of settings lands on the front door, and the row the
        # pilot wants there is the one that puts them back in the run.
        self.run.leave_for(SettingsScene(back_entry=MENU_ENTRY_RESUME))

    def abandon(self) -> None:
        """End the run deliberately. The ledger prices the hold as a death."""
        self.close()
        self.run.end_run("death", killed_by="abandoned")

    # -- frame -------------------------------------------------------------

    def on_update(self, dt: float):
        chart = self.run.chart_screen
        shop = self.run.depot_screen
        refit = self.run.refit_screen
        if Input.just_pressed(PAUSE_ACTION):
            if not self._open and refit is not None and refit.is_open:
                # The refit panel backs out to the shelf it was raised from,
                # and closes itself on the same press: nothing else may read it.
                return
            if not self._open and shop is not None and shop.is_open:
                # Escape backs out of whatever is up, and the dock screen is.
                # Backing out of a bay means leaving it, not abandoning the
                # pilot inside a shop with nothing on the screen.
                shop.undock()
                return
            if not self._open and chart is not None and chart.is_open:
                # Escape backs out of whatever is up, and the chart is up.
                chart.close()
                return
            self.toggle()
            return
        if self._open and self.menu is not None:
            self.menu.poll(dt)


class DepotScene(Control):
    """The dock screen: the shelf as a grid of cards, the offer, and the way out.

    The bay has six items and a pity slot rolled against the build being
    flown, a reroll that doubles, and a standing offer on the hold, and the
    screen puts all three in reach. A list is not a shop: an item written as
    one sentence a hundred and fifty characters long, carrying a name, a
    category, a price, the mount it would take, its mechanical summary and its
    state, in that order, on one line, puts the price in the middle of the
    line and the reason a thing cannot be bought at the end of it, past
    everything else.

    So the shelf is a grid of cards, two across. A card answers the three
    questions in the order they are asked: what is this and what does it cost,
    what does it do, and can I have it. The third line is never blank (it is
    a verb, a shortfall in scrap, or the hull's own refusal), and a card the
    hold cannot pay for is drawn on a darker plate in dimmer type as well as
    saying how short it is, because a grey card alone only informs a player who
    already knows what the greying means.

    A purchase says what it changed rather than what it cost. The hull is read
    before and after the payment, so a gun that went onto a bare hardpoint, a
    module that went into a socket and a gun that went into the locker are
    three different sentences; and the locker case names the refit row, which
    grows a label of its own until the thing is mounted. That is the handoff
    the shelf owes: a weapon that is bought and stowed does nothing at all
    until somebody mounts it, and the bay is the only place it can be mounted.

    Under everything sits the FIT panel, the full statement of what is bolted
    where, so a card promising a mount can be checked in place.

    An overlay rather than a scene, like :class:`PauseScene`: the run has to be
    standing behind it for undocking to put the pilot back where they were. It
    holds the tree still and drives the depot's own interact ladder by hand
    while it does, so the three-second sell hold the world spent the run
    teaching keeps working with the screen up; a tap of the same key is the
    screen's confirm, and the bay is left through its own row or through
    Escape.
    """

    # It runs while it holds the tree still, for the same reason the chart does:
    # the screen that owns the pause is the only one that can lift it.
    update_mode = Property(
        UpdateMode.ALWAYS,
        hint="Processing behaviour while the tree is paused",
        on_change="_invalidate_update_mode_cache",
    )

    #: The rows under the shelf, in the order they are drawn.
    ACTION_REFIT = "refit"
    ACTION_SELL = "sell"
    ACTION_REROLL = "reroll"
    ACTION_UNDOCK = "undock"
    ACTIONS: tuple[str, ...] = (ACTION_REFIT, ACTION_SELL, ACTION_REROLL, ACTION_UNDOCK)

    def __init__(self, run: RunScene, **kwargs):
        kwargs.setdefault("name", "DepotScreen")
        super().__init__(**kwargs)
        self.run = run
        # It reads the pointer itself and never eats a shot while it is closed.
        self.pointer_filter = PointerFilter.IGNORE
        self.depot: Depot | None = None
        #: The Doctrine Kit choice, above the shelf until the profile has picked.
        self.kits: list[str] = []
        self.items: list[dict] = []
        self.cursor = 0
        self.status = ""

        self._open = False
        self._rebuild = False
        self._backdrop: Panel | None = None
        self._subtitle: Label | None = None
        self._detail_row: Label | None = None
        self._status_row: Label | None = None
        self._kit_rows: list[Button] = []
        #: One plate per shelf card, and the three lines written on it.
        self._item_rows: list[Panel] = []
        self._item_lines: list[tuple[Label, Label, Label]] = []
        self._shelf: DrawCanvas | None = None
        self._action_rows: list[Button] = []
        self._fit_rows: list[Label] = []
        #: How many characters a card's line holds, at the size it came out.
        self._card_chars = DEPOT_ROW_CHARS // DEPOT_GRID_COLUMNS
        #: Whether this window had the room to print the FIT panel at all.
        self._fit_visible = True
        #: Whether a purchase this visit has put something in the locker, which
        #: is what turns the refit row into an instruction rather than a door.
        self._refit_waiting = False
        self._commit = PressLatch("interact")
        self._click = PressLatch("fire_primary")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._pointer: tuple[float, float] | None = None
        self._banked_mark = 0.0
        #: The chart's update mode while this is not holding it shut.
        self._chart_update_mode: UpdateMode | None = None

    def on_ready(self):
        self.anchor = Anchor.FULL_RECT
        self.visible = False

    @property
    def is_open(self) -> bool:
        return self._open

    # -- opening and closing ----------------------------------------------

    def open(self, depot: Depot) -> None:
        """Show *depot*'s shelf and hold the run still behind it."""
        if self._open:
            return
        self.depot = depot
        self.kits = self.run.kit_offers()
        self.items = self.shelf()
        self.cursor = 0
        self.status = ""
        self._refit_waiting = False
        self._open = True
        self._rebuild = True
        self.visible = True
        # Primed now, so the press that docked cannot also buy row one.
        self.reprime()
        economy = self.run.economy
        self._banked_mark = float(getattr(economy, "cores_banked_this_run", 0.0)) if economy else 0.0
        chart = self.run.chart_screen
        if chart is not None:
            # The chart also runs while paused and also answers to a key. Left
            # live it would open over the shelf and, worse, lift the pause on
            # its way out and set the run flying behind a screen still up. It
            # is shut for the duration and put back exactly as it was found.
            self._chart_update_mode = chart.update_mode
            chart.update_mode = UpdateMode.DISABLED
        if self.tree is not None:
            self.tree.paused = True

    def reprime(self) -> None:
        """Re-arm the press latches to whatever is held right now.

        Called on every open, and again whenever the refit panel hands the bay
        back: the key that closed the panel is still down on the frame the
        shelf resumes reading it, and unprimed it would buy row one.
        """
        self._commit = PressLatch("interact")
        self._click = PressLatch("fire_primary")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._pointer = None

    def close(self) -> None:
        """Drop the screen and let the run breathe again."""
        if not self._open:
            return
        refit = self.run.refit_screen
        if refit is not None:
            refit.close()
        self._open = False
        self.visible = False
        self.depot = None
        self.kits = []
        self.items = []
        chart = self.run.chart_screen
        if chart is not None and self._chart_update_mode is not None:
            chart.update_mode = self._chart_update_mode
        self._chart_update_mode = None
        if self._backdrop is not None:
            self._backdrop.destroy()
            self._backdrop = None
        self._kit_rows.clear()
        self._item_rows.clear()
        self._item_lines.clear()
        self._action_rows.clear()
        self._fit_rows.clear()
        self._shelf = None
        self._subtitle = self._status_row = self._detail_row = None
        if self.tree is not None:
            self.tree.paused = False

    def undock(self) -> None:
        """Close the bay, which closes this screen through the depot's signal."""
        depot = self.depot
        if depot is not None:
            depot.undock()
        self.close()

    # -- the shelf ---------------------------------------------------------

    def shelf(self) -> list[dict]:
        """Roll this visit's stock. Only opening the bay and rerolling do this."""
        depot = self.depot
        if depot is None:
            return []
        return self._ordered(depot.stock_for(self.run.build_profile()))

    def _ordered(self, items: list[dict]) -> list[dict]:
        """The running-out supply first, and otherwise the shelf as it rolled.

        Prominence rather than charity. Both supplies are always on the shelf
        (``trading.GUARANTEED_CONSUMABLES``) and the depot already puts them at
        the head of it; this only moves the one whose clock is actually running
        down to the very top, and the row carries a mark to say which clock.
        Air outranks fuel when both are short: a tank at zero strands a run and
        an empty lung ends it.
        """
        urgent = [DEPOT_FUEL_ITEM_ID] if self.low_fuel() else []
        if self.low_air():
            urgent = [DEPOT_O2_ITEM_ID, *urgent]
        if not urgent:
            return list(items)
        rank = {item_id: index for index, item_id in enumerate(urgent)}
        return sorted(items, key=lambda item: rank.get(str(item.get("id", "")), len(rank)))

    def _resync(self) -> None:
        """Re-read what the visit has sold without re-rolling what it stocks.

        A shelf is read while it is being bought from, and asking the depot for
        stock again would roll a fresh one against a build that has just
        changed: the card under the cursor would become a different item between
        the press and the release. The entries stay; only their state moves.
        """
        depot = self.depot
        if depot is None:
            return
        self.items = self._ordered([depot.priced(item) for item in self.items])
        self._sync_fit()

    def fit_lines(self) -> list[str]:
        """The FIT panel: every hardpoint, every socket, and the stowage."""
        run = self.run
        return fit_panel_lines(run.rack, run.sockets, run.stowed_weapons, run.stowed_modules)

    def _sync_fit(self) -> None:
        """Rebuild when the FIT block's line count has moved under the shelf.

        A purchase that stows and a refit made next door both change what the
        FIT panel lists, and a panel is a fixed set of controls, so a changed
        count means mounting a fresh one. The cursor is clamped rather than
        reset: the cards above the fit block have not moved.
        """
        self.cursor = min(self.cursor, max(0, self.rows - 1))
        if self._fit_visible and len(self.fit_lines()) != len(self._fit_rows):
            self._rebuild = True

    def air_seconds(self) -> float:
        """Seconds of air left at the hull's current drain."""
        power = self.run.power
        if power is None:
            return float("inf")
        breaches = int(getattr(self.run.ship, "open_breaches", 0) or 0)
        drain = balance.O2_DRAIN_PER_S + breaches * balance.O2_DRAIN_PER_BREACH_PER_S
        return float(power.o2) / drain if drain > 0.0 else float("inf")

    def low_air(self) -> bool:
        """Whether the life-support clock is inside its warning window."""
        return self.air_seconds() <= balance.O2_LOW_WARNING_SECONDS

    def jumps_left(self) -> float:
        """Ordinary jumps the tank still covers, at ``balance.WARP_FUEL_BASE``.

        The base fare rather than the cheapest route on the chart: a skip or a
        jump made with the hunter in the sector costs more, so a tank measured
        against the base is the optimistic reading, and the bay warns before
        even that runs out. It is also the number the pilot can check, since
        the base fare is what the chart quotes for a hop to the next column.
        """
        power = self.run.power
        if power is None:
            return float("inf")
        return float(power.fuel) / max(1e-6, float(balance.WARP_FUEL_BASE))

    def low_fuel(self) -> bool:
        """Whether the tank is down to :data:`DEPOT_LOW_FUEL_JUMPS` or fewer."""
        return self.jumps_left() <= DEPOT_LOW_FUEL_JUMPS

    def scrap(self) -> float:
        economy = self.run.economy
        return float(getattr(economy, "scrap", 0.0)) if economy is not None else 0.0

    # -- moving ------------------------------------------------------------

    @property
    def rows(self) -> int:
        return len(self.kits) + len(self.items) + len(self.ACTIONS)

    def move_cursor(self, step: int) -> None:
        """Step the cursor one place through the whole screen, in reading order.

        Reading order and not grid order, even though the shelf is a grid: the
        cards run left to right and then down, and one key walking every kit,
        every card and every action row in that order is the shape a menu has
        everywhere else in the game. A grid's second axis is :meth:`move_row`.
        """
        self.cursor = (self.cursor + int(step)) % max(1, self.rows)

    def move_row(self, step: int) -> None:
        """Jump a whole card row, which is what left and right do on the shelf.

        Only the shelf has a second axis, so this does nothing on a kit row or
        an action row, and it clamps rather than wrapping: a pilot pressing D
        on the bottom card wants the bottom card, not the top of the shelf.
        """
        first = len(self.kits)
        index = self.cursor - first
        if not 0 <= index < len(self.items):
            return
        moved = index + int(step) * DEPOT_GRID_COLUMNS
        if 0 <= moved < len(self.items):
            self.cursor = first + moved

    def selected_kit(self) -> str | None:
        """The Doctrine Kit row under the cursor, None while it is elsewhere."""
        return self.kits[self.cursor] if self.cursor < len(self.kits) else None

    def selected_item(self) -> dict | None:
        """The shelf card under the cursor, None while it is on any other row."""
        index = self.cursor - len(self.kits)
        return self.items[index] if 0 <= index < len(self.items) else None

    def selected_action(self) -> str:
        """The action row under the cursor, empty while it is on the shelf."""
        index = self.cursor - len(self.kits) - len(self.items)
        if index < 0:
            return ""
        return self.ACTIONS[index]

    # -- spending ----------------------------------------------------------

    def take_kit(self, index: int) -> bool:
        """Take the Doctrine Kit row at *index*. False when the pick is spent.

        The delivery and the once-per-profile record both belong to the run;
        this screen only drops the rows and says what came aboard.
        """
        if not (0 <= index < len(self.kits)):
            return False
        kit_id = self.kits[index]
        if not self.run.grant_kit(kit_id):
            self.kits = self.run.kit_offers()
            self._rebuild = True
            return False
        self.status = KIT_TAKEN.format(name=KIT_NAMES[kit_id], effects=KIT_EFFECTS[kit_id].upper())
        self.kits = self.run.kit_offers()
        self.cursor = 0
        self._rebuild = True
        self._resync()
        return True

    def buy(self, index: int) -> bool:
        """Buy the shelf card at *index*. False, and a reason, when it refuses."""
        depot = self.depot
        if depot is None or not (0 <= index < len(self.items)):
            return False
        item = self.items[index]
        name = _item_name(str(item.get("id", "")))
        if item.get("sold"):
            self.status = DEPOT_BUY_SOLD.format(name=name)
            return False
        price = float(item.get("price", 0.0))
        if self.scrap() + 1e-9 < price:
            self.status = DEPOT_BUY_SHORT.format(name=name)
            return False
        before = self.fit_snapshot()
        if not depot.buy(item):
            # The purchase gate refused before payment and named its reason on
            # the toast line; echo it here so the screen is not silent.
            hud = self.run.hud
            self.status = str(getattr(hud, "toast", "") or "") or DEPOT_BUY_SOLD.format(name=name)
            return False
        self.status = self.purchase_report(item, price, before, self.fit_snapshot())
        self._resync()
        return True

    def fit_snapshot(self) -> tuple[tuple[str, ...], tuple[str, ...], int]:
        """What is bolted where and how full the locker is, right now.

        Taken either side of a payment so the receipt can name the change
        rather than the price. Reading the racks is the only honest way to do
        it: the delivery runs through the run scene's own mutators off a
        signal, and the shelf is not told which of them fired.
        """
        run = self.run
        rack, sockets = run.rack, run.sockets
        guns = tuple(
            str(weapon.spec.id) if weapon is not None else ""
            for weapon in (rack.hardpoints if rack is not None else ())
        )
        modules: tuple[str, ...] = ()
        if sockets is not None:
            modules = tuple(str(sockets.module_id_at(index) or "") for index in range(len(sockets.sockets)))
        return guns, modules, len(run.stowed_weapons) + len(run.stowed_modules)

    def purchase_report(self, item: dict, price: float, before: tuple, after: tuple) -> str:
        """What the purchase actually did to the hull, in one sentence."""
        item_id = str(item.get("id", ""))
        name = _item_name(item_id)
        guns_before, modules_before, locker_before = before
        guns_after, modules_after, locker_after = after
        for index, (was, now) in enumerate(zip(guns_before, guns_after, strict=False)):
            if now != was and now == item_id:
                return DEPOT_BUY_MOUNTED.format(name=name, price=price, hardpoint=index + 1)
        sockets = self.run.sockets
        for index, (was, now) in enumerate(zip(modules_before, modules_after, strict=False)):
            if now != was and now == item_id:
                label = str(sockets.sockets[index].label).upper() if sockets is not None else str(index + 1)
                return DEPOT_BUY_INSTALLED.format(name=name, price=price, slot=REFIT_SOCKET_LABEL.format(label=label))
        if locker_after > locker_before:
            self._refit_waiting = True
            return DEPOT_BUY_STOWED.format(name=name, price=price)
        effect = CONSUMABLE_EFFECTS.get(item_id, "")
        if effect:
            return DEPOT_BUY_APPLIED.format(name=name, price=price, effect=effect.upper())
        return DEPOT_BUY_DONE.format(name=name, price=price)

    def open_refit(self) -> bool:
        """Raise the refit panel over the shelf. False when there is none."""
        refit = self.run.refit_screen
        if refit is None or self.depot is None:
            return False
        refit.open(self.depot)
        return True

    def refit_closed(self) -> None:
        """Take the bay back from the refit panel.

        The fit has moved, so the shelf's promises ("mounts hardpoint 2") and
        the FIT block are both stale, and the key that shut the panel is still
        down: re-read the one, re-prime the other. Whatever was waiting for a
        mount has had its chance, so the refit row goes back to being a door.
        """
        self.reprime()
        self._refit_waiting = False
        self._resync()
        self._refresh()

    def sell(self) -> float:
        """Sell the whole hold at the post's rate. Returns Cores banked.

        A sale that pays says so through :meth:`_banked_since`, which is the
        one path: the same hold can also be sold by holding the interact key,
        and a screen that only announced its own row would go quiet for the
        verb the world actually taught.
        """
        depot = self.depot
        if depot is None:
            return 0.0
        cores = depot.sell_hold()
        if cores <= 0.0:
            self.status = DEPOT_SOLD_NOTHING
        return cores

    def _banked_since(self) -> None:
        """Announce any Cores banked at this bay, whoever asked for them."""
        economy = self.run.economy
        if economy is None:
            return
        banked = float(economy.cores_banked_this_run)
        if banked > self._banked_mark + 1e-9:
            self.status = DEPOT_SOLD_HOLD.format(cores=banked - self._banked_mark)
        self._banked_mark = banked

    def reroll(self) -> bool:
        """Buy a fresh shelf. False, and a reason, when the hold is short."""
        depot = self.depot
        if depot is None:
            return False
        if not depot.reroll():
            self.status = DEPOT_REROLL_REFUSED
            return False
        self.items = self.shelf()
        self.cursor = min(self.cursor, max(0, self.rows - 1))
        self.status = DEPOT_REROLLED.format(price=depot.reroll_price())
        self._rebuild = True
        return True

    def commit(self) -> bool:
        """Run whatever the cursor is on."""
        action = self.selected_action()
        if not action:
            if self.cursor < len(self.kits):
                return self.take_kit(self.cursor)
            return self.buy(self.cursor - len(self.kits))
        if action == self.ACTION_REFIT:
            return self.open_refit()
        if action == self.ACTION_SELL:
            self.sell()
            return True
        if action == self.ACTION_REROLL:
            return self.reroll()
        self.undock()
        return True

    # -- frame -------------------------------------------------------------

    def on_update(self, dt: float):
        if not self._open:
            return
        refit = self.run.refit_screen
        if refit is not None and refit.is_open:
            # The refit panel is up. It owns every key and the pointer while it
            # is, including the interact key the bay's sell hold shares, so the
            # shelf reads nothing at all until it is handed back.
            return
        depot = self.depot
        if depot is None or not depot.is_docked:
            self.close()
            return
        # The bay is paused under this screen, so its ladder is driven by hand.
        # Taps belong to the screen; the sell hold still belongs to the bay.
        depot.tick_interact(dt, taps_toggle_bay=False)
        if not depot.is_docked:
            self.close()
            return
        hud = self.run.hud
        if hud is not None:
            # The run is paused underneath, so nobody else is pushing the verb
            # line and whatever it last said would stand frozen under the
            # panel. The screen owns every verb while it is up.
            hud.set_affordance("")
        if self._rebuild:
            self._build()

        if Input.just_pressed("thrust_down") or Input.just_pressed(MENU_DOWN_ACTION):
            self.move_cursor(1)
        elif Input.just_pressed("thrust_up") or Input.just_pressed(MENU_UP_ACTION):
            self.move_cursor(-1)
        if Input.just_pressed("thrust_right"):
            self.move_row(1)
        elif Input.just_pressed("thrust_left"):
            self.move_row(-1)

        under, moved = self._pointed_at()
        if under is not None and moved:
            self.cursor = under
        _, released = self._commit.poll(dt)
        confirmed, _ = self._confirm.poll(dt)
        clicked, _ = self._click.poll(dt)
        if clicked and under is not None:
            self.cursor = under
        # A tap of interact confirms; a long press of the same key belongs to
        # the bay's sell rung and must not also buy whatever the cursor is on.
        tapped = released and self._commit.hold_s < INTERACT_SELL_HOLD_S
        if tapped or confirmed or (clicked and under is not None):
            self.commit()
        if not self._open:
            return
        self._banked_since()
        self._refresh()

    def _pointed_at(self) -> tuple[int | None, bool]:
        """The row or card under the pointer, and whether the pointer has moved."""
        position = Input.mouse_position
        point = (float(position.x), float(position.y))
        moved = self._pointer is not None and point != self._pointer
        self._pointer = point
        for index, row in enumerate([*self._kit_rows, *self._item_rows, *self._action_rows]):
            if _rect_holds(row.get_global_rect(), point):
                return index, moved
        return None, moved

    # -- drawing -----------------------------------------------------------

    def _build(self) -> None:
        """Mount the panel for this visit's shelf."""
        self._rebuild = False
        if self._backdrop is not None:
            self._backdrop.destroy()
        self._kit_rows.clear()
        self._item_rows.clear()
        self._item_lines.clear()
        self._action_rows.clear()
        self._fit_rows.clear()

        title = BROKER_TITLE if isinstance(self.depot, Broker) else DEPOT_TITLE
        # A column lays its children out at its own width, so the shelf's width
        # has to reach the column and not only the panel around it.
        box = build_menu_panel(self, title, width=DEPOT_ROW_WIDTH_PX)
        # Rows sit in the column, the column in the panel, the panel on the
        # backdrop: the backdrop is what has to go when the bay closes.
        panel = menu_panel_of(self)
        # The shop's own plate, opaque and dark: see DEPOT_PANEL_FILL. Every
        # other screen keeps the shared one, which is over a nebula rather than
        # over a lit barge four metres off the bow.
        panel.bg_colour = DEPOT_PANEL_FILL
        self._backdrop = panel.parent
        self._subtitle = add_menu_line(box, "", dim=True)
        # The Doctrine Kit pick stands above the shelf: it is free exactly once,
        # so it outranks everything the bay wants paying for.
        for _ in self.kits:
            row = box.add_child(Button("", size_x=DEPOT_ROW_WIDTH_PX, size_y=DEPOT_ROW_HEIGHT_PX))
            row.font_size = DEPOT_ROW_FONT_PX
            # See MenuList: this screen hit-tests its own rows, and its shelf
            # cards are panels, so a button that claimed the press would take
            # the click away from the path that runs every row.
            row.pointer_filter = PointerFilter.IGNORE
            self._kit_rows.append(row)
        self._shelf = box.add_child(DrawCanvas(name="Shelf", size_x=DEPOT_ROW_WIDTH_PX, size_y=self.shelf_height()))
        # The one line under the grid: the focused card's whole row, including
        # everything three short lines had to leave out.
        self._detail_row = add_menu_line(box, "", dim=True)
        self._detail_row.font_size = DEPOT_ROW_FONT_PX
        for _ in self.ACTIONS:
            row = box.add_child(Button("", size_x=DEPOT_ROW_WIDTH_PX, size_y=MENU_ROW_HEIGHT_PX))
            row.font_size = DEPOT_ROW_FONT_PX
            row.pointer_filter = PointerFilter.IGNORE
            self._action_rows.append(row)
        self._status_row = add_menu_line(box, "", dim=True)
        # The FIT panel under everything spendable: what is bolted where, so a
        # card promising "hardpoint 2" or "bow socket" can be checked in place.
        self._fit_visible = self.shows_fit_panel()
        lines = self.fit_lines() if self._fit_visible else [DEPOT_FIT_ELSEWHERE]
        for line in lines:
            label = add_menu_line(box, ellipsise(line, DEPOT_ROW_CHARS), dim=True)
            label.font_size = DEPOT_ROW_FONT_PX
            if self._fit_visible:
                self._fit_rows.append(label)
        legend = add_menu_line(box, DEPOT_CONTROLS_LINE, dim=True)
        legend.font_size = DEPOT_ROW_FONT_PX
        settle_menu_panel(self)
        # Only now is the shelf canvas standing at the rect it will keep.
        self._draw_cards()
        self._refresh()

    def shelf_rows(self) -> int:
        """How many card rows this visit's shelf comes to."""
        return max(1, -(-len(self.items) // DEPOT_GRID_COLUMNS))

    def shelf_height(self) -> float:
        """The grid's authored height, which is what the column reserves for it."""
        rows = self.shelf_rows()
        return rows * DEPOT_CARD_HEIGHT_PX + (rows - 1) * DEPOT_CARD_GAP_PX

    def _draw_cards(self) -> None:
        """Place one plate and three lines per shelf item, once, on the canvas."""
        canvas = self._shelf
        if canvas is None:
            return
        _, _, view_w, view_h = (float(value) for value in canvas.get_global_rect())
        if view_w <= 1.0 or view_h <= 1.0:
            return
        # The panel fits width and height by separate factors, so the card
        # keeps its own proportions on each axis rather than one of them.
        wide = view_w / DEPOT_ROW_WIDTH_PX
        tall = view_h / max(1.0, self.shelf_height())
        gap_x, gap_y = DEPOT_CARD_GAP_PX * wide, DEPOT_CARD_GAP_PX * tall
        card_w = (view_w - (DEPOT_GRID_COLUMNS - 1) * gap_x) / DEPOT_GRID_COLUMNS
        card_h = DEPOT_CARD_HEIGHT_PX * tall
        line_h = DEPOT_CARD_LINE_PX * tall
        pad = DEPOT_CARD_PAD_PX * min(wide, tall)
        head_font = DEPOT_CARD_HEAD_FONT_PX * tall
        body_font = DEPOT_CARD_BODY_FONT_PX * tall
        self._card_chars = _row_chars(max(1.0, card_w - 2.0 * pad), body_font)
        for index in range(len(self.items)):
            column, row = index % DEPOT_GRID_COLUMNS, index // DEPOT_GRID_COLUMNS
            x, y = column * (card_w + gap_x), row * (card_h + gap_y)
            plate = self._place(canvas, Panel(), x, y, card_w, card_h)
            plate.bg_colour = DEPOT_CARD_FILL
            plate.border_colour = DEPOT_CARD_EDGE_COLOUR
            plate.border_width = DEPOT_CARD_BORDER_PX * min(wide, tall)
            width = max(1.0, card_w - 2.0 * pad)
            head = self._card_line(canvas, x + pad, y + pad, width, line_h, head_font)
            body = self._card_line(canvas, x + pad, y + pad + line_h, width, line_h, body_font)
            foot = self._card_line(canvas, x + pad, y + pad + 2.0 * line_h, width, line_h, body_font)
            self._item_rows.append(plate)
            self._item_lines.append((head, body, foot))

    def _place(self, parent: Control, control: Control, x: float, y: float, width: float, height: float) -> Control:
        """Mount *control* on *parent* at a rect it keeps for its whole life."""
        control.margin_left, control.margin_top = float(x), float(y)
        control.size_x, control.size_y = float(width), float(height)
        control.pointer_filter = PointerFilter.IGNORE
        return parent.add_child(control)

    def _card_line(self, parent: Control, x: float, y: float, width: float, height: float, font: float) -> Label:
        """One of a card's three lines, never smaller than the engine will draw."""
        label = Label("", size_x=width, size_y=height)
        self._place(parent, label, x, y, width, height)
        label.font_size = _refit_font(font)
        label.text_colour = Colour.coerce(MENU_TEXT_COLOUR, name="card")
        return label

    def shows_fit_panel(self) -> bool:
        """Whether this window is tall enough for the shelf and the fit block."""
        _, _, _, height = self.get_global_rect()
        return float(height) >= DEPOT_FIT_PANEL_MIN_WINDOW_PX

    def subtitle_text(self) -> str:
        """The line under the title: the hold, and the two survival clocks.

        A clock is only named while it is running out, and the sentence that
        names it is followed by the sentence that answers it: the shelf below
        carries both supplies, so the only bad news left to print is a ration
        this visit has already spent.
        """
        parts = [DEPOT_HOLD_SUBTITLE.format(scrap=self.scrap())]
        if self.low_air():
            parts.append(DEPOT_LOW_AIR_SUBTITLE.format(seconds=self.air_seconds()))
            if not self.stocks(DEPOT_O2_ITEM_ID):
                parts.append(DEPOT_NO_CANISTER)
        if self.low_fuel():
            parts.append(DEPOT_LOW_FUEL_SUBTITLE.format(jumps=self.jumps_left()))
            if not self.stocks(DEPOT_FUEL_ITEM_ID):
                parts.append(DEPOT_NO_FUEL_CELL)
        return ", ".join(parts)

    def stocks(self, item_id: str) -> bool:
        """Whether the shelf still has an unsold *item_id* on it to buy."""
        return any(str(item.get("id", "")) == item_id and not item.get("sold") for item in self.items)

    def supply_flag(self, item_id: str) -> str:
        """The mark a supply row carries while its own clock is running down."""
        if item_id == DEPOT_O2_ITEM_ID and self.low_air():
            return f"{DEPOT_MARK_AIR} "
        if item_id == DEPOT_FUEL_ITEM_ID and self.low_fuel():
            return f"{DEPOT_MARK_FUEL} "
        return ""

    def kit_row_text(self, index: int) -> str:
        """One Doctrine Kit row: the name, that it is free, and what it seeds."""
        kit_id = self.kits[index]
        mark = DOCTRINE_MARK_CURSOR if self.cursor == index else " "
        head = f"{mark} {KIT_ROW.format(name=KIT_NAMES[kit_id], effects='')}"
        return head + ellipsise(KIT_EFFECTS[kit_id], DEPOT_ROW_CHARS - len(head))

    def item_row_text(self, index: int) -> str:
        """One shelf item as a single line: name, category, price, effect, state.

        What a card says over three lines, joined back into one. The card is
        what a pilot reads; this is what the line under the grid prints for
        whatever the cursor is on, and it is the form that fits everything in,
        so it is also the form anything scripted reads.

        The effect is the only part that may be cut. The name, the price and
        the state mark are what the item is read for, and a line long enough to
        need cutting is long because its effect is, never because its price is.
        """
        item = self.items[index]
        item_id = str(item.get("id", ""))
        price = float(item.get("price", 0.0))
        mark = DOCTRINE_MARK_CURSOR if self.cursor == len(self.kits) + index else " "
        flag = self.supply_flag(item_id)
        head = f"{mark} {flag}{_item_name(item_id)} [{category_label(item)}] {price:.0f} scrap: "
        short = price - self.scrap()
        if item.get("sold"):
            tail = f", {DEPOT_MARK_SOLD}"
        elif short > 1e-9:
            tail = f", {DEPOT_MARK_SHORT.format(short=short)}"
        else:
            tail = ""
        effect = ellipsise(effect_line(item), DEPOT_ROW_CHARS - len(head) - len(tail))
        return f"{head}{effect}{tail}"

    def item_card_lines(self, index: int) -> tuple[str, str, str]:
        """One card's three lines: what it is, what it does, and can I have it.

        The third is never empty. A card that said nothing where the answer
        goes would be indistinguishable from one whose answer is yes, and the
        answer is the reason the card is being read.
        """
        item = self.items[index]
        item_id = str(item.get("id", ""))
        price = float(item.get("price", 0.0))
        mark = f"{DOCTRINE_MARK_CURSOR} " if self.cursor == len(self.kits) + index else "  "
        flag = self.supply_flag(item_id)
        head = DEPOT_CARD_HEAD.format(
            mark=mark, flag=flag, name=_item_name(item_id), price=price, category=category_label(item)
        )
        return head, self.item_card_effect(index), self.item_card_state(index)

    def item_card_effect(self, index: int) -> str:
        """The card's middle line: what the thing does, whoever can use it.

        The shelf's own one-liner collapses to the refusal for something the
        hull has no use for, which is right for a single line and wrong for a
        card: the card has a line for the refusal already, and printing it
        twice tells a pilot what they cannot do without ever saying what they
        were being offered.
        """
        item = self.items[index]
        item_id = str(item.get("id", ""))
        effect = effect_line(item)
        if effect and effect.upper() == self.item_card_state(index):
            return CONSUMABLE_EFFECTS.get(item_id, "") or item_summary(item_id) or effect
        return effect

    def item_card_state(self, index: int) -> str:
        """The card's foot: the verb, the shortfall, or the hull's own refusal."""
        item = self.items[index]
        price = float(item.get("price", 0.0))
        if item.get("sold"):
            return DEPOT_CARD_SOLD
        short = price - self.scrap()
        if short > 1e-9:
            return DEPOT_CARD_SHORT.format(short=short)
        if item.get("fit_blocked") and item.get("fit"):
            return str(item["fit"]).upper()
        return DEPOT_CARD_BUY.format(price=price)

    def action_row_text(self, action: str) -> str:
        """One action row, priced the same way the shelf is."""
        depot = self.depot
        if action == self.ACTION_REFIT:
            stowed = len(self.run.stowed_weapons) + len(self.run.stowed_modules)
            if self._refit_waiting and stowed:
                return DEPOT_REFIT_ROW_WAITING.format(stowed=stowed)
            return DEPOT_REFIT_ROW.format(stowed=stowed)
        if action == self.ACTION_SELL:
            scrap, cores, rate = depot.sell_quote() if depot is not None else (0.0, 0.0, 0.0)
            if scrap <= 0.0:
                return DEPOT_SELL_EMPTY_ROW
            return DEPOT_SELL_ROW.format(scrap=scrap, cores=cores, rate=rate)
        if action == self.ACTION_REROLL:
            return DEPOT_REROLL_ROW.format(price=depot.reroll_price() if depot is not None else 0)
        return DEPOT_UNDOCK_ROW

    def _refresh(self) -> None:
        if self._subtitle is not None:
            _set_text(self._subtitle, self.subtitle_text())
        for index, row in enumerate(self._kit_rows):
            if index >= len(self.kits):
                continue
            _set_text(row, self.kit_row_text(index))
            row.text_colour = Colour.coerce(MENU_TEXT_COLOUR, name="kit")
        for index, plate in enumerate(self._item_rows):
            if index >= len(self.items) or index >= len(self._item_lines):
                continue
            self._paint_card(index, plate, self._item_lines[index])
        if self._detail_row is not None:
            index = self.cursor - len(self.kits)
            detail = self.item_row_text(index) if 0 <= index < len(self.items) else ""
            _set_text(self._detail_row, ellipsise(detail, DEPOT_ROW_CHARS))
        for index, action in enumerate(self.ACTIONS):
            if index >= len(self._action_rows):
                continue
            offset = len(self.kits) + len(self.items)
            on_cursor = self.cursor == offset + index
            mark = DOCTRINE_MARK_CURSOR if on_cursor else " "
            text = ellipsise(self.action_row_text(action), DEPOT_ROW_CHARS - 2)
            row = self._action_rows[index]
            _set_text(row, f"{mark} {text}")
            waiting = action == self.ACTION_REFIT and self._refit_waiting
            colour = MENU_SELECTED_COLOUR if on_cursor or waiting else MENU_TEXT_COLOUR
            row.text_colour = Colour.coerce(colour, name="action")
        if self._status_row is not None:
            _set_text(self._status_row, ellipsise(self.status, DEPOT_ROW_CHARS))
        for label, line in zip(self._fit_rows, self.fit_lines(), strict=False):
            _set_text(label, ellipsise(line, DEPOT_ROW_CHARS))

    def _paint_card(self, index: int, plate: Panel, lines: tuple[Label, Label, Label]) -> None:
        """Write and colour one card. Nothing on it ever moves."""
        item = self.items[index]
        focused = self.cursor == len(self.kits) + index
        sold = bool(item.get("sold"))
        short = not sold and float(item.get("price", 0.0)) > self.scrap() + 1e-9
        refused = not sold and not short and bool(item.get("fit_blocked"))
        head_text, body_text, foot_text = self.item_card_lines(index)
        chars = self._card_chars
        _set_text(lines[0], ellipsise(head_text, chars))
        _set_text(lines[1], ellipsise(body_text, chars))
        _set_text(lines[2], ellipsise(foot_text, chars))
        if sold:
            plate.bg_colour = DEPOT_CARD_SOLD_FILL
            head_colour, foot_colour = DOCTRINE_BLOCKED_COLOUR, DEPOT_CARD_SOLD_COLOUR
        elif short:
            plate.bg_colour = DEPOT_CARD_SHORT_FILL
            head_colour, foot_colour = MENU_DIM_COLOUR, DEPOT_CARD_SHORT_COLOUR
        else:
            plate.bg_colour = DEPOT_CARD_FILL
            head_colour = MENU_SELECTED_COLOUR if focused else MENU_TEXT_COLOUR
            foot_colour = DEPOT_CARD_SHORT_COLOUR if refused else DEPOT_CARD_BUY_COLOUR
        plate.border_colour = DEPOT_CARD_FOCUS_COLOUR if focused else DEPOT_CARD_EDGE_COLOUR
        lines[0].text_colour = Colour.coerce(head_colour, name="card_head")
        lines[1].text_colour = Colour.coerce(DEPOT_CARD_BODY_COLOUR, name="card_body")
        lines[2].text_colour = Colour.coerce(foot_colour, name="card_foot")


@dataclass(frozen=True)
class RefitSlot:
    """One mount on the hull, as the refit panel needs to draw and name it.

    A hardpoint and a socket are different things to every other module in the
    game and the same thing to a pilot changing a fit: a place on the hull with
    something bolted to it. This is that shared shape, built from the two racks
    and never stored anywhere: the racks stay authoritative.

    :attr:`x` and :attr:`z` are hull units in the ship's own frame, nose along
    -Z and starboard along +X, which is what puts the drawn mount where the
    real one is.
    """

    kind: str
    index: int
    label: str
    tag: str
    x: float
    z: float
    size: str = ""

    #: The two kinds, spelled once.
    HARDPOINT = "hardpoint"
    SOCKET = "socket"


def _socket_tag(label: str) -> str:
    """A socket's label as a mount tag: "starboard quarter" to "S.QUAR"."""
    words = str(label).split()
    if not words:
        return "SOCKET"
    if len(words) == 1:
        return words[0][:5].upper()
    return f"{words[0][0].upper()}.{words[-1][:4].upper()}"


def refit_slots(rack, sockets) -> list[RefitSlot]:
    """Every mount on the hull, fore to aft, whatever kind it is.

    Sorted by position rather than by rack, because the panel draws them on a
    plan and the cursor walks them down it: a list that ran the hardpoints and
    then the sockets would move the cursor about the hull at random.
    """
    slots: list[RefitSlot] = []
    for index in range(len(getattr(rack, "hardpoints", ()))):
        x, z = HARDPOINT_OFFSETS[index % len(HARDPOINT_OFFSETS)]
        slots.append(
            RefitSlot(RefitSlot.HARDPOINT, index, REFIT_HARDPOINT_LABEL.format(index=index + 1), f"H{index + 1}", x, z)
        )
    for socket in getattr(sockets, "sockets", ()):
        slots.append(
            RefitSlot(
                RefitSlot.SOCKET,
                socket.index,
                REFIT_SOCKET_LABEL.format(label=socket.label.upper()),
                _socket_tag(socket.label),
                float(socket.offset.x),
                float(socket.offset.y),
                str(socket.size),
            )
        )
    return sorted(slots, key=lambda slot: (slot.z, slot.x))


class RefitScene(Control):
    """The hull drawn as a hull, and the locker beside it.

    A fit changed through a block of sentences under the shelf, one per stowed
    weapon per hardpoint, works and reads as nothing: rows saying "MOUNT
    AUTOCANNON ON HARDPOINT 2" never say where hardpoint 2 is or what else the
    hull carries, four of them say the same four words, and a module cannot be
    moved at all once it is bolted in.

    So this screen is a plan of the ship. Every mount is a box where it really
    sits, carrying the short name of what is on it or EMPTY; the locker is the
    column beside it; and a refit is picking one of each, in either order. What
    the pick *would* do is printed before the press, in the same sentence that
    reports it afterwards, so a swap that costs a gun says which gun while it
    can still be reconsidered.

    Every control is placed once, from the window rect, and never moves again:
    the locker is allocated for every item that could ever be in it (what is in
    it now, plus one per mount, which is what unmounting everything would come
    to), so mounting a gun rewrites text and never reflows a column. That is the
    engine's retained-draw contract taken seriously rather than worked around.

    An overlay over the dock screen, which holds the tree still for it. The bay
    keeps the pause; this panel only takes the keys while it is up.
    """

    # It runs while the bay holds the tree still, so it must not be paused with
    # everything else.
    update_mode = Property(
        UpdateMode.ALWAYS,
        hint="Processing behaviour while the tree is paused",
        on_change="_invalidate_update_mode_cache",
    )

    #: The columns the focus moves between, and the rows under both.
    COLUMN_HULL = "hull"
    COLUMN_LOCKER = "locker"
    ACTION_UNMOUNT = "unmount"
    ACTION_DONE = "done"
    ACTIONS: tuple[str, ...] = (ACTION_UNMOUNT, ACTION_DONE)

    def __init__(self, run: RunScene, **kwargs):
        kwargs.setdefault("name", "RefitPanel")
        super().__init__(**kwargs)
        self.run = run
        # It reads the pointer itself.
        self.pointer_filter = PointerFilter.IGNORE
        self.depot: Depot | None = None
        #: Every mount on the hull, fore to aft. Rebuilt on open, never during.
        self.slots: list[RefitSlot] = []
        #: What the pilot is looking at: ``(column, index)`` into the mounts,
        #: the locker rows or the action rows.
        self.focus: tuple[str, int] = (self.COLUMN_HULL, 0)
        #: What is armed and waiting for its other half, or None.
        self.armed: tuple[str, int] | None = None
        self.status = ""

        self._open = False
        self._backdrop: Panel | None = None
        self._slot_boxes: list[Panel] = []
        self._slot_labels: list[Label] = []
        self._locker_rows: list[Panel] = []
        self._locker_labels: list[Label] = []
        self._action_rows: list[Panel] = []
        self._action_labels: list[Label] = []
        self._preview: list[Label] = []
        self._status_row: Label | None = None
        self._locker_heading: Label | None = None
        #: How wide each block's text may be, in characters, and what the
        #: preview line is wrapped against.
        self._slot_chars: list[int] = []
        self._locker_chars = 40
        self._preview_chars = 60
        self._preview_width = REFIT_BASE_WIDTH_PX
        self._preview_font = REFIT_ROW_FONT_PX
        self._window: tuple[float, float, float, float] | None = None
        self._commit = PressLatch("interact")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._click = PressLatch("fire_primary")
        self._back = PressLatch(PAUSE_ACTION)
        self._pointer: tuple[float, float] | None = None

    def on_ready(self):
        self.anchor = Anchor.FULL_RECT
        self.visible = False

    @property
    def is_open(self) -> bool:
        return self._open

    # -- opening and closing ----------------------------------------------

    def open(self, depot: Depot) -> None:
        """Raise the panel over *depot*'s shelf."""
        if self._open:
            return
        self.depot = depot
        self.slots = refit_slots(self.run.rack, self.run.sockets)
        self.focus = (self.COLUMN_HULL, 0) if self.slots else (self.COLUMN_LOCKER, 0)
        self.armed = None
        self.status = ""
        self._open = True
        self.visible = True
        # Primed on the press that opened the panel, so it cannot also mount.
        self._commit = PressLatch("interact")
        self._confirm = PressLatch(MENU_CONFIRM_ACTION)
        self._click = PressLatch("fire_primary")
        self._back = PressLatch(PAUSE_ACTION)
        self._pointer = None
        self._build()

    def close(self) -> None:
        """Drop the panel and hand the bay back to the shelf."""
        if not self._open:
            return
        self._open = False
        self.visible = False
        self.depot = None
        if self._backdrop is not None:
            self._backdrop.destroy()
            self._backdrop = None
        self._slot_boxes.clear()
        self._slot_labels.clear()
        self._locker_rows.clear()
        self._locker_labels.clear()
        self._action_rows.clear()
        self._action_labels.clear()
        self._preview.clear()
        self._status_row = self._locker_heading = None
        self._window = None
        shop = self.run.depot_screen
        if shop is not None and shop.is_open:
            shop.refit_closed()

    # -- what is on the hull and in the locker ------------------------------

    def occupant(self, slot: RefitSlot) -> str:
        """The catalogue id bolted to *slot*, empty for a bare mount."""
        if slot.kind == RefitSlot.HARDPOINT:
            rack = self.run.rack
            fitted = rack.hardpoints[slot.index] if rack is not None else None
            return str(fitted.spec.id) if fitted is not None else ""
        sockets = self.run.sockets
        return str(sockets.module_id_at(slot.index) or "") if sockets is not None else ""

    def locker(self) -> list[dict]:
        """Everything waiting for a mount: stowed guns, then loose modules."""
        run = self.run
        rows = [{"id": weapon_id, "kind": "weapon"} for weapon_id in run.stowed_weapons]
        rows += [{"id": module_id, "kind": "module"} for module_id in run.stowed_modules]
        return rows

    def selected_slot(self) -> RefitSlot | None:
        """The mount the pilot has armed, None while nothing is armed."""
        if self.armed is None or self.armed[0] != self.COLUMN_HULL:
            return None
        index = self.armed[1]
        return self.slots[index] if 0 <= index < len(self.slots) else None

    def selected_item(self) -> dict | None:
        """The locker row the pilot has armed, None while nothing is armed."""
        if self.armed is None or self.armed[0] != self.COLUMN_LOCKER:
            return None
        rows = self.locker()
        index = self.armed[1]
        return rows[index] if 0 <= index < len(rows) else None

    # -- moving ------------------------------------------------------------

    def entries(self) -> list[tuple[str, int]]:
        """Every focusable thing, in the order W and S walk them."""
        rows = [(self.COLUMN_HULL, index) for index in range(len(self.slots))]
        rows += [(self.COLUMN_LOCKER, index) for index in range(len(self.locker()))]
        rows += [(action, index) for index, action in enumerate(self.ACTIONS)]
        return rows

    def move_focus(self, step: int) -> None:
        """Step the focus through the mounts, the locker and the action rows."""
        entries = self.entries()
        if not entries:
            return
        try:
            at = entries.index(self.focus)
        except ValueError:
            at = 0
            step = 0
        self.focus = entries[(at + int(step)) % len(entries)]

    def move_column(self) -> None:
        """Jump between the hull and the locker, keeping the row where it fits.

        One key for both directions: there are two columns, so "sideways" has
        only one meaning, and A and D both mean it.
        """
        column, index = self.focus
        rows = self.locker()
        if column == self.COLUMN_HULL:
            if rows:
                self.focus = (self.COLUMN_LOCKER, min(index, len(rows) - 1))
        elif self.slots:
            self.focus = (self.COLUMN_HULL, min(index, len(self.slots) - 1))

    def place_focus(self, entry: tuple[str, int]) -> None:
        """Put the focus exactly here, which is what the pointer does."""
        if entry in self.entries():
            self.focus = entry

    # -- what a mount would do ---------------------------------------------

    def fit_refusal(self, item: dict, slot: RefitSlot) -> str:
        """Why *item* will not go on *slot*, empty when it will.

        The rules are the racks' own; what is written here is only their
        wording, and it is written before the press rather than after it.
        """
        item_id = str(item.get("id", ""))
        name = _item_name(item_id)
        if str(item.get("kind", "")) == "weapon":
            if slot.kind == RefitSlot.SOCKET:
                return REFIT_REFUSE_GUN_IN_SOCKET.format(name=name, slot=slot.label)
            return ""
        if slot.kind == RefitSlot.HARDPOINT:
            return REFIT_REFUSE_MODULE_ON_HARDPOINT.format(name=name, slot=slot.label)
        sockets = self.run.sockets
        if sockets is None or item_id not in MODULE_CATALOGUE:
            return REFIT_REFUSED
        spec = module_spec(item_id)
        size = str(spec["socket_size"])
        if not sockets.sockets[slot.index].accepts(size):
            return REFIT_REFUSE_TOO_LARGE.format(
                name=name, size=size.upper(), slot=slot.label, socket_size=slot.size.upper()
            )
        if str(spec["family"]) == "turret":
            # The rack caps turrets, and a socket that already holds one is a
            # straight exchange rather than a fifth turret.
            standing = len(sockets.turrets())
            if self.occupant(slot) in MODULE_CATALOGUE and str(module_spec(self.occupant(slot))["family"]) == "turret":
                standing -= 1
            if standing >= balance.AUTO_TURRETS_MAX:
                return REFIT_REFUSE_TURRETS_FULL.format(name=name, count=standing + 1, maximum=balance.AUTO_TURRETS_MAX)
        return ""

    def focused_pair(self) -> tuple[dict | None, RefitSlot | None]:
        """The refit the focus is currently describing: what, and where.

        One of the two comes from the armed pick and the other from wherever
        the focus is standing, in whichever order they were chosen, which is
        what makes the panel work from either column.
        """
        column, index = self.focus
        item, slot = self.selected_item(), self.selected_slot()
        if column == self.COLUMN_HULL and 0 <= index < len(self.slots):
            slot = self.slots[index]
        rows = self.locker()
        if column == self.COLUMN_LOCKER and 0 <= index < len(rows):
            item = rows[index]
        return item, slot

    def refusal(self) -> str:
        """Why the focused refit will not happen, empty when it will."""
        item, slot = self.focused_pair()
        if item is None or slot is None or self.focus[0] in self.ACTIONS:
            return ""
        return self.fit_refusal(item, slot)

    def preview(self) -> str:
        """What confirming right now would do, said before it is done.

        The whole panel turns on this line. Reading it with a mount focused and
        nothing armed describes the mount; with a thing armed it describes the
        refit that thing would make *here*, including the gun it would cost.
        """
        column, _index = self.focus
        if column == self.ACTION_UNMOUNT:
            slot = self.selected_slot()
            if slot is None:
                return REFIT_UNMOUNT_NOTHING
            occupant = self.occupant(slot)
            if not occupant:
                return REFIT_UNMOUNT_BARE.format(slot=slot.label)
            return REFIT_UNMOUNT_DONE.format(name=_item_name(occupant), slot=slot.label)
        if column == self.ACTION_DONE:
            return REFIT_ACTION_DONE
        item, slot = self.focused_pair()
        if item is not None and slot is not None:
            return self.fit_refusal(item, slot) or refit_preview(str(item["id"]), slot.label, self.occupant(slot))
        if item is not None:
            item_id = str(item["id"])
            return REFIT_PREVIEW_PICK_MOUNT.format(name=_item_name(item_id), summary=item_summary(item_id))
        if slot is not None:
            occupant = self.occupant(slot)
            if not occupant:
                return REFIT_PREVIEW_SLOT_BARE.format(slot=slot.label)
            return REFIT_PREVIEW_SLOT_FULL.format(
                slot=slot.label, occupant=_item_name(occupant), summary=item_summary(occupant)
            )
        return REFIT_LOCKER_EMPTY

    # -- refitting ---------------------------------------------------------

    def mount(self, item: dict, slot: RefitSlot) -> bool:
        """Put *item* on *slot*. False, and a reason on the line, when it will not."""
        refusal = self.fit_refusal(item, slot)
        if refusal:
            self.status = refusal
            return False
        item_id = str(item.get("id", ""))
        name = _item_name(item_id)
        if slot.kind == RefitSlot.HARDPOINT:
            displaced = self.run.mount_weapon(item_id, slot.index)
            if displaced is None:
                self.status = REFIT_REFUSED
                return False
            done = (
                DEPOT_SWAP_DONE_DISPLACED.format(name=name, hardpoint=slot.index + 1, displaced=_item_name(displaced))
                if displaced
                else DEPOT_SWAP_DONE.format(name=name, hardpoint=slot.index + 1)
            )
        else:
            displaced = self.run.install_module(item_id, slot.index)
            if displaced is None:
                self.status = REFIT_REFUSED
                return False
            done = (
                REFIT_INSTALL_DISPLACED.format(name=name, slot=slot.label, displaced=_item_name(displaced))
                if displaced
                else REFIT_INSTALL_DONE.format(name=name, slot=slot.label)
            )
        self._announce(done)
        self.armed = None
        self._settle_focus()
        return True

    def unmount(self, slot: RefitSlot | None) -> bool:
        """Strip *slot* back to bare mounting and put what came off in the locker."""
        if slot is None:
            self.status = REFIT_UNMOUNT_NOTHING
            return False
        occupant = self.occupant(slot)
        if not occupant:
            self.status = REFIT_UNMOUNT_BARE.format(slot=slot.label)
            return False
        if slot.kind == RefitSlot.HARDPOINT:
            self.run.unmount_weapon(slot.index)
        else:
            self.run.uninstall_module(slot.index)
        self._announce(REFIT_UNMOUNT_DONE.format(name=_item_name(occupant), slot=slot.label))
        self._settle_focus()
        return True

    def confirm(self) -> bool:
        """Act on whatever the focus is standing on."""
        column, index = self.focus
        if column == self.ACTION_DONE:
            self.close()
            return True
        if column == self.ACTION_UNMOUNT:
            return self.unmount(self.selected_slot())
        if column == self.COLUMN_HULL:
            if not 0 <= index < len(self.slots):
                return False
            item = self.selected_item()
            if item is not None:
                return self.mount(item, self.slots[index])
            self.armed = None if self.armed == (self.COLUMN_HULL, index) else (self.COLUMN_HULL, index)
            self.status = ""
            return True
        rows = self.locker()
        if not 0 <= index < len(rows):
            return False
        slot = self.selected_slot()
        if slot is not None:
            return self.mount(rows[index], slot)
        self.armed = None if self.armed == (self.COLUMN_LOCKER, index) else (self.COLUMN_LOCKER, index)
        self.status = ""
        return True

    def _announce(self, text: str) -> None:
        """Say what just happened on the panel and on the run's own toast line."""
        self.status = text
        hud = self.run.hud
        if hud is not None:
            hud.show_toast(text)

    def _settle_focus(self) -> None:
        """Keep the focus on something that still exists after a refit."""
        self.armed = None
        entries = self.entries()
        if self.focus not in entries:
            self.focus = entries[0] if entries else (self.COLUMN_HULL, 0)

    # -- frame -------------------------------------------------------------

    def on_update(self, dt: float):
        if not self._open:
            return
        shop = self.run.depot_screen
        if shop is None or not shop.is_open:
            self.close()
            return
        if self.get_global_rect() != self._window:
            # The window itself resized. Everything is placed from that rect,
            # so it is all rebuilt at the new one rather than left painted at
            # coordinates that have moved out from under it.
            self._build()

        if Input.just_pressed("thrust_down") or Input.just_pressed(MENU_DOWN_ACTION):
            self.move_focus(1)
        elif Input.just_pressed("thrust_up") or Input.just_pressed(MENU_UP_ACTION):
            self.move_focus(-1)
        if Input.just_pressed("thrust_left") or Input.just_pressed("thrust_right"):
            self.move_column()

        under, moved = self._pointed_at()
        if under is not None and moved:
            self.place_focus(under)
        committed, _ = self._commit.poll(dt)
        confirmed, _ = self._confirm.poll(dt)
        clicked, _ = self._click.poll(dt)
        backed, _ = self._back.poll(dt)
        if clicked and under is not None:
            self.place_focus(under)
        if backed:
            self.close()
            return
        if committed or confirmed or (clicked and under is not None):
            self.confirm()
        if not self._open:
            return
        self._refresh()

    def _pointed_at(self) -> tuple[tuple[str, int] | None, bool]:
        """The entry under the pointer, and whether the pointer has moved.

        A mount answers to its box and to its label both: the box is fifteen
        pixels across, which is a target for the eye rather than for a mouse.
        """
        position = Input.mouse_position
        point = (float(position.x), float(position.y))
        moved = self._pointer is not None and point != self._pointer
        self._pointer = point
        for index, box in enumerate(self._slot_boxes):
            label = self._slot_labels[index] if index < len(self._slot_labels) else None
            if _rect_holds(box.get_global_rect(), point) or (
                label is not None and label.text and _rect_holds(label.get_global_rect(), point)
            ):
                return (self.COLUMN_HULL, index), moved
        for index, row in enumerate(self._locker_rows):
            if index < len(self.locker()) and _rect_holds(row.get_global_rect(), point):
                return (self.COLUMN_LOCKER, index), moved
        for index, row in enumerate(self._action_rows):
            if _rect_holds(row.get_global_rect(), point):
                return (self.ACTIONS[index], index), moved
        return None, moved

    # -- drawing -----------------------------------------------------------

    def _build(self) -> None:
        """Place every control, once, from the window rect it will keep."""
        if self._backdrop is not None:
            self._backdrop.destroy()
        self._slot_boxes.clear()
        self._slot_labels.clear()
        self._locker_rows.clear()
        self._locker_labels.clear()
        self._action_rows.clear()
        self._action_labels.clear()
        self._preview.clear()
        self._slot_chars.clear()

        window = self.get_global_rect()
        self._window = window
        _, _, width, height = (float(value) for value in window)
        room_w = max(1.0, width - 2.0 * MENU_WINDOW_MARGIN_PX)
        room_h = max(1.0, height - 2.0 * MENU_WINDOW_MARGIN_PX)
        scale = max(REFIT_MIN_SCALE, min(1.0, room_w / REFIT_BASE_WIDTH_PX, room_h / REFIT_BASE_HEIGHT_PX))
        panel_w = min(room_w, REFIT_BASE_WIDTH_PX * scale)
        panel_h = min(room_h, REFIT_BASE_HEIGHT_PX * scale)
        panel_x = (width - panel_w) / 2.0
        panel_y = (height - panel_h) / 2.0

        self._backdrop = self.add_child(Panel(name="Backdrop", anchor=Anchor.FULL_RECT))
        self._backdrop.bg_colour = MENU_BACKDROP
        # Drawn only, like everything it carries: this screen hit-tests its own
        # slots and reads ``fire_primary`` for the click, and a backdrop that
        # claimed the press would be the one control that swallowed it.
        self._backdrop.pointer_filter = PointerFilter.IGNORE
        panel = self._place(Panel(name="Panel"), panel_x, panel_y, panel_w, panel_h)
        panel.bg_colour = MENU_PANEL

        pad = REFIT_PAD_PX * scale
        line = REFIT_LINE_HEIGHT_PX * scale
        title_h = REFIT_TITLE_FONT_PX * scale * 1.4
        x0, y0 = panel_x + pad, panel_y + pad
        inner_w = panel_w - 2.0 * pad
        # Six footer lines: two of preview, the status, the two action rows and
        # the key legend. Measured off the bottom so the body takes what is left.
        body_y = y0 + title_h + line
        body_h = max(line * 2.0, panel_h - 2.0 * pad - title_h - line - 6.0 * line)

        self._text(REFIT_TITLE, x0, y0, inner_w, title_h, REFIT_TITLE_FONT_PX * scale, MENU_TITLE_COLOUR)
        self._text(REFIT_SUBTITLE, x0, y0 + title_h, inner_w, line, REFIT_ROW_FONT_PX * scale, MENU_DIM_COLOUR)

        diagram_w = inner_w * REFIT_DIAGRAM_FRACTION
        gap = REFIT_GAP_PX * scale
        self._build_diagram(x0, body_y, diagram_w, body_h, scale)
        self._build_locker(x0 + diagram_w + gap, body_y, inner_w - diagram_w - gap, body_h, scale)

        footer_y = body_y + body_h
        row_font = REFIT_ROW_FONT_PX * scale
        self._preview = [
            self._text("", x0, footer_y + index * line, inner_w, line, row_font, MENU_TEXT_COLOUR) for index in range(2)
        ]
        self._preview_font = _refit_font(row_font)
        self._preview_width = inner_w
        self._preview_chars = _row_chars(inner_w, row_font)
        self._status_row = self._text("", x0, footer_y + 2.0 * line, inner_w, line, row_font, MENU_DIM_COLOUR)
        for index, _action in enumerate(self.ACTIONS):
            top = footer_y + (3.0 + index) * line
            row = self._plate(x0, top, inner_w, line * 0.92, scale)
            label = self._text("", x0 + pad * 0.5, top, inner_w - pad, line, row_font)
            self._action_rows.append(row)
            self._action_labels.append(label)
        self._text(
            REFIT_CONTROLS_LINE, x0, footer_y + 5.0 * line, inner_w, line, REFIT_SLOT_FONT_PX * scale, MENU_DIM_COLOUR
        )
        self._refresh()

    def _build_diagram(self, x: float, y: float, width: float, height: float, scale: float) -> None:
        """Draw the hull plan and put a box on every mount it carries.

        The plan is scaled to fit its box *including* the room the labels take,
        so a mount's name is cut to the space beside it rather than running out
        through the side of the panel. Port labels are right-aligned in a rect
        that ends at the mount, starboard ones left-aligned in a rect that
        starts there: the text hugs its mount at any length without the rect
        ever having to move when the name under it changes.
        """
        line = REFIT_LINE_HEIGHT_PX * scale
        self._text(REFIT_HULL_HEADING, x, y, width, line, REFIT_SLOT_FONT_PX * scale, MENU_DIM_COLOUR)
        top = y + line
        height = max(1.0, height - line)

        hull_x = [abs(sx) + sw / 2.0 for sx, _sz, sw, _sd in REFIT_HULL_SHAPES]
        hull_z = [abs(sz) + sd / 2.0 for _sx, sz, _sw, sd in REFIT_HULL_SHAPES]
        half_x = max([*hull_x, *(abs(slot.x) for slot in self.slots), 1.0])
        half_z = max([*hull_z, *(abs(slot.z) for slot in self.slots), 1.0])
        unit = min(width / (2.0 * (half_x + REFIT_LABEL_ROOM_UNITS)), height / (2.0 * (half_z + 0.3)))
        centre_x, centre_y = x + width / 2.0, top + height / 2.0

        for shape_x, shape_z, shape_w, shape_d in REFIT_HULL_SHAPES:
            plate = self._plate(
                centre_x + (shape_x - shape_w / 2.0) * unit,
                centre_y + (shape_z - shape_d / 2.0) * unit,
                shape_w * unit,
                shape_d * unit,
                scale,
                colour=REFIT_HULL_COLOUR,
                border=REFIT_HULL_EDGE_COLOUR,
            )
            del plate

        marker = REFIT_MARKER_PX * scale
        font = REFIT_SLOT_FONT_PX * scale
        label_h = font * 1.4
        for slot in self.slots:
            mark_x, mark_y = centre_x + slot.x * unit, centre_y + slot.z * unit
            self._slot_boxes.append(self._plate(mark_x - marker / 2.0, mark_y - marker / 2.0, marker, marker, scale))
            if abs(slot.x) <= REFIT_CENTRELINE_UNITS:
                room = width / 2.0
                label_x = mark_x - room / 2.0
                label_y = mark_y - marker / 2.0 - label_h if slot.z < 0.0 else mark_y + marker / 2.0
                alignment = "centre"
            elif slot.x < 0.0:
                room = max(font, mark_x - marker / 2.0 - x - font * 0.5)
                label_x, label_y, alignment = x, mark_y - label_h / 2.0, "right"
            else:
                room = max(font, x + width - mark_x - marker / 2.0 - font * 0.5)
                label_x, label_y, alignment = mark_x + marker / 2.0 + font * 0.5, mark_y - label_h / 2.0, "left"
            label = self._text("", label_x, label_y, room, label_h, font)
            label.alignment = alignment
            self._slot_labels.append(label)
            self._slot_chars.append(_row_chars(room, font))

    def _build_locker(self, x: float, y: float, width: float, height: float, scale: float) -> None:
        """Allocate a row for everything that could ever be in the locker.

        The bound is what is in it now plus one per mount: nothing else can put
        anything in it while the panel is up, and unmounting the whole hull is
        the worst it can come to. Allocating for that is what lets the column
        stay exactly where it was drawn for the life of the visit.
        """
        line = REFIT_LINE_HEIGHT_PX * scale
        font = REFIT_ROW_FONT_PX * scale
        self._locker_heading = self._text(
            REFIT_LOCKER_HEADING, x, y, width, line, REFIT_SLOT_FONT_PX * scale, MENU_DIM_COLOUR
        )
        allocated = max(1, len(self.locker()) + len(self.slots))
        row_h = min(line, max(1.0, (height - line) / allocated))
        font = min(font, row_h * 0.62)
        pad = REFIT_PAD_PX * scale * 0.5
        self._locker_chars = _row_chars(width - 2.0 * pad, font)
        for index in range(allocated):
            top = y + line + index * row_h
            self._locker_rows.append(self._plate(x, top, width, row_h * 0.92, scale))
            self._locker_labels.append(self._text("", x + pad, top, width - 2.0 * pad, row_h, font))

    def _place(self, control: Control, x: float, y: float, width: float, height: float) -> Control:
        """Mount *control* on the backdrop at an absolute rect, once and for good."""
        control.margin_left, control.margin_top = float(x), float(y)
        control.size_x, control.size_y = float(width), float(height)
        control.pointer_filter = PointerFilter.IGNORE
        return self._backdrop.add_child(control)

    def _plate(self, x: float, y: float, width: float, height: float, scale: float, *, colour=None, border=None):
        """One placed panel with a border that a later colour change can show.

        The order is load-bearing: the engine builds a panel's style box from
        whichever of the two colours is set first and gives it no border until
        one is asked for, so a plate whose width is set before its fill draws
        its ring at zero pixels for the life of the screen.
        """
        plate = self._place(Panel(), x, y, width, height)
        plate.bg_colour = colour if colour is not None else REFIT_ROW_COLOUR
        plate.border_colour = border if border is not None else REFIT_SLOT_EDGE_COLOUR
        plate.border_width = REFIT_BORDER_PX * scale
        return plate

    def _text(self, text: str, x: float, y: float, width: float, height: float, font: float, colour=None) -> Label:
        """One placed line of type, never smaller than the engine will draw."""
        label = self._place(Label(text, size_x=width, size_y=height), x, y, width, height)
        label.font_size = _refit_font(font)
        label.text_colour = Colour.coerce(colour or MENU_TEXT_COLOUR, name="refit")
        return label

    def _refresh(self) -> None:
        """Rewrite every line and re-colour every ring. Nothing moves."""
        for index, slot in enumerate(self.slots):
            if index >= len(self._slot_boxes):
                break
            occupant = self.occupant(slot)
            focused = self.focus == (self.COLUMN_HULL, index)
            armed = self.armed == (self.COLUMN_HULL, index)
            box = self._slot_boxes[index]
            box.bg_colour = REFIT_SLOT_FILLED_COLOUR if occupant else REFIT_SLOT_BARE_COLOUR
            box.border_colour = _ring_colour(focused, armed, REFIT_SLOT_EDGE_COLOUR)
            label = self._slot_labels[index]
            name = _item_name(occupant) if occupant else REFIT_SLOT_EMPTY
            mark = REFIT_MARK_ARMED if armed else ""
            chars = self._slot_chars[index] if index < len(self._slot_chars) else len(name) + len(slot.tag) + 2
            _set_text(label, ellipsise(f"{mark}{slot.tag}: {name}", chars))
            label.text_colour = Colour.coerce(_ring_colour(focused, armed, MENU_TEXT_COLOUR), name="slot")

        rows = self.locker()
        for index, row in enumerate(self._locker_rows):
            label = self._locker_labels[index]
            if index >= len(rows):
                # An allocated row with nothing in it yet: kept, blank, at the
                # coordinates it was given, so filling it later moves nothing.
                _set_text(label, "")
                row.bg_colour = MENU_PANEL
                row.border_colour = MENU_PANEL
                continue
            item = rows[index]
            focused = self.focus == (self.COLUMN_LOCKER, index)
            armed = self.armed == (self.COLUMN_LOCKER, index)
            item_id = str(item["id"])
            text = REFIT_LOCKER_ROW.format(
                name=_item_name(item_id), kind=str(item["kind"]), summary=item_summary(item_id)
            )
            _set_text(label, ellipsise(f"{REFIT_MARK_ARMED if armed else ' '}{text}", self._locker_chars))
            label.text_colour = Colour.coerce(_ring_colour(focused, armed, MENU_TEXT_COLOUR), name="locker")
            row.bg_colour = REFIT_ROW_COLOUR
            row.border_colour = _ring_colour(focused, armed, REFIT_ROW_COLOUR)

        if self._locker_heading is not None:
            _set_text(self._locker_heading, REFIT_LOCKER_HEADING if rows else REFIT_LOCKER_EMPTY)

        for index, action in enumerate(self.ACTIONS):
            focused = self.focus == (action, index)
            text = REFIT_ACTION_UNMOUNT if action == self.ACTION_UNMOUNT else REFIT_ACTION_DONE
            label = self._action_labels[index]
            _set_text(label, f"{MENU_CURSOR_LEFT} {text} {MENU_CURSOR_RIGHT}" if focused else f"  {text}")
            label.text_colour = Colour.coerce(_ring_colour(focused, False, MENU_TEXT_COLOUR), name="action")
            self._action_rows[index].border_colour = _ring_colour(focused, False, REFIT_ROW_COLOUR)

        refused = bool(self.refusal())
        lines = wrap_prose(self.preview(), self._preview_font, self._preview_width)
        for index, label in enumerate(self._preview):
            _set_text(label, lines[index] if index < len(lines) else "")
            label.text_colour = Colour.coerce(REFIT_REFUSED_COLOUR if refused else MENU_TEXT_COLOUR, name="preview")
        if self._status_row is not None:
            _set_text(self._status_row, ellipsise(self.status, self._preview_chars))


def _ring_colour(focused: bool, armed: bool, resting):
    """The focus ring's colour: focus wins, then the armed pick, then nothing."""
    if focused:
        return REFIT_FOCUS_COLOUR
    if armed:
        return REFIT_ARMED_COLOUR
    return resting


def _row_chars(width: float, font: float) -> int:
    """How many characters fit across *width* at *font*, at least one."""
    return max(1, int(width / max(1.0, _refit_font(font) * MENU_GLYPH_ADVANCE_FRACTION)))


def _refit_font(size: float) -> float:
    """The size the engine will really draw *size* at, floor included."""
    return max(REFIT_MIN_FONT_PX, float(size))


class WakeTerritoryDirector(HunterDirector):
    """The arrival ladder, with the chart's swept ground folded into it.

    ``hunter.HunterDirector`` compresses its warning for repeat arrivals and
    for a muffling biome, and both of those are properties of the sector it has
    been told about. Whether that sector sits inside the Wake is a property of
    the chart, which the ladder has no route to and no business knowing, so the
    run scene owns the answer and hands it down exactly the way it hands down
    the biome. Compression takes a ``min`` on both counts: the Shrike never
    gives a longer warning because a rule stacked the other way.
    """

    def __init__(self, *, wake_territory: bool = False, **kwargs):
        super().__init__(**kwargs)
        self.wake_territory = bool(wake_territory)

    def set_wake_territory(self, active: bool) -> None:
        """Say whether the sector now being flown is ground the front has taken."""
        self.wake_territory = bool(active)

    def telegraph_seconds(self, arrival_index: int) -> float:
        seconds = super().telegraph_seconds(arrival_index)
        if self.wake_territory:
            seconds = min(seconds, WAKE_TERRITORY_TELEGRAPH_S)
        return seconds


class RunScene(ShrikeScene):
    """One run: the assembled world, the two endings, and the collapse rule."""

    run_started = Signal(dict)
    run_ended = Signal(str, dict)
    last_stand_triggered = Signal()
    extraction_completed = Signal(dict)

    def __init__(self, config: dict | None = None, **kwargs):
        kwargs.setdefault("name", "Run")
        super().__init__(**kwargs)
        self.config_dict = dict(config) if config else RunConfig().as_dict()
        #: Set by the menu when a suspend slot is being resumed.
        self.resume_state: RunState | None = None

        self.state: RunState | None = None
        self.onboarding_schedule = Onboarding(int(self.config_dict.get("run_number", 1)))
        self.running = False
        self.ended = False

        self.power: PowerSystem | None = None
        self.signature: SignatureMeter | None = None
        self.economy: Economy | None = None
        self.notoriety: Node | None = None
        self.damage: DamageRouter | None = None
        self.juice: JuiceDirector | None = None
        self.audio: Node | None = None
        self.waves: WaveComposer | None = None

        self.environment = None
        self.rig: CameraRig | None = None
        self.ship: PlayerShip | None = None
        self.rack: WeaponRack | None = None
        self.sockets: SocketRack | None = None
        self.hunter_director: WakeTerritoryDirector | None = None
        #: Whether this sector was already swept when the hull arrived in it.
        #: The arrival says so once; the front closing on a sector that was
        #: clean is the other announcement, and one jump never earns both.
        self._arrived_in_wake = False
        self.hud: Hud | None = None
        #: Wings state and generator state as they stood before this frame's
        #: input, so a key's answer never depends on node update order.
        self._power_state_seen: tuple[str, bool | None] | None = None
        self.chart_screen: StarChart | None = None
        self.pause_screen: PauseScene | None = None
        self.depot_screen: DepotScene | None = None
        self.refit_screen: RefitScene | None = None
        self.onboarding: OnboardingDirector | None = None
        self.sector: Sector | None = None
        self.depot: Depot | None = None

        #: Weapons bought with every hardpoint full, waiting for a mount.
        self.stowed_weapons: list[str] = []
        #: Modules pulled out of a socket at the refit panel, waiting for one.
        #: A purchase never lands here: it is socketed or refused at the till.
        self.stowed_modules: list[str] = []

        self.last_stand = False
        self.last_stand_offered = False
        self._stranded_for = 0.0
        self._scrap_earned_at_trigger = 0.0
        #: A spool has started and has not yet been matched to a destination.
        self._spool_unresolved = False
        #: The chart has bought a jump that is still in the channel.
        self._jump_committed = False
        #: Who the hull was lost to, held while the death settles. None until
        #: the hull reaches zero; see :meth:`_on_ship_destroyed`.
        self._death_killer: str | None = None
        self._death_wait = 0.0
        #: The bearing toward whatever last got through the hull, and when.
        self._last_hit_bearing: Vec3 | None = None
        self._last_hit_at = -KILLER_ATTRIBUTION_WINDOW_S
        self._scrap_toast_amount = 0.0
        self._scrap_toast_wait = 0.0
        self._ammo_rounds_bank = 0.0
        self._service_names: list[str] = []
        self._pool = ModulePool()
        self._wiring = SignalWiring(self)

    # ------------------------------------------------------------------ boot

    def on_ready(self):
        if not self.running:
            self.begin_run(self.config_dict)

    def begin_run(self, config: dict) -> None:
        """Assemble the world for *config* and start the run."""
        if self.running:
            raise RuntimeError("this run has already begun")
        self.config_dict = dict(config)
        run_config = RunConfig.from_dict(self.config_dict)
        resumed = self.resume_state is not None
        self.state = self.resume_state if resumed else RunState(run_config)
        self.onboarding_schedule = Onboarding(self.state.run_number)

        self._build_services()
        self._build_world()
        self._wire_ledger()
        self.settings().apply_to_run(self)
        self._apply_hull()
        self.enter_sector(self.state.current_node_id, first=True)
        if resumed and self.state.restore is not None:
            self._apply_restore(self.state.restore)
            self.state.restore = None

        profile = self.profile()
        if not resumed:
            profile["runs_started"] = int(profile.get("runs_started", 0)) + 1
            # Written here rather than left for the ledger. The counter is the
            # only input the onboarding schedule has, so a run that reaches the
            # world and never reaches an ending must still count: a profile
            # written only at end_run or at a suspend would keep a pilot who
            # closes the window mid-flight on run one for ever, with no chart,
            # no ballistics and no silent running, however many times they fly.
            self.save_system().save_profile(profile)
        self.running = True
        self.run_started.emit(dict(self.config_dict))

    def _build_services(self) -> None:
        tree = self.tree
        settings = self.settings()
        state = self.state

        self.power = PowerSystem(name="PowerSystem")
        # The onboarding schedule: silent running is a run-3 lesson. Before that
        # the key is answered, not obeyed, so the posture never acts invisibly
        # on a run whose HUD is not allowed to show it.
        self.power.silent_running_enabled = self.onboarding_schedule.silent_running_available()
        self.signature = SignatureMeter(name="SignatureMeter", act=state.act)
        self.economy = Economy(name="Economy")
        self.notoriety = Notoriety(name="Notoriety")
        self.damage = DamageRouter(name="DamageRouter", seed=state.seed)
        self.juice = JuiceDirector(name="JuiceDirector", shake_scale=settings.shake, hit_stop_scale=settings.hit_stop)
        self.waves = WaveComposer(name="WaveComposer")
        self.audio = _make_audio()

        services = [
            (Services.POWER, self.power),
            (Services.SIGNATURE, self.signature),
            (Services.ECONOMY, self.economy),
            (Services.NOTORIETY, self.notoriety),
            (Services.DAMAGE, self.damage),
            (Services.JUICE, self.juice),
            (Services.WAVES, self.waves),
        ]
        if self.audio is not None:
            services.append((Services.AUDIO, self.audio))
        for name, node in services:
            tree.add_singleton(name, node)
            self._service_names.append(name)

    def _build_world(self) -> None:
        state = self.state
        self.environment = self.add_child(artkit.build_environment(state.act, state.seed))
        sun = self.add_child(DirectionalLight3D(name="Sun"))
        sun.direction = SUN_DIRECTION
        sun.colour = SUN_COLOUR
        sun.intensity = SUN_INTENSITY

        self.rig = self.add_child(CameraRig(name="CameraRig"))
        self.ship = self.add_child(
            PlayerShip(name="Ship", hull_id=state.config.hull_id, position=Vec3(0.0, PLANE_Y, 0.0))
        )
        self.sockets = self.ship.add_child(SocketRack(state.config.hull_id))
        self.rack = self.ship.add_child(WeaponRack(hardpoints=self.ship.hardpoint_count))
        for hardpoint, weapon_id in enumerate(STARTER_WEAPONS[: self.ship.hardpoint_count]):
            self.rack.equip(weapon_id, hardpoint)
        self._fit_starter_power()
        self.rig.set_target(self.ship)

        self.hunter_director = self.add_child(WakeTerritoryDirector(name="HunterDirector", seed=state.seed))
        self.hud = self.add_child(Hud(name="Hud"))
        self.tree.add_singleton(Services.HUD, self.hud)
        self._service_names.append(Services.HUD)
        self.chart_screen = self.add_child(StarChart(name="StarChart"))
        self.chart_screen.run_state = state
        self.chart_screen.graph = state.chart
        self.chart_screen.current_node_id = state.current_node_id
        self.chart_screen.jumps_taken = state.jumps_taken
        self.chart_screen.jump_completed.connect(self._on_jump_completed)
        self.chart_screen.jump_started.connect(self._on_jump_started)
        self.chart_screen.wake_advanced.connect(self._on_wake_advanced)
        # Every spool is answered, whoever started it: the chart's confirm
        # button labels the ring, and a bare press of the drive key is either
        # matched to a destination or told what it is missing.
        self.ship.warp_spool_started.connect(self._on_warp_spool_started)
        self.ship.warp_spool_cancelled.connect(self._on_warp_spool_cancelled)
        self.ship.warp_completed.connect(self._on_warp_completed)
        if not self.onboarding_schedule.chart_open():
            # Run one flies a fixed gentle route: the screen still owns the
            # jump machinery, it simply does not take the player's input. The
            # route is taken by spooling the drive, which is the deliberate,
            # interruptible, diegetic act the chart's confirm button is.
            self.chart_screen.update_mode = UpdateMode.DISABLED
        # Nothing on the strip may name a key whose answer is "not yet": the
        # chart before run two, silent running before run three.
        self.hud.set_controls_bar(*controls_bar_rows(self.onboarding_schedule))

        self.pause_screen = self.add_child(PauseScene(self))
        self.depot_screen = self.add_child(DepotScene(self))
        # After the dock screen, so the refit panel draws over the shelf it is
        # raised from rather than under it.
        self.refit_screen = self.add_child(RefitScene(self))
        # The run's action map is declared on this node, and a node the pause
        # has put to sleep declares nothing. The screens that hold the pause
        # read the same actions while it is on, so each carries the map too.
        for screen in (self.chart_screen, self.pause_screen, self.depot_screen, self.refit_screen):
            screen.input_context = self.input_context
        self.onboarding = self.add_child(
            OnboardingDirector(name="Onboarding", onboarding=self.onboarding_schedule, profile=self.profile())
        )

    def _fit_starter_power(self) -> None:
        """Socket the hull's starter power source, if any mount takes one.

        Without a source the capacitor is a non-renewable hundred points and
        the solar and generator actions are dead keys, so every hull launches
        with the first entry in :data:`STARTER_POWER` it can physically carry.
        """
        for module_id in STARTER_POWER:
            size = str(module_spec(module_id)["socket_size"])
            free = self.sockets.free_sockets(size)
            if free:
                self.sockets.install(module_id, free[-1].index)
                return

    def _apply_hull(self) -> None:
        """Fold the hull choice and the doctrine bag into the systems flow owns.

        Only the effects whose consumer this module builds are applied here;
        everything else reads the same bag off ``RUN_STARTED``.
        """
        hull_id = self.state.config.hull_id
        modifiers = self.state.config.modifiers
        if hull_id == "dart" and self.signature is not None:
            self.signature.set_gain_multiplier("hull", balance.DART_SIGNATURE_FILL_MULT)
        capacitor_bonus = float(modifiers.get("capacitor_max_bonus", 0.0))
        if capacitor_bonus and self.power is not None:
            self.power.set_capacitor_max(self.power.capacitor_max + capacitor_bonus)
        fill = float(modifiers.get("signature_fill_mult", 1.0))
        if fill != 1.0 and self.signature is not None:
            self.signature.set_gain_multiplier("doctrine", fill)

    def _wire_ledger(self) -> None:
        """Subscribe the ledger to everything a run is judged on.

        The hunter's signals go through :class:`~shrike.power.SignalWiring`
        because the Shrike is spawned mid-run and replaced on every arrival:
        a one-shot connect in here would only ever see the first one.
        """
        ledger = self.state.ledger
        ledger.assists = self.settings().assists_in_use()
        self.ship.ship_destroyed.connect(self._on_ship_destroyed)
        self.damage.enemy_killed.connect(self._on_enemy_killed)
        # Through the wiring rather than a direct connect: the hunter emits its
        # burns itself, and it is spawned mid-run, after any one-shot connect.
        self._wiring.want(SignalNames.PLAYER_DAMAGED, self._on_player_damaged)
        self.economy.cores_banked.connect(self._on_cores_banked)
        self._wiring.want(SignalNames.HUNTER_DEPARTED, self._on_arrival_survived)
        self._wiring.want(SignalNames.QUILL_SHEARED, self._on_quill)
        self._wiring.sweep()

    # -------------------------------------------------------------- sectors

    def enter_sector(self, node_id: str, *, first: bool = False) -> None:
        """Generate and mount the sector at *node_id*, or end the run at the Gate.

        Charted lanes run both ways, so this is also the retreat path, and two
        things here are what stop a retreat being a farm. The act, the wave
        budget and the drop tables follow the deepest sector the run has ever
        reached rather than the column it is standing in, so falling back
        cannot soften the game. And a node the run has already stood in is
        dealt again stripped, so the ore is not there twice.
        """
        state = self.state
        node = state.chart.nodes[node_id]
        if node.is_deep_gate and not first:
            self.extract()
            return
        if node.is_roost:
            self.enter_roost()
            return
        # Harmless to call every jump, and the Lure can be assembled mid-run.
        roost.reveal_roost_node(state.chart, self.profile())

        arrived_from = state.current_node_id
        revisited = node_id in state.visited
        if arrived_from and arrived_from != node_id:
            state.visited.add(arrived_from)
        state.current_node_id = node_id
        ledger = state.ledger
        state.sector_index = max(ledger.deepest_sector, node.column + 1)
        state.biome_id = node.biome
        ledger.deepest_sector = max(ledger.deepest_sector, state.sector_index)
        ledger.sectors_visited = max(ledger.sectors_visited, state.jumps_taken + 1)

        if self.sector is not None:
            self.sector.destroy()
        if self.depot is not None:
            if self.depot_screen is not None:
                self.depot_screen.close()
            self.depot.destroy()
            self.depot = None

        self.signature.set_act(state.act)
        self.signature.reset_for_sector()
        # Beside the meter's own reset and for the same reason: what the last
        # sector was saying is not true here. Before the announcements below,
        # so the arrival card and the objective are what survives the sweep.
        if self.hud is not None:
            self.hud.reset_for_sector()
        self.hunter_director.set_biome(state.biome_id)
        self.hunter_director.set_wake_territory(node.consumed)
        self._arrived_in_wake = bool(node.consumed)
        if self.onboarding is not None:
            self.onboarding.set_sector(state.sector_index)
            # The sweep took the card with the rest of the glass. A lesson the
            # pilot is halfway through is not a thing the old sector owned, so
            # the schedule puts its live card straight back up.
            self.onboarding.restore_card()

        self._place_at_warp_anchor()

        self.sector = self.add_child(
            Sector(
                name="Sector",
                sector_index=state.sector_index,
                biome_id=state.biome_id,
                seed=state.sector_seed(),
                deck=state.deck,
                has_depot=self._edge_has_depot(arrived_from, node_id),
                chart_offline=not self.onboarding_schedule.chart_open(),
                revisited=revisited,
            )
        )
        # The sector is the one authority on whether a dock exists here: it
        # folds the edge roll together with the opening-sector guarantee, and
        # asking the edge again would lose the guarantee half of that answer.
        has_depot = self.sector.has_depot
        self.sector.vault_hacked.connect(self._on_vault_hacked)
        self.sector.resource_collected.connect(self._on_resource_collected)
        if has_depot:
            self._mount_depot()
        self._show_depot_route(node_id, has_depot)
        self._arm_default_warp()
        self._announce_arrival()
        # After the sector, never before it: the meter is reset by the
        # ``SECTOR_ENTERED`` the generator emits, so a signature written above
        # would be wiped by the arrival it was written for.
        if node.consumed:
            self._go_wake_territory(caught=False)
        self._announce_objective(has_depot)
        self.waves.start(state.sector_index, state.biome_id, state.sector_seed(), run_number=state.run_number)

    def _arm_default_warp(self) -> None:
        """Point the drive at a lane the moment the hull arrives somewhere.

        An arrival that left the drive pointing nowhere would make the first
        press of the drive key in every sector buy a refusal rather than a jump,
        and the chip could only say "pick destination (M)": the pilot would have
        to open a screen and confirm a choice before the key they had already
        been taught did anything at all. The arming is the chart's own default
        rule, so what an unread ``R`` buys and what an unread ``F`` on the chart
        buys are the same lane, and neither is swept ground.

        Run one is left alone. Its drive flies a surveyed route it picks for
        itself at the press, the cheapest way onward rather than the deepest,
        and a lane armed off a chart that run has not been given would leave
        the chip quoting one destination while the key flew to another.
        """
        chart = self.chart_screen
        if chart is None or not self.onboarding_schedule.chart_open():
            return
        chart.arm_default()

    def _place_at_warp_anchor(self) -> None:
        """Drop the hull on the new sector's warp-in point, dead in the water.

        A jump that left the ship wherever the last sector left it would drop a
        pilot who fought their way to the right-hand rim on the rim of the next
        sector too, staring at the void: the generator clusters the first
        features within ``sector.SECTOR_NEAR_RADIUS`` of the anchor, and
        nobody would be at the anchor to see them. Carried speed goes with the
        position, because arriving already at cruise into an unread screen is
        the same lost second. The rig cuts rather than eases, and the arrival
        flash covers the cut.
        """
        if self.ship is None:
            return
        self.ship.position = Vec3(Sector.warp_anchor)
        self.ship.velocity = Vec2(0.0, 0.0)
        self._cut_camera_to_ship()

    def _cut_camera_to_ship(self) -> None:
        """Put the rig on the hull with no follow lag, aim lead included."""
        if self.rig is None or self.ship is None:
            return
        self.rig.set_aim(Vec3(self.ship.position))
        self.rig.snap()

    def _show_depot_route(self, node_id: str, has_depot: bool) -> None:
        """Point the pilot at whatever this hold can actually be spent on.

        A depot in the sector gets the HUD's beacon and a live range. With no
        depot here, the nearest one being a single jump out is what this
        sector's objective says instead, because "scrap with nothing to do with
        it" is a chart the player never opened rather than an economy that is
        missing.
        """
        del node_id
        hud = self.hud
        if hud is None:
            return
        if has_depot and self.depot is not None:
            hud.set_depot_beacon(Vec3(self.depot.position))
            return
        hud.set_depot_beacon(None)

    def sector_title(self) -> str:
        """The place's name, in the chart's own spelling.

        Not the biome: a chart deals a biome three or four times and gives each
        one a name no other node answers to, so an arrival card printing the
        bare biome would name a different place from the jump button that
        bought the trip.
        """
        node = self.state.chart.nodes.get(self.state.current_node_id)
        if node is not None:
            return node.label
        return str(self.state.biome_id).replace("_", " ").upper()

    def _announce_arrival(self) -> None:
        """Name the sector on arrival, and leave the name standing in the corner.

        Without a name a jump lands the hull in a field of rocks that looks
        exactly like the field it left, and a pilot can fly three sectors
        without ever being sure one has happened. The card is the moment and
        the corner is the record.
        """
        hud = self.hud
        if hud is None:
            return
        state = self.state
        node = state.chart.nodes.get(state.current_node_id)
        # Swept ground is the one thing about a place that outranks the biome:
        # what this sector is like matters less than who has been through it.
        swept = node is not None and node.consumed
        flavour = WAKE_TERRITORY_FLAVOUR if swept else SECTOR_FLAVOUR.get(state.biome_id, "")
        hud.show_arrival_card(self.sector_title(), flavour)

    def objective_line(self, has_depot: bool = False) -> str:
        """The one sentence this sector is for, in the pilot's own terms.

        Without it a pilot can fly three sectors and never be told the game
        has a goal: the HUD prices everything and asks for nothing. Run one is
        scripted, because the pilot has no chart to reason with; every run
        after it reads the state it is actually in, in priority order, and the
        Gate line quotes the fuel so the last jump is never a surprise.
        """
        state = self.state
        if not self.onboarding_schedule.chart_open():
            return OBJECTIVE_RUN_1
        graph = state.chart
        scrap = float(self.economy.scrap) if self.economy is not None else 0.0
        if has_depot and scrap >= OBJECTIVE_BANK_SCRAP:
            return OBJECTIVE_BANK
        gate = next((node for node in graph.nodes.values() if node.is_deep_gate), None)
        here = graph.nodes.get(state.current_node_id)
        columns = max(0, gate.column - here.column) if gate is not None and here is not None else 1
        if gate is not None and columns <= 1:
            # The last jump outranks every other errand: it is the one that
            # decides whether any of the hold is ever banked.
            quote = next((d.quote.total for d in self.chart_screen.destinations() if d.node_id == gate.id), 0.0)
            return OBJECTIVE_GATE.format(fuel=quote)
        if not has_depot and scrap >= OBJECTIVE_BANK_SCRAP:
            # Most nodes have a depot somewhere on their fan, so this is only
            # an objective once there is a hold worth taking to one.
            if any(edge.depot for edge in graph.edges_from(state.current_node_id)):
                return DEPOT_ONE_JUMP_TOAST
        return OBJECTIVE_ONWARD.format(columns=columns)

    def _announce_objective(self, has_depot: bool) -> None:
        """Push this sector's objective onto the HUD's standing objective line.

        The line stands until the next sector replaces it, so "what am I here
        for" has an answer minutes after arrival, not just for a toast's three
        seconds.
        """
        hud = self.hud
        line = self.objective_line(has_depot)
        if hud is None or not line:
            return
        hud.set_objective(line)

    def _edge_has_depot(self, source_id: str, node_id: str) -> bool:
        """Whether the lane actually flown into *node_id* carried a drift depot.

        The lane, not the fan: whether *any* node on the map has a depot edge
        into here is generous, and nearly always true because every lane runs
        both ways. A depot is moored on
        one line, and the line the ship flew is the one that decides.
        """
        edge = self.state.chart.edge_between(source_id, node_id)
        return edge is not None and edge.depot

    def _mount_depot(self) -> None:
        state = self.state
        anchor = self.sector.depot_anchor
        position = from_plane(anchor) if anchor is not None else Vec3(20.0, PLANE_Y, 0.0)
        broker = state.biome_id == "broker_claim"
        factory = Broker if broker else Depot
        self.depot = self.add_child(
            factory(
                name="Depot",
                seed=state.sector_seed(),
                act=state.act,
                pool=self._pool,
                position=position,
            )
        )
        # A revisited dock is the same dock. Its shelf already rebuilds
        # identically from the node's seed; handing it back the same purchase
        # counter is what stops a round trip re-stocking the once-per-visit
        # rows a pilot has already bought out.
        self.depot.purchases = state.depot_purchases.setdefault(state.current_node_id, {})
        self.depot.purchase_gate = self._purchase_gate
        self.depot.item_purchased.connect(self._on_item_purchased)
        self.depot.weapon_swapped.connect(self._on_weapon_swapped)
        self.depot.docked.connect(self._on_docked)
        self.depot.undocked.connect(self._on_undocked)

    def build_profile(self) -> dict:
        """How a shelf reads this ship: the act, the fit, and the world pool.

        The pity slot leans on what is already flown, and the tier band comes
        off the act, so a depot handed nothing would roll a shelf for a ship it
        has never seen.
        """
        state = self.state
        weapons = [weapon.spec.id for weapon in self.rack.weapons()] if self.rack is not None else []
        modules = list(self.sockets.installed_ids()) if self.sockets is not None else []
        return {
            "act": state.act,
            "weapons": weapons,
            "modules": modules,
            "pool_unlocks": list(self._pool.expansions),
            ModulePool.PROFILE_KEY: list(self.profile().get(ModulePool.PROFILE_KEY, ())),
        }

    def _on_docked(self, depot_id: str) -> None:
        """Raise the dock screen. Docking is the only way scrap gets spent."""
        del depot_id
        if self.depot_screen is not None and self.depot is not None:
            self.depot_screen.open(self.depot)

    def _on_undocked(self) -> None:
        if self.depot_screen is not None:
            self.depot_screen.close()

    def _on_jump_completed(self, node_id: str) -> None:
        state = self.state
        state.jumps_taken = self.chart_screen.jumps_taken
        state.notoriety = int(getattr(self.notoriety, "value", 0))
        self.enter_sector(node_id)

    # ------------------------------------------------------------ the Wake

    def _on_wake_advanced(self, columns: int) -> None:
        """The front moved. If it moved onto this sector, it has caught up.

        The chart feeds the front after the arrival and clamps it to the hull's
        own column, so the only sector it can ever take is the one the ship is
        standing in, and only for a pilot who has been spending jumps going
        backwards. That is the whole point of the red band: it is not scenery
        behind you, it is a thing that closes.
        """
        del columns
        state = self.state
        node = state.chart.nodes.get(state.current_node_id)
        if node is None or not node.consumed or self._arrived_in_wake:
            # Already swept when the hull got here, so the arrival has said it
            # once and this is the same sentence twice.
            return
        self._arrived_in_wake = True
        self.hunter_director.set_wake_territory(True)
        self._go_wake_territory(caught=True)

    def _go_wake_territory(self, *, caught: bool) -> None:
        """Charge what the Wake's ground costs: a meter most of the way up.

        Arriving in it and being overtaken by it are the same state and read
        the same way, so they land here together and differ only in the words.
        The meter is written raw, because this is the mechanic rather than a
        gain: a wake damper does not make swept ground quieter.
        """
        signature = self.signature
        if signature is not None:
            wanted = WAKE_TERRITORY_SIGNATURE_START - float(signature.value)
            if wanted > 0.0:
                signature.add(wanted, "wake_territory", raw=True)
        hud = self.hud
        if hud is None:
            return
        hud.flash_stamp(WAKE_CAUGHT_STAMP if caught else WAKE_TERRITORY_STAMP)
        hud.show_toast(WAKE_CAUGHT_TOAST if caught else WAKE_TERRITORY_TOAST)

    # ------------------------------------------------------------- purchases

    def _purchase_gate(self, item: dict) -> bool:
        """Whether the hull can take *item*, asked by the depot before payment.

        A refusal names its reason on the toast line, so a full socket rack or
        a locker with nothing to feed costs a sentence rather than scrap.
        """
        refusal = self._purchase_refusal(item)
        if not refusal:
            return True
        if self.hud is not None:
            self.hud.show_toast(refusal)
        return False

    def _purchase_refusal(self, item: dict) -> str:
        """Why *item* cannot be taken aboard right now; empty when it can be."""
        item_id = str(item.get("id", ""))
        if item_id in MODULE_CATALOGUE:
            size = str(module_spec(item_id)["socket_size"])
            if not self.sockets.free_sockets(size):
                return f"NO FREE {size.upper()} SOCKET FOR THE {_item_name(item_id)}"
        elif item_id == "ammo_box" and self._ammo_eater() is None:
            return "NO BALLISTIC WEAPON TO FEED"
        elif item_id == "breach_patch" and self.ship.open_breaches <= 0:
            return "NO OPEN BREACH TO FOAM"
        return ""

    def _on_item_purchased(self, item_id: str, price: float) -> None:
        """Deliver a paid-for depot item to the run that bought it."""
        del price
        if item_id in MODULE_CATALOGUE:
            self._deliver_module(item_id)
        elif item_id in balance.WEAPONS:
            self._deliver_weapon(item_id)
        elif item_id in CONSUMABLES:
            self._deliver_consumable(item_id)

    def _deliver_module(self, module_id: str) -> None:
        """Socket a bought module on the stern-most mount that takes it.

        The gate has already vouched for a free socket, the same way the
        starter fit found one, so the install cannot fail after payment.
        """
        socket = self.sockets.socket_for(module_id)
        self.sockets.install(module_id, socket.index)
        self._purchase_toast(f"{_item_name(module_id)} INSTALLED, {socket.label} socket")

    def _deliver_weapon(self, weapon_id: str) -> None:
        """Bolt a bought weapon to a free hardpoint, or stow it when none is."""
        hardpoint = self.rack.free_hardpoint()
        if hardpoint is not None:
            self.rack.equip(weapon_id, hardpoint)
            self._purchase_toast(f"{_item_name(weapon_id)} MOUNTED, hardpoint {hardpoint + 1}")
            return
        self.stowed_weapons.append(weapon_id)
        self._purchase_toast(f"{_item_name(weapon_id)} STOWED: hardpoints full (swap at dock)")

    def _on_weapon_swapped(self, mounted: str, displaced: str, hardpoint: int) -> None:
        """Move a committed refit's ids between the locker and the hull.

        The depot performs the swap on the rack and this scene owns the
        stowage, so the ids cross here: the mounted gun leaves the locker and
        whatever it displaced takes its place. One list stays authoritative.
        """
        del hardpoint
        if mounted in self.stowed_weapons:
            self.stowed_weapons.remove(mounted)
        if displaced:
            self.stowed_weapons.append(displaced)

    # ------------------------------------------------------------- refitting
    #
    # The four moves a refit is made of. They live on the run rather than on
    # the panel that drives them because the run owns the locker: a gun coming
    # off a hardpoint and a module coming out of a socket land in the same
    # place, and one list per kind is what keeps that place authoritative.

    def mount_weapon(self, weapon_id: str, hardpoint: int) -> str | None:
        """Bolt a stowed gun to a hardpoint. Returns the id it displaced.

        The empty string for a bare mount, None when the bay refuses. The
        depot performs it, so a refit made here and one made by a script both
        announce themselves through ``weapon_swapped`` and both move the
        stowage through one handler.
        """
        depot = self.depot
        if depot is None or self.rack is None:
            return None
        return depot.swap_weapon(weapon_id, hardpoint)

    def unmount_weapon(self, hardpoint: int) -> str:
        """Strip a hardpoint into the locker. Returns the id that came off."""
        rack = self.rack
        if rack is None or not 0 <= hardpoint < len(rack.hardpoints):
            return ""
        fitted = rack.hardpoints[hardpoint]
        if fitted is None:
            return ""
        weapon_id = str(fitted.spec.id)
        rack.unequip(hardpoint)
        self.stowed_weapons.append(weapon_id)
        return weapon_id

    def install_module(self, module_id: str, socket_index: int) -> str | None:
        """Bolt a loose module into a socket. Returns the id it displaced.

        The empty string for a bare socket, None when the rack refused. A
        refusal puts back whatever was already in the socket: a swap that
        cannot complete must not cost the module that was working.
        """
        sockets = self.sockets
        if sockets is None or module_id not in MODULE_CATALOGUE:
            return None
        displaced = str(sockets.module_id_at(socket_index) or "") if 0 <= socket_index < len(sockets.sockets) else ""
        if displaced:
            sockets.remove(socket_index)
        try:
            sockets.install(module_id, socket_index)
        except ValueError:
            if displaced:
                sockets.install(displaced, socket_index)
            return None
        if module_id in self.stowed_modules:
            self.stowed_modules.remove(module_id)
        if displaced:
            self.stowed_modules.append(displaced)
        return displaced

    def uninstall_module(self, socket_index: int) -> str:
        """Strip a socket into the locker. Returns the id that came out."""
        sockets = self.sockets
        if sockets is None or not 0 <= socket_index < len(sockets.sockets):
            return ""
        module_id = str(sockets.module_id_at(socket_index) or "")
        if not module_id:
            return ""
        sockets.remove(socket_index)
        self.stowed_modules.append(module_id)
        return module_id

    def _deliver_consumable(self, item_id: str) -> None:
        """Apply a bought consumable to the run state at once."""
        if item_id == "ammo_box":
            weapon_id = self._ammo_eater()
            self.rack.add_ammo_box(weapon_id)
            self._purchase_toast(f"AMMO BOX STOWED FOR THE {_item_name(weapon_id)}")
        elif item_id == "o2_canister":
            self.power.add_o2(balance.DEPOT_O2_CANISTER_AMOUNT)
            self._purchase_toast(f"O2 +{balance.DEPOT_O2_CANISTER_AMOUNT:.0f}")
        elif item_id == "fuel_cell":
            self.power.add_fuel(balance.DEPOT_FUEL_AMOUNT)
            self._purchase_toast(f"FUEL +{balance.DEPOT_FUEL_AMOUNT:.0f}")
        elif item_id == "breach_patch":
            self.ship.seal_breach()
            self._purchase_toast("BREACH FOAMED SHUT")

    def _ammo_eater(self) -> str | None:
        """The mounted ballistic weapon a bought box feeds: the rack's own pick."""
        return self.rack.ammo_eater()

    def _purchase_toast(self, text: str) -> None:
        if self.hud is not None:
            self.hud.show_toast(text)

    # --------------------------------------------------------- doctrine kits

    def kit_offers(self) -> list[str]:
        """The Doctrine Kits the dock screen should print, or nothing.

        The pick is once per profile, ever: a profile that has taken one is
        never offered another, on this run or any later one. Until then every
        dock offers it, so a pilot who undocked without reading the rows has
        not silently spent their one free fork.
        """
        if str(self.profile().get("kit", "")):
            return []
        return list(KIT_CONTENTS)

    def grant_kit(self, kit_id: str) -> bool:
        """Deliver *kit_id* free of charge and record the pick on the profile.

        Delivery rides the paid paths: each part goes through the purchase
        gate and then :meth:`_on_item_purchased`, so a part the hull cannot
        take right now refuses with the same toast a purchase would, rather
        than installing around the fitting rules. A module part already
        socketed is skipped: every hull boots with the first power source it
        can carry, so the Solar Kit on a wings-carrying hull delivers the
        dampener and never a second wing array (the decision is recorded on
        ``balance.KIT_CONTENTS``). The Arsenal Kit's rounds are boxed straight
        into the locker under the cannon's own name, because the cannon may
        well be stowed when it arrives (the starter fit fills both hardpoints)
        and the rounds belong to it, not to the hungriest gun.
        """
        profile = self.profile()
        if kit_id not in KIT_CONTENTS or str(profile.get("kit", "")):
            return False
        profile["kit"] = kit_id
        if self.state is not None:
            self.state.kit = kit_id
        aboard = set(self.sockets.installed_ids()) if self.sockets is not None else set()
        for part in KIT_CONTENTS[kit_id]:
            if part in aboard:
                continue
            item = {"id": part, "price": 0.0}
            if self._purchase_gate(item):
                self._on_item_purchased(part, 0.0)
        if kit_id == KIT_ARSENAL and self.rack is not None:
            for _ in range(KIT_ARSENAL_AMMO_BOXES):
                self.rack.add_ammo_box("flak_cannon")
        self.meta_profile().persist()
        return True

    # ----------------------------------------------------------------- frame

    def on_update(self, dt: float):
        if not self.running or self.ended:
            return
        if self._death_killer is not None:
            # Dying. The world keeps drawing, and nothing else on the run reads
            # a key or settles a ledger until the blow has had its frame.
            self._death_wait -= dt
            if self._death_wait <= 0.0:
                self.end_run("death", killed_by=self._death_killer)
            return
        state = self.state
        state.elapsed_s += dt
        self._wiring.poll(dt)
        state.fuel = float(self.power.fuel)
        state.notoriety = int(getattr(self.notoriety, "value", 0))
        self._answer_keys()
        if self._spool_unresolved:
            self._spool_unresolved = False
            self._resolve_spool()
        self._tick_controls_bar()
        self._tick_affordance()
        self._tick_warp_status()
        self._tick_scrap_label(dt)
        self._tick_last_stand(dt)
        if self.power.o2 <= 0.0:
            self.end_run("death", killed_by="suffocation")

    # -------------------------------------------------------- the key channel

    def _answer_keys(self) -> None:
        """Give every bound gameplay key an answer this frame, or a reason.

        The systems that own a key answer it in the world where they can: the
        wings unfold, the drive spools, the guns fire. This pass covers the
        rest, which is every press whose owner had nothing to say and every
        press made against a state that refuses it. It runs before the systems
        do nothing, not instead of them: an answer here is a line on the toast
        channel, never a substitute for the effect.
        """
        hud = self.hud
        if hud is None:
            return
        if self._power_state_seen is None:
            self._power_state_seen = self._power_state()
        shop = self.depot_screen
        chart = self.chart_screen
        if (shop is not None and shop.is_open) or (chart is not None and chart.is_open):
            # A screen that is up owns every key it names, and it answers them
            # itself. Nothing here may speak over a shelf or a route.
            self._power_state_seen = self._power_state()
            return
        if Input.just_pressed(CHART_ACTION) and not self.onboarding_schedule.chart_open():
            # Run one has no chart. Say so, rather than answering the key with
            # a sector jump nobody asked for.
            hud.show_toast(CHART_OFFLINE_TOAST)
        if Input.just_pressed("tractor_scoop"):
            hud.show_toast(SCOOP_PASSIVE_TOAST)
        if Input.just_pressed("solar_wings"):
            hud.show_toast(self._wings_answer())
        if Input.just_pressed("generator"):
            hud.show_toast(self._generator_answer())
        if Input.just_pressed("shield_left") or Input.just_pressed("shield_right"):
            hud.show_toast(SHIELD_MOVED_TOAST)
        if Input.just_pressed("afterburner"):
            flat = self.power is not None and self.power.capacitor <= 0.0
            hud.show_toast(AFTERBURNER_FLAT_TOAST if flat else AFTERBURNER_TOAST)
        if Input.just_pressed("interact") and not self.affordance_prompt() and not self.last_stand_offered:
            # The collapse offer takes the same key, and it answers with a
            # stamp of its own rather than with a refusal.
            hud.show_toast(INTERACT_NOTHING_TOAST)
        if Input.just_pressed("jettison_scrap"):
            hud.show_toast(self._jettison_answer())
        self._power_state_seen = self._power_state()

    def _power_state(self) -> tuple[str, bool | None]:
        """The wings' state and the generator's, or ``None`` for absent parts."""
        ship = self.ship
        wings = ship.find(SolarWings) if ship is not None else None
        generator = ship.find(Generator) if ship is not None else None
        return (str(wings.state) if wings is not None else "", None if generator is None else bool(generator.running))

    def _wings_answer(self) -> str:
        """What a press of the wings key does, in the pilot's own terms.

        Read off the state as it stood *before* the press, latched last frame,
        so the answer does not depend on whether the wings' own node has
        already seen the same press this frame. Run one launches with the wings
        already unfolded, and a pilot who presses X on a deployed pair and sees
        nothing happen files the key as dead, so a press that finds them
        out says exactly that and then says what it did about it.
        """
        state, _running = self._power_state_seen
        if not state:
            return WINGS_NONE_TOAST
        if state == "deployed":
            return WINGS_ALREADY_OUT_TOAST
        if state == "deploying":
            return WINGS_RETRACTING_TOAST
        return WINGS_DEPLOYING_TOAST

    def _generator_answer(self) -> str:
        """What a press of the generator key does, or why it cannot.

        The starter kit has no generator at all, which is the state a new pilot
        first presses the key in: the answer names the gap rather than
        letting Z press into nothing for a whole run.
        """
        _state, running = self._power_state_seen
        if running is None:
            return GENERATOR_NONE_TOAST
        if running:
            return GENERATOR_OFF_TOAST
        if self.power is not None and (self.power.silent_running or self.power.fuel <= 0.0):
            return GENERATOR_REFUSED_TOAST
        return GENERATOR_ON_TOAST

    def _jettison_answer(self) -> str:
        """What a press of the jettison key does with this hold, or why nothing.

        Jettisoned scrap is bait, and bait with nothing hunting is a hold
        thrown away for no reason, so the refusal teaches what the key is for
        rather than reporting a dump that never happened.
        """
        held = float(self.economy.scrap) if self.economy is not None else 0.0
        if held <= 0.0:
            return JETTISON_NOTHING_TOAST
        hunters = self.tree.group(Groups.HUNTER) if self.tree is not None else ()
        return JETTISON_DONE_TOAST if hunters else JETTISON_NO_HUNTER_TOAST

    # ------------------------------------------------------- the verb channel

    def _tick_controls_bar(self) -> None:
        """Hide and show the persistent key list, and remember the choice."""
        if self.hud is None or not Input.just_pressed(CONTROLS_BAR_ACTION):
            return
        showing = self.hud.toggle_controls_bar()
        settings = self.settings()
        settings.controls_bar = showing
        settings.store(self.profile())
        self.hud.show_toast(CONTROLS_BAR_ON_TOAST if showing else CONTROLS_BAR_OFF_TOAST)

    def affordance_prompt(self) -> str:
        """The one verb line the HUD should be showing, empty when there is none.

        Resolved in priority order rather than by distance, because the things
        competing for the key are not comparable: a bay you are sitting in beats
        anything, the sector's own reach comes next, and the breach patch is the
        fallback, since it is the one verb that is available everywhere and so
        would otherwise drown out every prompt that is actually about a place.
        """
        shop = self.depot_screen
        if shop is not None and shop.is_open:
            # The dock screen quotes the shelf, the sell offer and the way out
            # itself; a HUD verb line underneath it would name the same key
            # twice and read as a different offer.
            return ""
        ship = self.ship
        if ship is not None and ship.patching:
            return PATCH_PROMPT_RUNNING
        depot_line = self.depot.affordance() if self.depot is not None else ""
        if depot_line:
            return depot_line
        sector_offer = self.sector.affordance() if self.sector is not None else None
        if sector_offer is not None:
            return sector_offer.prompt
        if ship is not None and ship.open_breaches > 0:
            scrap = float(self.economy.scrap) if self.economy is not None else 0.0
            return PATCH_PROMPT if scrap >= balance.BREACH_PATCH_SCRAP else PATCH_PROMPT_BROKE
        return ""

    def _tick_affordance(self) -> None:
        if self.hud is not None:
            self.hud.set_affordance(self.affordance_prompt())

    def node_label(self, node_id: str) -> str:
        """The chart's own spelling of *node_id*, for anything that names it.

        One spelling, everywhere: the warp chip, the spool ring and the chart's
        own boxes have to agree, or a pilot reading two of them at once is
        looking at two places.
        """
        node = self.state.chart.nodes.get(node_id)
        return node.label if node is not None else str(node_id)

    def warp_status(self) -> tuple[str, bool]:
        """The warp chip's line and whether it is a refusal rather than an offer.

        The spool ring appears only once the drive is already running, so
        without the chip the one question a pilot asks every thirty seconds,
        when can I warp, would have no answer on screen until after they had
        committed to it.
        """
        chart = self.chart_screen
        if chart is None:
            return ("", False)
        # Swept ground is on the offer sheet like anything else; it is priced
        # in what waits there rather than in fuel, and the chip prices fuel.
        offered = chart.destinations()
        chosen = next((d for d in offered if d.node_id == chart.selected_id), None)
        if offered and not any(d.available for d in offered):
            # Nothing on the chart is affordable, which is the one state the
            # pilot must never have to open a screen to discover: quote the
            # cheapest way out and the gap, since that gap is the whole story
            # of the collapse that is about to be offered. The cheapest rather
            # than whatever the arrival armed, because a dry tank is a question
            # about the shortest gap to close, not about the lane the drive is
            # holding.
            chosen = min(offered, key=lambda d: d.quote.total)
        elif chosen is None and not self.onboarding_schedule.chart_open():
            # Run one flies a fixed route, so the drive already knows where it
            # is going and the chip quotes that rather than sending the pilot
            # to a chart they do not have. The route :meth:`gentle_jump` would
            # take, so the chip cannot name a lane the key will not fly.
            takeable = [d for d in offered if d.available]
            chosen = min(takeable, key=lambda d: d.quote.total) if takeable else None
        if chosen is None:
            if not self.onboarding_schedule.chart_open():
                # No chart this run, so nothing on the HUD may send the pilot
                # to one. The drive holds the route; the chip says only that.
                return (WARP_STATUS_SURVEYED, False)
            return (WARP_STATUS_PICK, False)
        # Both lines quote the price itemised: what a jump costs over the base
        # fare is the pilot's decision to make, so it is named wherever it is quoted.
        price = warp_price(chosen.quote)
        if chosen.affordable:
            return (WARP_STATUS_READY.format(name=self.node_label(chosen.node_id), fuel=price), False)
        have = float(self.power.fuel) if self.power is not None else 0.0
        return (WARP_STATUS_NO_FUEL.format(need=price, have=have), True)

    def _tick_warp_status(self) -> None:
        if self.hud is None:
            return
        line, blocked = self.warp_status()
        self.hud.set_warp_status(line, blocked=blocked)

    # ------------------------------------------------------------ last stand

    def stranded(self) -> bool:
        """True when no visible route out of this node is affordable."""
        return bool(self.chart_screen is not None and self.chart_screen.stranded)

    def cheapest_exit_fuel(self) -> float:
        """Fuel the cheapest route out wants, zero when there is no route."""
        quotes = [d.quote.total for d in self.chart_screen.destinations() if not d.consumed]
        return min(quotes) if quotes else 0.0

    def _tick_last_stand(self, dt: float) -> None:
        if self.last_stand or self.chart_screen is None:
            return
        if not self.stranded():
            self._stranded_for = 0.0
            self.last_stand_offered = False
            return
        self._stranded_for += dt
        if not self.last_stand_offered:
            if self._stranded_for < LAST_STAND_OFFER_GRACE_S:
                return
            # Raise the offer and stop there: a held interact must not accept
            # a collapse on the same frame the stamp appears.
            self.last_stand_offered = True
            if self.hud is not None:
                self.hud.flash_stamp("LAST STAND")
            return
        if Input.just_pressed("interact") or self._stranded_for >= LAST_STAND_AUTO_ACCEPT_S:
            self.trigger_last_stand()

    def trigger_last_stand(self) -> None:
        """Take the collapse: free guns, a locked meter, and a priced ending.

        The signature jump is left to the meter, which already consumes
        ``LAST_STAND_TRIGGERED``, so the Shrike is inbound the moment the
        signal lands.
        """
        if self.last_stand:
            return
        self.last_stand = True
        ledger = self.state.ledger
        ledger.last_stand = True
        ledger.cheapest_exit_fuel = self.cheapest_exit_fuel()
        self._scrap_earned_at_trigger = float(self.economy.scrap_earned_this_run)
        if self.rack is not None:
            self.rack.free_fire = True
        if self.hud is not None:
            self.hud.flash_stamp("LAST STAND")
        self.last_stand_triggered.emit()

    # ------------------------------------------------------------- endings

    def extract(self) -> None:
        """Escape through the Deep Gate with the hoard.

        The Gate's toll is already inside the warp quote the chart charged, so
        arriving here is the whole of the transaction.
        """
        self.end_run("extraction")

    def enter_roost(self) -> None:
        """Take the predation fork: hand the run over to the Roost duel.

        The Roost is only ever on the chart with the Lure aboard, and it owns
        its own persistence, so the run scene's job is the handover and the way
        back to the menu once the duel resolves either way.
        """
        if self.waves is not None:
            self.waves.stop()
        self.running = False
        self.ended = True
        scene = roost.RoostScene(self.profile(), name="Roost")
        home = _return_to_menu(self.tree, self.settings(), self.profile())
        scene.roost_victory.connect(home)
        scene.roost_failed.connect(home)
        self.go(scene)

    def gentle_jump(self) -> bool:
        """Take run one's fixed route: the cheapest affordable way onward.

        Reachable only through a chart action: the chart's own confirm button
        past run one, and the drive spool on run one, where the chart is shut.
        No key jumps a sector on its own.
        """
        chart = self.chart_screen
        offered = [d for d in chart.destinations() if d.available]
        if not offered:
            return False
        cheapest = min(offered, key=lambda destination: destination.quote.total)
        return bool(chart.select(cheapest.node_id) and chart.confirm())

    # ------------------------------------------------------------------ warp

    def _on_warp_spool_started(self, emergency: bool) -> None:
        """Note a spool and settle what it is for on the next frame.

        Deliberately deferred: the chart starts its spool from inside
        :meth:`~shrike.chart.StarChart.confirm` and only announces the jump
        afterwards, so a decision taken here and now would call a bought route
        unauthorised and cancel it.
        """
        del emergency
        self._spool_unresolved = True

    def _on_jump_started(self, node_id: str, fuel_cost: float) -> None:
        """The chart has bought a route; the ring in flight belongs to it."""
        del node_id, fuel_cost
        self._jump_committed = True

    def _on_warp_completed(self, emergency: bool) -> None:
        del emergency
        self._jump_committed = False

    def _resolve_spool(self) -> None:
        """Match a running spool to a destination, or refuse it and say why.

        The key either buys the route the chart is pointing at, or it is told
        what it is missing: the ring never runs without a destination behind
        it. A ring that closed on nothing would be a five-second animation for
        no jump.
        """
        ship, chart = self.ship, self.chart_screen
        if ship is None or chart is None or not ship.spooling:
            return
        if self._jump_committed:
            self._label_spool(chart.selected_id)
            return
        if not self.onboarding_schedule.chart_open():
            # Run one flies a fixed route, so the drive picks it: the cheapest
            # way onward, which is the only choice the run offers.
            if self.gentle_jump():
                self._label_spool(chart.selected_id)
            return
        target = chart.selected_id
        if not target:
            self._refuse_spool(WARP_NO_DESTINATION_TOAST, lesson=OnboardingLessons.WARP)
            return
        if chart.select(target) and chart.confirm():
            self._label_spool(target)
            return
        self._refuse_spool(WARP_UNAFFORDABLE_TOAST)

    def _on_warp_spool_cancelled(self) -> None:
        """Release whatever an aborted spool was holding.

        The HUD takes its own ring down off the same signal; what is settled
        here is the route: a jump the chart had already bought would otherwise
        stay pending and refuse every jump after it.
        """
        if self._jump_committed:
            self._jump_committed = False
            if self.chart_screen is not None:
                self.chart_screen.cancel_jump()

    def _label_spool(self, node_id: str) -> None:
        """Write the destination and its fuel price around the spool ring.

        The price is itemised the same way the warp chip itemises it
        (:func:`warp_price`): the ring and the chip are on screen together
        while a channel runs, and a ring quoting a bare 22 beside a chip
        quoting "22 (15 +7 HUNTED)" reads as two separate charges.
        """
        if self.hud is None or not node_id:
            return
        quote = next((d.quote for d in self.chart_screen.destinations() if d.node_id == node_id), None)
        self.hud.set_warp_target(
            self.node_label(node_id),
            float(quote.total) if quote is not None else 0.0,
            price_text=warp_price(quote) if quote is not None else "",
        )

    def _refuse_spool(self, message: str, *, lesson: str = "") -> None:
        """Stand the drive down and put the reason on the toast line.

        *lesson* is the card the refusal earns, and only the no-destination
        refusal earns one. A tank too shallow for the route is a pilot who has
        already picked a destination, and teaching them how to pick one raises
        "WARP NEEDS A DESTINATION" over a chart that has one: an answer to a
        question they did not ask, in place of the one they did. It also spends
        the lesson, which is taught once per profile, on the run where it was
        wrong. The refusal's own chip already names the fix.
        """
        if self.ship is not None:
            self.ship.cancel_warp_spool()
        if self.hud is not None:
            self.hud.end_warp_spool()
            self.hud.show_toast(message)
        if lesson and self.onboarding is not None:
            self.onboarding.teach(lesson)

    def leave_for(self, scene: Node) -> None:
        """Stand the run down and swap to *scene* without settling a ledger.

        The way out for a screen that is not an ending: the waves stop, the
        run stops counting, and nothing is banked, because the run itself is
        expected to come back from its suspend slot.
        """
        if self.waves is not None:
            self.waves.stop()
        self._close_overlays()
        self.running = False
        self.go(scene)

    def _close_overlays(self) -> None:
        """Drop anything holding the tree still, so the next scene can breathe.

        A screen that pauses and a ``change_scene`` are a deadlock waiting to
        happen: the pause outlives the screen that lifted it and the scene that
        replaces it never runs a frame.
        """
        if self.refit_screen is not None:
            self.refit_screen.close()
        if self.depot_screen is not None:
            self.depot_screen.close()
        if self.pause_screen is not None:
            self.pause_screen.close()
        if self.chart_screen is not None:
            self.chart_screen.close()

    def end_run(self, outcome: str, *, killed_by: str = "") -> RunLedger:
        """Settle the run, bank it on the profile, and show the ledger."""
        if self.ended:
            return self.state.ledger
        self.ended = True
        self.running = False
        if self.waves is not None:
            self.waves.stop()
        self._close_overlays()

        ledger = self._collect_ledger(outcome, killed_by)
        self._bank(ledger)
        self.run_ended.emit(outcome, ledger.as_dict())
        if outcome == "extraction":
            self.extraction_completed.emit(ledger.as_dict())
        self.go(LedgerScene(ledger))
        return ledger

    def _collect_ledger(self, outcome: str, killed_by: str) -> RunLedger:
        state = self.state
        ledger = state.ledger
        ledger.outcome = outcome
        ledger.killed_by = killed_by
        ledger.elapsed_s = state.elapsed_s
        ledger.scrap_earned = float(self.economy.scrap_earned_this_run)
        ledger.scrap_carried = float(self.economy.scrap)
        ledger.cores_banked_in_run = float(self.economy.cores_banked_this_run)
        ledger.scrap_after_last_stand = (
            max(0.0, ledger.scrap_earned - self._scrap_earned_at_trigger) if ledger.last_stand else 0.0
        )
        ledger.notoriety = int(getattr(self.notoriety, "value", 0))
        ledger.hull_left = float(self.ship.hull)
        ledger.open_breaches = int(self.ship.open_breaches)
        ledger.fuel_left = float(self.power.fuel)
        ledger.o2_left = float(self.power.o2)
        ledger.signature = float(self.signature.value)
        ledger.loudest_gain = _loudest_gain(self.signature)
        if not ledger.last_stand:
            ledger.cheapest_exit_fuel = self.cheapest_exit_fuel()

        rate = death_conversion_rate(self.profile(), self.state.config.modifiers)
        ledger.conversion = settle_conversion(ledger, death_rate=rate)
        ledger.cores_from_conversion = sum(entry.cores for entry in ledger.conversion)
        for entry in ledger.conversion:
            self.economy.convert(entry.scrap, entry.rate)
        return ledger

    def _bank(self, ledger: RunLedger) -> None:
        """Pay the milestones, update the profile, and write it to disk."""
        profile = self.profile()
        ledger.milestones = earned_milestones(ledger, profile)
        flags = profile.setdefault("milestones", {})
        for name in ledger.milestones:
            flags[name] = True
        ledger.cores_from_milestones = float(sum(save.MILESTONE_CORES[name] for name in ledger.milestones))

        ledger.score = run_score(ledger)
        ledger.best_score, ledger.new_best = record_best(profile, ledger.hull_id, ledger.score)
        ledger.recap = recap_sentence(ledger)

        profile["cores"] = int(profile.get("cores", 0)) + int(round(ledger.cores_total))
        if ledger.outcome == "extraction":
            profile["runs_extracted"] = int(profile.get("runs_extracted", 0)) + 1
            profile["quills"] = int(profile.get("quills", 0)) + ledger.quills
            if ledger.scrap_carried >= balance.BARGE_UNLOCK_SCRAP_CARRIED:
                _unlock_hull(profile, "barge")
        else:
            kept = roost.quills_after_death(ledger.quills, roost_attempt=False)
            profile["quills"] = int(profile.get("quills", 0)) + kept
        if ledger.quills > 0:
            profile["runs_since_last_quill"] = 0
        else:
            profile["runs_since_last_quill"] = int(profile.get("runs_since_last_quill", 0)) + 1
        self.settings().store(profile)
        self.save_system().save_profile(profile)

    # -- suspend -----------------------------------------------------------

    def suspend(self) -> None:
        """Write the run to the one suspend slot, for a resume after a quit.

        The profile goes to disk with it: the run already counted itself as
        started, and a quit that forgot that would let the onboarding schedule
        and the run counter drift from what the player actually played.
        """
        self.save_system().write_suspend(self._capture_suspend())
        self.save_system().save_profile(self.profile())

    def _capture_suspend(self) -> dict:
        """The run as a suspend payload: chart position plus the live state.

        ``RunState.as_suspend`` carries the identity and the route; everything
        a seed cannot reproduce (the four meters, the hold, the hull, the
        harvest progress) is read off the live services here, so a resume
        continues the run instead of refitting it.
        """
        if self.chart_screen is not None:
            self.state.armed_node_id = self.chart_screen.selected_id
        payload = self.state.as_suspend()
        if self.power is not None:
            payload["resources"].update(
                capacitor=float(self.power.capacitor),
                capacitor_max=float(self.power.capacitor_max),
                fuel=float(self.power.fuel),
                o2=float(self.power.o2),
            )
        if self.economy is not None:
            payload["resources"].update(
                scrap=float(self.economy.scrap),
                cores_banked_this_run=float(self.economy.cores_banked_this_run),
            )
            # The run ledger only settles at the end; mid-run the purse holds
            # the true income line.
            payload["ledger"]["scrap_earned"] = float(self.economy.scrap_earned_this_run)
        if self.ship is not None:
            payload["ship"].update(
                hull=float(self.ship.hull),
                hull_max=float(self.ship.hull_max),
                open_breaches=int(self.ship.open_breaches),
                position=[float(self.ship.position.x), float(self.ship.position.z)],
                heading=float(self.ship.heading),
            )
        if self.rack is not None:
            payload["ship"]["weapons"] = [
                {"hardpoint": hardpoint, "id": weapon.spec.id, "rounds": int(getattr(weapon, "rounds", -1))}
                for hardpoint, weapon in enumerate(self.rack.hardpoints)
                if weapon is not None
            ]
            payload["ship"]["ammo_boxes"] = {wid: int(held) for wid, held in self.rack.locker().items()}
            payload["ship"]["stowed_weapons"] = list(self.stowed_weapons)
        payload["ship"]["stowed_modules"] = list(self.stowed_modules)
        if self.sockets is not None:
            payload["ship"]["modules"] = [
                {"socket": index, "id": self.sockets.module_id_at(index)} for index, _node in self.sockets.installed()
            ]
        if self.signature is not None:
            payload["signature"].update(
                value=float(self.signature.value),
                act=int(self.signature.act),
                silent_running=bool(self.signature.silent_running),
            )
        if self.hunter_director is not None:
            payload["hunter"]["arrivals_this_run"] = int(self.hunter_director.arrivals_this_run)
        deck = self.state.deck
        payload["sector"]["event_draws"] = int(getattr(deck, "draws", 0))
        payload["sector"]["seen_events"] = sorted(deck.seen)
        if self.sector is not None:
            payload["sector"]["deposits"] = [
                {
                    "surface": float(deposit.remaining_surface),
                    "core": float(deposit.remaining_core),
                    "tapped": bool(deposit.tapped),
                    "split": bool(deposit.split),
                }
                for deposit in self.sector.deposits
            ]
        return payload

    def _apply_restore(self, payload: dict) -> None:
        """Push a suspend payload's live state back into the rebuilt world.

        A resume is the one arrival that is not a jump: the run was suspended
        somewhere in the sector and goes back exactly there, so the warp-in
        placement the boot's ``enter_sector`` did is overwritten here rather
        than skipped, and the rig is cut to wherever the hull really is.
        """
        resources = payload.get("resources") or {}
        ship_state = payload.get("ship") or {}
        signature = payload.get("signature") or {}

        if self.ship is not None:
            self.ship.hull_max = float(ship_state.get("hull_max", self.ship.hull_max))
            self.ship.hull = float(ship_state.get("hull", self.ship.hull))
            self.ship.open_breaches = int(ship_state.get("open_breaches", 0))
            x, z = (list(ship_state.get("position") or [0.0, 0.0]) + [0.0, 0.0])[:2]
            self.ship.position = Vec3(float(x), PLANE_Y, float(z))
            self.ship.heading = float(ship_state.get("heading", self.ship.heading))
            self._cut_camera_to_ship()
        self._restore_fittings(ship_state)
        if self.power is not None:
            self.power.restore_levels(
                capacitor=float(resources.get("capacitor", self.power.capacitor)),
                fuel=float(resources.get("fuel", self.power.fuel)),
                o2=float(resources.get("o2", self.power.o2)),
            )
            self.power.open_breaches = int(ship_state.get("open_breaches", 0))
        if self.economy is not None:
            scrap = max(0.0, float(resources.get("scrap", 0.0)))
            if scrap > 0.0:
                self.economy.add_scrap(scrap, "resume")
            self.economy.scrap_earned_this_run = float(self.state.ledger.scrap_earned)
            self.economy.cores_banked_this_run = float(resources.get("cores_banked_this_run", 0.0))
            self.state.ledger.cores_banked_in_run = self.economy.cores_banked_this_run
        if self.signature is not None:
            saved = float(signature.get("value", self.signature.value))
            if saved > self.signature.value:
                self.signature.add(saved - self.signature.value, "baseline", raw=True)
        if self.notoriety is not None and self.state.notoriety > 0:
            self.notoriety.add(int(self.state.notoriety), "resume")
        if self.hunter_director is not None:
            self.hunter_director.arrivals_this_run = int((payload.get("hunter") or {}).get("arrivals_this_run", 0))
        self._restore_deposits((payload.get("sector") or {}).get("deposits") or [])
        # Last, and deliberately after the tank: the boot already armed this
        # sector's default, so a lane the pilot chose for themselves is put
        # back over the top of it and a run suspended with nothing armed comes
        # back armed like any other arrival. A saved lane the fan no longer
        # offers is refused by ``select`` and leaves the default standing.
        if self.chart_screen is not None and self.state.armed_node_id:
            self.chart_screen.select(self.state.armed_node_id)

    def _restore_fittings(self, ship_state: dict) -> None:
        """Refit the racks to what the suspended run actually carried.

        The rebuilt run launches with the starter fit, so without this a quit
        costs every weapon, box and module bought since minute one. Empty saved
        lists (including a payload that carries no fittings at all)
        leave the starter fit alone. Runs before the power restore, so a
        refitted power module's sources are in place when the levels land.
        """
        saved_weapons = [r for r in (ship_state.get("weapons") or []) if isinstance(r, dict)]
        if self.rack is not None and saved_weapons:
            for hardpoint in range(len(self.rack.hardpoints)):
                self.rack.unequip(hardpoint)
            for record in saved_weapons:
                hardpoint = int(record.get("hardpoint", -1))
                weapon_id = str(record.get("id", ""))
                if weapon_id not in balance.WEAPONS or not 0 <= hardpoint < len(self.rack.hardpoints):
                    continue
                self.rack.equip(weapon_id, hardpoint)
                weapon = self.rack.hardpoints[hardpoint]
                rounds = int(record.get("rounds", -1))
                if rounds >= 0 and hasattr(weapon, "rounds"):
                    weapon.rounds = min(rounds, int(weapon.magazine_size))
        if self.rack is not None:
            for weapon_id, held in (ship_state.get("ammo_boxes") or {}).items():
                spec = balance.WEAPONS.get(str(weapon_id))
                if spec is None or spec.family != "ballistic":
                    continue
                for _ in range(max(0, int(held))):
                    self.rack.add_ammo_box(str(weapon_id))
        stowed = ship_state.get("stowed_weapons") or []
        if stowed:
            self.stowed_weapons = [str(w) for w in stowed if str(w) in balance.WEAPONS]
        loose = ship_state.get("stowed_modules") or []
        if loose:
            self.stowed_modules = [str(m) for m in loose if str(m) in MODULE_CATALOGUE]
        saved_modules = [r for r in (ship_state.get("modules") or []) if isinstance(r, dict)]
        if self.sockets is not None and saved_modules:
            for index, _node in self.sockets.installed():
                self.sockets.remove(index)
            for record in saved_modules:
                module_id = str(record.get("id", ""))
                socket_index = int(record.get("socket", -1))
                if module_id not in MODULE_CATALOGUE:
                    continue
                try:
                    self.sockets.install(module_id, socket_index)
                except ValueError:
                    # A payload from another hull layout; skipping one module
                    # beats refusing the whole resume.
                    continue

    def _restore_deposits(self, saved: list) -> None:
        """Reapply per-deposit harvest progress onto the regenerated sector.

        The sector regenerates deterministically from its seed, so the saved
        list lines up with the fresh one by order; a mismatched length means
        the payload is from another build of the generator and is skipped
        rather than misapplied.
        """
        if self.sector is None:
            return
        deposits = self.sector.deposits
        if len(saved) != len(deposits):
            return
        for record, deposit in zip(saved, deposits, strict=True):
            if not isinstance(record, dict):
                return
            deposit.remaining_surface = max(0.0, float(record.get("surface", deposit.remaining_surface)))
            deposit.remaining_core = max(0.0, float(record.get("core", deposit.remaining_core)))
            deposit.tapped = bool(record.get("tapped", deposit.tapped))
            if record.get("split", False):
                deposit.split_core()
            # The rock wears its own state, and a restored one has to wear the
            # state it was restored into rather than the one it was born with.
            deposit.refresh_visual()

    def suspend_and_quit(self) -> None:
        self.suspend()
        self.quit()

    # -- ledger sources ----------------------------------------------------

    def _on_player_damaged(self, amount: float, direction: Vec3) -> None:
        """Remember where the last hit that reached the hull came from.

        The bearing is the fallback the ledger names a killer from. The router
        itself records the attacker of every sourced hit before the hull
        resolves it (``DamageRouter.last_ship_attacker``), so the fatal shot
        names itself; what lands here is the history for hits nothing sourced,
        which is why :meth:`_attribute_killer` also has a proximity rule for a
        hull that died to the first thing that touched it.
        """
        del amount
        self._last_hit_bearing = Vec3(direction)
        self._last_hit_at = self.state.elapsed_s if self.state is not None else 0.0

    def _attribute_killer(self) -> str:
        """Name what killed the ship, as specifically as the run can tell.

        A fresh lantern burn first: the burn writes itself down before the
        hull resolves it (:func:`~shrike.hunter.killing_blow`), so a hull the
        beam finished is named for the beam and the dodge it teaches. The
        Shrike's mere presence claims nothing, because the beam is the only
        hull damage it deals: a hull a mite finished during an arrival died
        to the mite. So next the router's own record: enemies pass themselves
        as the source of every hit they deal, and the router writes the
        attacker down before the hull resolves the hit, so a death mid-hit
        reads the true killer. Only an unsourced death falls back to
        geometry: the enemy sitting on the bearing of the last hit that got
        through, nearest along that bearing, then whatever was inside
        :data:`KILLER_NEAR_UNITS`, which is close enough to have been on top
        of it. Failing all of it, a live Shrike in the sector takes the
        blame, and failing even that, the honest :data:`KILLER_UNKNOWN`.
        """
        if self.tree is None or self.ship is None:
            return KILLER_UNKNOWN
        hunter_present = self.tree.first(Groups.HUNTER, Hunter) is not None
        if hunter_present and killing_blow(self.tree) == LANTERN_BLOW_ID:
            return LANTERN_BLOW_ID
        named = self.damage.last_ship_attacker() if self.damage is not None else ""
        if named:
            return named
        elapsed = self.state.elapsed_s if self.state is not None else 0.0
        bearing = self._last_hit_bearing if elapsed - self._last_hit_at <= KILLER_ATTRIBUTION_WINDOW_S else None
        unit = _plane_unit(bearing) if bearing is not None else None

        best, best_distance = "", 0.0
        for enemy in self.tree.group(Groups.ENEMIES):
            offset = Vec3(enemy.position) - Vec3(self.ship.position)
            distance = math.hypot(float(offset.x), float(offset.z))
            if distance <= 1e-6:
                continue
            if unit is not None:
                alignment = (float(offset.x) * unit[0] + float(offset.z) * unit[1]) / distance
                if alignment < KILLER_BEARING_COS:
                    continue
            elif distance > KILLER_NEAR_UNITS:
                continue
            if not best or distance < best_distance:
                best, best_distance = _archetype_of(enemy), distance
        if best:
            return best
        return "hunter" if hunter_present else KILLER_UNKNOWN

    def _on_ship_destroyed(self) -> None:
        """Note the death and let the world run on for :data:`DEATH_SETTLE_S`.

        The killer is attributed here rather than when the timer expires, while
        the blow is still the freshest thing that happened; the wait is only so
        the blow gets a frame of its own before the ledger takes the screen.
        """
        if self._death_killer is not None or self.ended:
            return
        self._death_killer = self._attribute_killer()
        self._death_wait = DEATH_SETTLE_S

    def _on_resource_collected(self, kind: str, amount: float) -> None:
        """Bank a scooped mote for the next "+N SCRAP" label, or stow ammo."""
        if str(kind) == "ammo":
            self._collect_ammo(float(amount))
            return
        if str(kind) != "scrap":
            return
        self._scrap_toast_amount += float(amount)
        self._scrap_toast_wait = SCRAP_TOAST_WINDOW_S

    def _collect_ammo(self, rounds: float) -> None:
        """Turn scooped rounds into stowed boxes for whichever gun is hungriest.

        A wreck's ammo bay releases one box's worth of rounds as a spray of
        motes, so the rounds bank up here and every full box is stowed through
        the same routing a depot purchase takes: the mounted ballistic weapon
        with the fewest spares. A hold with no ballistic weapon keeps the bank;
        the locker fills the moment one is fitted and the next round arrives.
        """
        self._ammo_rounds_bank += rounds
        if self.rack is None:
            return
        while self._ammo_rounds_bank >= balance.AMMO_BOX_ROUNDS - 1e-6:
            weapon_id = self._ammo_eater()
            if weapon_id is None:
                return
            self._ammo_rounds_bank -= balance.AMMO_BOX_ROUNDS
            self.rack.add_ammo_box(weapon_id)
            if self.hud is not None and self.ship is not None:
                self.hud.float_text(AMMO_BOX_FLOAT.format(name=_item_name(weapon_id)), node=self.ship)

    def _tick_scrap_label(self, dt: float) -> None:
        """Float one label for everything scooped inside the merge window."""
        if self._scrap_toast_amount <= 0.0:
            return
        self._scrap_toast_wait -= dt
        if self._scrap_toast_wait > 0.0:
            return
        amount, self._scrap_toast_amount = self._scrap_toast_amount, 0.0
        if self.hud is not None and self.ship is not None:
            # The HUD banks the fractions and floats whole units only, so the
            # labels sum to exactly what the counter took: never "+0", and
            # never "+2" for a rock whose last mote paid 2.475.
            self.hud.credit_float("scrap", amount, "SCRAP", node=self.ship)

    def _on_enemy_killed(self, archetype: str, position, elite: bool) -> None:
        del archetype, position
        ledger = self.state.ledger
        ledger.kills += 1
        if elite:
            ledger.elite_kills += 1

    def _on_vault_hacked(self, scrap: float) -> None:
        del scrap
        self.state.ledger.vaults_cracked += 1

    def _on_cores_banked(self, cores: float, rate: float) -> None:
        """Track in-run banking only.

        The end-of-run settlement converts through the same economy, so once
        the run has ended this must stop mirroring or the ledger would count
        the settlement twice: once as banked, once as converted.
        """
        del cores, rate
        if self.ended or self.economy is None:
            return
        self.state.ledger.cores_banked_in_run = float(self.economy.cores_banked_this_run)

    def _on_arrival_survived(self) -> None:
        """Count a survived arrival. The notoriety it earns is bounty.py's."""
        self.state.ledger.arrivals_survived += 1

    def _on_quill(self, quills_this_run: int) -> None:
        self.state.ledger.quills = int(quills_this_run)

    # -- teardown ----------------------------------------------------------

    def on_exit_tree(self):
        """Retire the run-scoped services; only the meta ones outlive a run."""
        tree = self.tree
        if tree is None:
            return
        for name in self._service_names:
            tree.remove_singleton(name)
        self._service_names = []


def death_headline(ledger: RunLedger) -> str:
    """The one line the ledger opens with: what ended the run, in name.

    Extraction has its own word for it. Everything else names the killer the
    run recorded, falling back to :data:`DEATH_HEADLINES` for the deaths that
    have no archetype behind them, so no run ever ends on "RUN ENDED".
    """
    if ledger.outcome == "extraction":
        return "EXTRACTED"
    killer = ledger.killed_by or KILLER_UNKNOWN
    named = DEATH_HEADLINES.get(killer)
    return named if named else f"DESTROYED BY {killer.replace('_', ' ').upper()}"


class LedgerScene(ShrikeScene):
    """The death (or extraction) ledger: what you banked, and what it cost.

    Never a fail screen, and never a mystery either. It opens on the killer's
    name in the largest type on the screen with the run's one generated
    sentence directly under it, and only then itemises the conversion, the
    milestone bounties, the score against the hull's personal best and the
    assists that were on.
    """

    def __init__(self, ledger: RunLedger, *, focus_entry: str = "", **kwargs):
        kwargs.setdefault("name", "Ledger")
        super().__init__(**kwargs)
        self.ledger = ledger
        self.focus_entry = str(focus_entry)
        self.menu: MenuList | None = None

    def headline(self) -> str:
        """The screen's opening line: :func:`death_headline` for this ledger."""
        return death_headline(self.ledger)

    def lines(self) -> list[str]:
        """The conversion table, in the order the screen prints it.

        The headline and the recap are drawn above this in their own type, so
        neither is repeated here.
        """
        ledger = self.ledger
        out = [f"Scrap earned {ledger.scrap_earned:.0f}, carried {ledger.scrap_carried:.0f}"]
        out += [entry.line() for entry in ledger.conversion]
        if ledger.cores_banked_in_run > 0.0:
            out.append(f"Banked in run: {ledger.cores_banked_in_run:.1f} Cores")
        if ledger.milestones:
            out.append(f"Milestones: {', '.join(ledger.milestones)} (+{ledger.cores_from_milestones:.0f} Cores)")
        out.append(f"Cores this run: {ledger.cores_total:.1f}")
        out.append(f"Sector {ledger.deepest_sector}, {ledger.kills} kills, {ledger.quills} quills")
        best = "NEW BEST" if ledger.new_best else f"best {ledger.best_score}"
        out.append(f"Score {ledger.score} ({best})")
        if ledger.assists:
            out.append(f"Steady Wake: {', '.join(ledger.assists)}")
        return out

    def on_ready(self):
        ledger = self.ledger
        subtitle = f"{ledger.elapsed_s / 60.0:.0f} minutes on the hull {ledger.hull_id}"
        box = self.build_panel(self.headline(), subtitle, title_size=LEDGER_HEADLINE_FONT_PX)
        # The recap is a generated sentence of unbounded length, and a panel
        # grows to fit its widest child: unwrapped, one long recap would stretch
        # the whole ledger out past the buttons it is a caption for.
        for line in wrap_prose(ledger.recap, LEDGER_RECAP_FONT_PX):
            recap = self.add_line(box, line)
            recap.font_size = LEDGER_RECAP_FONT_PX
        for line in self.lines():
            self.add_line(box, line)
        # What the number on the last row is, and where more of it comes from.
        # The ledger is where a player is paid, so it is where the currency has
        # to explain itself; the doctrine screen repeats it where it is spent.
        for line in wrap_prose(cores_source_line(self.profile()), MENU_LINE_FONT_PX):
            self.add_line(box, line, dim=True)
        self.menu = MenuList(box)
        self.menu.add("CONTINUE", lambda: self.go(MainMenuScene()))
        # The Cores this screen just paid out have somewhere to go, and the
        # ledger is where the player is looking when they are paid. Second
        # rather than first: the default row stays the way out.
        self.menu.add(LEDGER_DOCTRINE_ENTRY, self.open_doctrine)
        self.menu.add("RUN AGAIN", lambda: self.go(RunSetupScene()))
        self.add_line(box, MENU_CONTROLS_LINE, dim=True)
        self.menu.focus(self.focus_entry)
        self.settle_panel()

    def open_doctrine(self) -> None:
        """Open the tree, with BACK returning to this ledger rather than past it."""
        ledger = self.ledger
        self.go(DoctrineScene(back_factory=lambda: LedgerScene(ledger, focus_entry=LEDGER_DOCTRINE_ENTRY)))

    def on_update(self, dt: float):
        if self.menu is not None:
            self.menu.poll(dt)


class SettingsScene(ShrikeScene):
    """Accessibility, remapping and the Steady Wake assist panel.

    Everything here is stored on the meta profile the moment it changes, and
    every assist is stamped on the ledger of any run that uses it. None of them
    locks content.
    """

    def __init__(self, *, back_entry: str = MENU_ENTRY_SETTINGS, **kwargs):
        kwargs.setdefault("name", "Settings")
        super().__init__(**kwargs)
        self.menu: MenuList | None = None
        self.rebinding: str = ""
        #: Which front-door row the player came in through, so backing out puts
        #: the cursor back where they left it.
        self.back_entry = str(back_entry)
        self._sliders: dict[str, Slider] = {}
        self._slider_labels: dict[str, Label] = {}
        self._checks: dict[str, CheckBox] = {}
        self._damage_row = -1
        self._frame_cap_row = -1
        self._back: PressLatch | None = None

    # -- edits -------------------------------------------------------------

    def _live_audio(self):
        """The live ``AudioDirector``, when this screen is up over a run."""
        tree = self.tree
        if tree is None:
            return None
        return tree.singletons.get(Services.AUDIO)

    def set_slider(self, name: str, value: float) -> None:
        """Move one of the feel sliders, the UI scale, or one of the mix rows."""
        settings = self.settings()
        if name == "ui_scale":
            settings.ui_scale = min(UI_SCALE_MAX, max(UI_SCALE_MIN, float(value)))
        else:
            setattr(settings, name, _clamp01(value))
        if name.startswith("volume_"):
            # A mix slider has to be audible while it is being dragged, or the
            # only way to set it is to leave the screen and come back.
            settings.apply_volumes(self._live_audio())
        self.persist()

    def set_photosensitive(self, on: bool) -> None:
        self.settings().photosensitive = bool(on)
        self.persist()

    def set_controls_bar(self, on: bool) -> None:
        """Show or hide the persistent controls bar along the bottom of the HUD."""
        self.settings().controls_bar = bool(on)
        self.persist()

    def set_hold(self, action: str, hold: bool) -> None:
        """Hold-versus-toggle for fire, shield and silent running."""
        if action not in HOLD_OR_TOGGLE_ACTIONS:
            raise ValueError(f"{action!r} is not a hold-or-toggle action")
        self.settings().hold_actions[action] = bool(hold)
        self.persist()

    def cycle_frame_cap(self) -> int:
        """Step the frame cap through :data:`FRAME_CAP_OPTIONS`, live, and store it.

        Applied as well as stored: ``App.target_fps`` is writable mid-run, so the
        new cap takes effect on the next frame. It is still written to disk
        because boot reads it (``main.resolve_frame_cap``, or the front door in
        the browser), which is what makes
        the choice survive a restart rather than what makes it take effect.
        """
        options = FRAME_CAP_OPTIONS
        settings = self.settings()
        current = _frame_cap_of(settings.frame_cap)
        index = options.index(current) if current in options else 0
        settings.frame_cap = options[(index + 1) % len(options)]
        self.persist()
        _apply_frame_cap(settings.frame_cap)
        return settings.frame_cap

    def set_vsync(self, on: bool) -> None:
        """Flip vsync, live, the same way the frame cap goes."""
        settings = self.settings()
        settings.vsync = bool(on)
        self.persist()
        _apply_vsync(settings.vsync)

    def cycle_damage_taken(self) -> float:
        """Step the Steady Wake damage slider through its three settings."""
        steps = balance.ASSIST_DAMAGE_TAKEN_STEPS
        settings = self.settings()
        index = steps.index(_nearest_step(settings.damage_taken))
        settings.damage_taken = steps[(index + 1) % len(steps)]
        self.persist()
        return settings.damage_taken

    def toggle_assist(self, name: str) -> bool:
        """Flip one of the Steady Wake toggles and hand back its new state."""
        if name not in ("slow_signature", "slow_lantern", "spool_immunity"):
            raise ValueError(f"{name!r} is not a Steady Wake toggle")
        settings = self.settings()
        value = not getattr(settings, name)
        setattr(settings, name, value)
        self.persist()
        return value

    def rebind(self, action: str, bindings) -> None:
        """Rebind *action* to *bindings*, keeping its pad axes.

        Raises for an unknown action or a binding that cannot be stored, so a
        control can never end up silently unbound.
        """
        if action not in REMAPPABLE_ACTIONS:
            raise ValueError(f"{action!r} is not remappable")
        tokens = []
        for binding in bindings:
            token = encode_binding(binding)
            if token is None:
                raise ValueError(f"{binding!r} cannot be bound from the options screen")
            tokens.append(token)
        self.settings().bindings[action] = tokens
        self.persist()

    def reset_bindings(self) -> None:
        self.settings().bindings.clear()
        self.persist()

    def persist(self) -> None:
        """Store the settings on the profile and write it out."""
        self.settings().store(self.profile())
        self.save_system().save_profile(self.profile())

    # -- screen ------------------------------------------------------------

    def on_ready(self):
        self._back = PressLatch(PAUSE_ACTION)
        settings = self.settings()
        box = self.build_panel("SETTINGS", "nothing here locks content")

        for name, label in (("shake", "Screen shake"), ("flash", "Flash"), ("hit_stop", "Hit stop")):
            self._sliders[name] = self._slider(box, label, getattr(settings, name), 0.0, 1.0, name)
        self._sliders["ui_scale"] = self._slider(
            box, "UI scale", settings.ui_scale, UI_SCALE_MIN, UI_SCALE_MAX, "ui_scale"
        )
        for name, label in VOLUME_SETTINGS:
            self._sliders[name] = self._slider(box, label, getattr(settings, name), 0.0, 1.0, name)
        self._checks["photosensitive"] = box.add_child(
            CheckBox("Photosensitivity mode", checked=settings.photosensitive, on_toggle=self.set_photosensitive)
        )
        self._checks["controls_bar"] = box.add_child(
            CheckBox("Controls bar (H)", checked=settings.controls_bar, on_toggle=self.set_controls_bar)
        )
        for action in HOLD_OR_TOGGLE_ACTIONS:
            self._checks[action] = box.add_child(
                CheckBox(
                    f"Hold to {action.replace('_', ' ')}",
                    checked=settings.hold_to_use(action),
                    on_toggle=_bind(self.set_hold, action),
                )
            )

        self.add_line(box, "STEADY WAKE", dim=True)
        for name, label in (
            ("slow_signature", "Signature fills slower"),
            ("slow_lantern", "Lantern sweeps slower"),
            ("spool_immunity", "Spool cannot be interrupted"),
        ):
            self._checks[name] = box.add_child(
                CheckBox(label, checked=getattr(settings, name), on_toggle=_bind(self._set_assist, name))
            )

        self._checks["vsync"] = box.add_child(
            CheckBox("Vertical sync", checked=settings.vsync, on_toggle=self.set_vsync)
        )

        self.menu = MenuList(box)
        self.menu.add(self.damage_row_label(), self._cycle_damage_row)
        self._damage_row = 0
        self.menu.add(self.frame_cap_row_label(), self._cycle_frame_cap_row)
        self._frame_cap_row = 1
        self.menu.add("RESET KEY BINDINGS", self.reset_bindings)
        self.menu.add("BACK", self.back)
        self.add_line(box, MENU_CONTROLS_LINE_BACK, dim=True)
        self.settle_panel()

    def back(self) -> None:
        """Return to the front door with the cursor on the row we came in by."""
        self.go(MainMenuScene(focus_entry=self.back_entry))

    def on_update(self, dt: float):
        if self._back is not None and self._back.poll(dt)[0]:
            self.back()
            return
        if self.menu is not None:
            self.menu.poll(dt)

    # -- live labels -------------------------------------------------------

    def damage_row_label(self) -> str:
        """The damage row, carrying the setting it is currently on.

        "DAMAGE TAKEN: CYCLE" would name the verb and hide the value, so the only
        way to read an assist that changes how much damage the hull takes would
        be to press it three times and watch what happened.
        """
        return SETTINGS_DAMAGE_ROW.format(percent=self.settings().damage_taken * 100.0)

    def _cycle_damage_row(self) -> float:
        """Step the damage assist and rewrite the row with its new value."""
        value = self.cycle_damage_taken()
        if self.menu is not None and self._damage_row >= 0:
            self.menu.relabel(self._damage_row, self.damage_row_label())
        return value

    def frame_cap_row_label(self) -> str:
        """The frame cap row, carrying the cap it is currently set to."""
        cap = _frame_cap_of(self.settings().frame_cap)
        return SETTINGS_FRAME_CAP_ROW.format(value=SETTINGS_FRAME_CAP_FOLLOW if cap == 0 else f"{cap} FPS")

    def _cycle_frame_cap_row(self) -> int:
        """Step the frame cap and rewrite the row with its new value."""
        value = self.cycle_frame_cap()
        if self.menu is not None and self._frame_cap_row >= 0:
            self.menu.relabel(self._frame_cap_row, self.frame_cap_row_label())
        return value

    def slider_label(self, name: str, label: str, value: float) -> str:
        """One slider's caption, with its value written out beside its name."""
        if name == "ui_scale":
            return SETTINGS_SCALE_ROW.format(name=label, value=value)
        return SETTINGS_SLIDER_ROW.format(name=label, percent=value * 100.0)

    def _slider(self, box: VBoxContainer, label: str, value: float, low: float, high: float, name: str) -> Slider:
        caption = self.add_line(box, self.slider_label(name, label, value), dim=True)
        self._slider_labels[name] = caption
        slider = box.add_child(Slider(low, high, value, size_y=MENU_ROW_HEIGHT_PX))
        slider.size_x = MENU_WIDTH_PX
        slider.step = 0.05
        slider.value_changed.connect(_bind(self._on_slider_moved, name, label, slider))
        return slider

    def _on_slider_moved(self, name: str, label: str, slider: Slider, *_) -> None:
        """Store the new value and write it into the slider's own caption."""
        self.set_slider(name, slider.value)
        caption = self._slider_labels.get(name)
        if caption is not None:
            _set_text(caption, self.slider_label(name, label, slider.value))

    def _set_assist(self, name: str, on: bool) -> None:
        setattr(self.settings(), name, bool(on))
        self.persist()


# ============================================================================
# Entry point
# ============================================================================


def create_entry_scene() -> Node:
    """The scene ``main.py`` boots.

    The game opens on :class:`MainMenuScene`, its front door. Setting
    :data:`BOOT_STRAIGHT_INTO_RUN` boots a live run instead, which is a debug
    convenience rather than a shipping mode. Either way the menu, the setup
    screen, the ledger and the settings are one ``change_scene`` apart.
    """
    if BOOT_STRAIGHT_INTO_RUN:
        return RunScene(RunConfig(seed=random.randrange(1, 2**31)).as_dict())
    return MainMenuScene()


# ============================================================================
# Small helpers
# ============================================================================


def _return_to_menu(tree, settings: Settings, profile: dict):
    """A handler that puts the main menu back up, bound to the tree.

    Bound to the tree rather than to a scene on purpose: the screen that asks
    for this is the one being swapped out, and it is gone by the time the
    handler runs.
    """

    def handler(*_):
        scene = MainMenuScene(settings=settings, profile=profile)
        scene.input_context = settings.input_actions()
        tree.change_scene(scene)

    return handler


def _item_name(item_id: str) -> str:
    """A catalogue id as the toast line spells it: RAIL LANCE, not rail_lance."""
    return item_name(item_id)


def _bind(function, *args):
    """A zero-argument (or engine-argument) callable that calls *function*."""

    def call(*extra):
        return function(*args, *extra)

    return call


def _make_audio() -> Node | None:
    """The audio director, or None when the audio backend cannot bake a bank.

    A headless box without an audio device must still be able to run the game,
    and silence is a better failure than a run that will not boot.
    """
    try:
        from .audio import AudioDirector
    except Exception:  # pragma: no cover - import-time backend failure
        return None
    try:
        return AudioDirector(name="AudioDirector")
    except Exception:  # pragma: no cover - device or bake failure
        return None


def _plane_unit(vector: Vec3) -> tuple[float, float] | None:
    """*vector* on the flight plane, normalised, or None when it has no length."""
    length = math.hypot(float(vector.x), float(vector.z))
    if length <= 1e-6:
        return None
    return (float(vector.x) / length, float(vector.z) / length)


def _archetype_of(enemy: Node) -> str:
    """The archetype id of *enemy*, spelled the way ``combat.py`` reports kills."""
    spec = getattr(enemy, "spec", None)
    archetype = getattr(spec, "id", None)
    return str(archetype) if archetype else type(enemy).__name__.lower()


def _loudest_gain(meter: SignatureMeter) -> str:
    """The signature reason that charged the most this sector, for the recap."""
    gains = {reason: value for reason, value in meter.gains.items() if reason != "baseline"}
    if not gains:
        return ""
    return max(gains.items(), key=lambda item: item[1])[0].replace("_", " ")


def _unlock_hull(profile: dict, hull_id: str) -> None:
    hulls = profile.setdefault("hulls", {"unlocked": [save.STARTER_HULL], "selected": save.STARTER_HULL})
    unlocked = hulls.setdefault("unlocked", [save.STARTER_HULL])
    if hull_id not in unlocked:
        unlocked.append(hull_id)


def hull_socket_count(hull_id: str) -> int:
    """How many sockets *hull_id* carries, from the module layout tables.

    The setup screen quotes this rather than ``balance.HULL_SOCKETS`` so the
    number on the launch screen is the one the rack will really build.
    """
    return len(sockets_for_hull(hull_id))