shrike/hud.py

Part of SHRIKE.

"""SHRIKE's heads-up display: foveal arcs, a warming border and diegetic rings.

The HUD is deliberately not a corner-panel dashboard. Everything the pilot
reads while dodging sits inside the foveal zone around the ship:

* **Hull, capacitor, O2 and fuel** are thin arcs ringing the ship, each with a
  dim track behind a bright fill, so a glance costs no eye movement. Each is
  captioned at a fixed compass point *outside every ring the HUD draws*, and
  hull and capacitor carry their number there because they have no cell in the
  strip below.
* **Every resource the run prices is a number under the ring.** The strip
  (:meth:`Hud.resource_lines`) carries scrap, fuel and air, and it is in the
  run-one floor because run one quotes five scrap for a patch and fifteen fuel
  for a jump. The rule it follows: *anything the run can
  charge or credit has a visible number from the moment it is first touched.*
  Under it sit the power-state pips (:meth:`Hud.state_pips`), which are what
  the wings key and the generator key have to show for themselves.
* **The shield pad is drawn on the bearing it covers.** Q and E move a defence
  that would otherwise exist only in the collision maths, and a control with no
  output reads as an unbound key.
* **The signature meter is a gauge and a border.** An arc over the ship's nose
  carries the reading and its number; the screen border warms from cold blue to
  red behind it, off the same fraction. A border alone does not work: a pilot
  can watch the frame redden for seventy-five seconds without learning that it
  is a meter, and die to the arrival it was counting down to. A tint is a mood;
  a gauge is a reading, and this meter needs both. When it locks, the HUD says so in the imperative
  and then draws the countdown and a marker on the approach bearing, because a
  killer nobody has ever seen is not a boss, it is a bug.
* **The warp spool is a ring closing on the ship.** It shrinks toward the hull
  over ``balance.WARP_SPOOL_S`` and visibly stutters every time a hit adds
  seconds to the channel. It never simply disappears: a jump whites the screen
  out, and an abort or a failure holds the ring in red for
  :data:`WARP_OUTCOME_FLASH_S` with the ending written under it, so "the circle
  went big and then small and nothing happened" is not a state the HUD has.
* **The sector's edge and its compass.** A standing line says the ship has
  flown out of the sector (:meth:`Hud.set_boundary_notice`), and while nothing
  worth flying to is on screen, edge markers give the bearing and range of the
  nearest vein, hulk and depot (:meth:`Hud.set_compass_targets`). A waypoint
  label is the one thing on the screen placed by where a rock is rather than by
  a layout, so it steps along its edge to a row clear of the whole standing HUD
  (:meth:`Hud._label_zones`) and stands its marker down rather than share a row
  with one of the transient plates at the foot of the screen.
* **Damage direction is edge desaturation**, never a red overlay: the edge the
  hit came from drains of colour for a moment. :meth:`Hud.edge_desaturation`
  exposes the same per-edge intensities as a hook, so a post-process pass can
  drive the real desaturation while the HUD draws the fallback band.
* **Dying is a state you can see coming.** Below :data:`LOW_HULL_FRACTION` the
  whole border pulses and the klaxon caption keeps coming back; under
  ``balance.O2_LOW_WARNING_SECONDS`` of air the remaining seconds are counted
  down beside the ship. Both are warnings, not readouts, so onboarding never
  subtracts them: a pilot who cannot see the hull can still see it is critical.
* **The warp ring says what it is spooling to.** ``WARP SPOOL`` names the
  destination and its fuel price while the channel runs, an interruption
  flashes the seconds it just cost, and the abort key is written under it.
* **Floating text belongs to the world, not to the corner.** A pickup's value
  and a first-sighting enemy tag are drawn where the thing is
  (:meth:`Hud.float_text`), and a one-line :meth:`Hud.show_toast` carries the
  short answers a key press deserves ("select a destination: M"). A label that
  names a counter the HUD keeps flies across to it as it fades, so the number
  in the corner grows because of something the pilot watched happen. Anything
  paid in fractions goes through :meth:`Hud.credit_float`, which banks per
  source and writes one label per whole unit, so a beam paying a tenth of a
  unit a frame never captions itself ``+0 SCRAP`` beside a climbing counter.
* **Everything under the hull has a reserved slot.** The warp chip, the
  survival warnings, the run's current instruction and the boundary line each
  own a band (``BAND_*_PX``) and never leave it, and the waypoint labels stay
  out of the controls strip's band. One shared offset would put four sentences
  on one row of pixels, legible as none of them. The transient
  answer line is the one row anchored to the screen rather than to the hull,
  so it steps around whichever standing lines are up
  (:meth:`Hud.message_row`) instead of being written through them.
* **Every reading around the hull sits on its own plate.** The gauge captions
  and the signature reading are drawn over the playfield, and the playfield is
  allowed to be a lantern cone bloomed several stops over white. The burn frame
  is the one frame where HULL and SIGNATURE decide whether the pilot
  understands their own death, and without a plate it is the one frame where
  neither can be read. Nothing the HUD draws over the playfield is allowed to cover them
  either: a rising float takes a lane beside a reading rather than through it
  (:meth:`Hud._float_lane`), and the standing lines stand down when the caption
  track reaches their band (:meth:`Hud.caption_block`).
* **The affordance line names the verb in reach.** Whenever something the ship
  can act on is close enough to act on, one short line sits above the gauge
  ring and says which key does what ("F: DOCK", "HOLD RMB: CRACK THE CORE").
  It is pushed every frame by whoever resolved the reach
  (:meth:`Hud.set_affordance`) and it is never subtracted: a verb nobody names
  is a verb nobody performs.
* **The controls strip is always there.** Two rows on a dark plate along the
  bottom of the screen list the whole keyboard in the order a pilot needs it.
  It is on by default for every run, toggled with the controls key or from the
  settings screen, and it is independent of the onboarding lessons, which stop
  showing after run three and never come back.
* **The warp chip answers "when can I leave?"** It sits where the spool ring
  will close and reads one of three states: no destination picked, ready at a
  named fuel price, or short of fuel by a stated amount.
* **Every audio cue also lands here as a caption on the caption plate**
  (:data:`CUE_SUBTITLES`, written by :func:`caption_for`), because a mix that
  carries mechanical information must never be hearing-gated. The caption is a
  diegetic phrase in small caps on a dark strip (KLAXON, HULL BREACHED,
  WHISTLE) and it carries no punctuation at all: punctuation around a word in
  the middle of the screen reads as placeholder text that shipped, so the plate
  does the work glyphs cannot.
* **Arriving somewhere is an event with a name.** A jump lands the hull in a
  field of rocks that looks like the last field of rocks, so
  :meth:`Hud.show_arrival_card` names the biome and says one line about it, and
  :meth:`Hud.set_sector_name` leaves the name standing in the corner for as
  long as the sector lasts.
* **The control card is onboarding's own channel**, and it is not the caption
  queue. One centred panel names the keys of the lesson in hand and stays up
  until the player does the thing, so a control the player never found cannot
  scroll away under a combat caption. :meth:`Hud.show_control_card` puts one up
  and :meth:`Hud.clear_control_card` takes it down; the schedule that decides
  which card is current lives in ``shrike.onboarding``. The card is drawn where
  :meth:`Hud.control_card_layout` says, which is never over the ship's own
  status band (:meth:`Hud.status_band_top`): a fixed top-band panel would sit
  on ``SIGNATURE LOCKED`` and on every breach message whenever the aim lead
  carries the hull up the screen. It yields in order (up, then its
  hint, then its size, then off), and the ship's readings never move for it.

Every pixel constant here is authored against a 720-pixel-tall window and
scaled at draw time by :attr:`Hud.effective_scale`, which is the window's own
height scale (:func:`screen_scale_for`) times the player's UI-scale slider. A
window twice as tall therefore draws a HUD twice as large rather than a HUD
half as readable.

Onboarding subtracts elements rather than adding them: the HUD draws whatever
is in :attr:`Hud.visible_elements`, and ``flow.Onboarding`` narrows that set for
the first three runs. :data:`ALL_HUD_ELEMENTS` is the vocabulary and
:data:`MINIMAL_HUD_ELEMENTS` the run-one floor.

Sources are discovered, not injected. The HUD scans the run's singletons and
the ship's subtree for the signals in :data:`_WANTED_SIGNALS` and connects to
whatever exists, re-scanning while anything is still missing. A HUD in a scene
with no power system simply draws empty arcs instead of raising.
"""

from __future__ import annotations

import math
import weakref
from typing import NamedTuple

import numpy as np

from simvx.core import Anchor, Control, Input, Node, PointerFilter, Signal, Vec3

from . import balance
from .runtime import CameraRig, Groups, Services, SignalNames, heading_to_direction

# ============================================================================
# Local presentation constants
#
# balance.py owns tuning that changes how the game plays; these govern how the
# HUD looks, which is this module's own business. They are all in pixels at a
# UI scale of 1.0 or in seconds.
# ============================================================================

#: Radius of the innermost gauge arc, measured from the ship on screen.
ARC_RADIUS_PX = 58.0
#: Radial gap between the gauge ring and the interact fill inside it.
INTERACT_FILL_RADIUS_PX = 34.0
ARC_THICKNESS_PX = 5.0
#: Degrees of arc per drawn segment; small enough that the chord reads as curved.
ARC_SEGMENT_DEGREES = 6.0

#: Captions outside the rings, on the compass point of the arc they name. Four
#: unlabelled arcs are four colours a pilot has to have been told about; four
#: labelled ones are a gauge cluster.
#:
#: They are drawn *clear of every ring*, not on the ring's own radius. Centring
#: a label on the compass point would put the side captions half over the arcs
#: and half over the hull, with "O2" written across the ship and "FUEL" with
#: its first two letters behind the fuel arc. The side captions hang outward
#: from the rings and the top and bottom ones sit above and below them, so
#: nothing the HUD draws around the hull is written on anything else the HUD
#: draws around the hull.
ARC_LABEL_GAP_PX = 10.0
#: The gauge captions name the four numbers that keep the pilot alive, so they
#: are drawn at full alpha and at a size a glance can resolve: dimmer or
#: smaller, they read as four illegible smudges against a bright nebula.
ARC_LABEL_FONT_SCALE = 0.9
#: Wide enough for the longest caption and its numeral ("HULL 100").
ARC_LABEL_BOX_PX = 104.0
ARC_LABEL_LINE_PX = 16.0
#: The plate every reading around the hull is written on.
#:
#: These numbers are drawn over the playfield, and the playfield is allowed to
#: be a bloomed white lantern shaft: on the burn frame the hull arc, the HULL
#: number and the SIGNATURE reading all sit inside the cone, and unbacked none
#: of them is readable on the one frame in the game where reading them matters
#: most. The plate is what puts the ship's own
#: numbers in front of whatever the sector is doing, and it costs one rect per
#: caption.
READING_PLATE_PADDING_X_PX = 5.0
READING_PLATE_PADDING_Y_PX = 2.0
#: Clearance between a ring caption and whatever is written beyond it.
ARC_LABEL_CLEARANCE_PX = 4.0
#: How hull and capacitor write their numbers. O2 and fuel carry theirs in the
#: resource strip, so their captions stay bare: two copies of one number is one
#: copy too many, and these two have no other copy.
ARC_LABEL_WITH_VALUE = "{caption} {value:.0f}"

#: The shield arc, drawn just outside the gauge ring on the bearing it covers.
#: Q and E move the pad, and a pad that answered the key only in the collision
#: maths would be a control with no output.
SHIELD_ARC_GAP_PX = 9.0
SHIELD_ARC_THICKNESS_PX = 6.0

#: The power-state pips: solar wings, generator and afterburner, as three small
#: lamps on the second row of the ship-state block. Each names the key that
#: moves it, so pressing X or Z always changes something on screen.
STATE_PIP_LINE_PX = 17.0
STATE_PIP_CELL_PX = 116.0
STATE_PIP_FONT_SCALE = 0.85
#: How each pip reads, ``(on, off)``. The afterburner has no off text: an
#: engine that is not burning is the resting state and does not need a lamp.
PIP_WINGS = ("X WINGS OUT", "X WINGS IN")
PIP_GENERATOR = ("Z GEN RUNNING", "Z GEN OFF")
PIP_AFTERBURNER = ("SHIFT BURNING", "SHIFT BURN")

#: The warp ring starts this far out and closes onto the gauge ring.
WARP_RING_START_RADIUS_PX = 170.0
WARP_STUTTER_S = 0.45
WARP_STUTTER_AMPLITUDE_PX = 9.0
WARP_STUTTER_HZ = 22.0

#: The label under the closing ring, and the gap between it and the ring.
WARP_LABEL = "WARP SPOOL"
#: What the abort line says. The action, not the key: a remapped drive still
#: aborts on whatever the pilot bound it to, and this is the name they saw.
WARP_ABORT_HINT = "tap R again to abort"
#: The price the ring quotes beside the destination. The caller may hand down
#: its own wording (the warp chip itemises a surcharge, and a ring quoting a
#: bare total beside a chip that itemises reads as two different prices); when
#: it does not, the ring spells the number it was given.
WARP_LABEL_PRICE = " for {price} fuel"
WARP_LABEL_GAP_PX = 16.0
WARP_LABEL_LINE_PX = 20.0
WARP_LABEL_FONT_SCALE = 1.1
#: How long the interruption line stays up after a hit lengthens the channel.
WARP_INTERRUPT_FLASH_S = 1.4
WARP_INTERRUPT_FONT_SCALE = 1.3
#: What an interruption is spelled out as. "INTERRUPTED" on its own would tell
#: the pilot that something happened and nothing about what or why; this names
#: the cost in seconds and the cause in the same breath.
WARP_INTERRUPT_PREFIX = "SPOOL INTERRUPTED"
WARP_INTERRUPT_CAUSE = "taking fire"

#: The warp chip: one line in the context band under the ship, up whenever no
#: spool is running, answering "can I leave, and what does it cost?".
WARP_STATUS_FONT_SCALE = 1.0
#: How far the chip's plate is padded past its own type, sideways only. A
#: refused spool holds its red ring at the outer radius, and the outer radius
#: crosses this band, and without a plate the ring runs straight through
#: "need 15, have 5", which is the shortfall a stranded pilot has most need of.
#: The plate is laid down after the ring and before the type, so the ring
#: passes behind the chip rather than through it. It takes no vertical padding
#: because the band's row already carries the type's leading, and a plate
#: taller than its band walks into the resource strip's plate above it.
WARP_STATUS_PLATE_PADDING_X_PX = 10.0

#: Border thickness at signature zero and at :data:`balance.SIGNATURE_MAX`.
SIGNATURE_BORDER_MIN_PX = 2.0
SIGNATURE_BORDER_MAX_PX = 18.0

#: The signature gauge proper: an outer arc over the ship's nose, with the
#: meter's own number written above it. A border alone is not enough, because
#: a screen tint is a mood and not a reading: a pilot can watch the frame turn
#: red for seventy-five seconds without ever learning that the red is a meter,
#: that it is filling, or how full it is. The border stays, because a
#: peripheral warm is the right thing to feel; this is the thing to read.
SIGNATURE_ARC_GAP_PX = 20.0
SIGNATURE_ARC_SPAN_DEGREES = 156.0
SIGNATURE_ARC_THICKNESS_PX = 4.0

#: Where the rings around the hull stop. The shield pad follows the aim and can
#: be at any bearing, so it sets the outer edge everywhere; the signature gauge
#: only ever covers the nose, so it sets a taller one above the ship alone. The
#: gauge captions are placed off these two, which is what keeps them off the
#: arcs however wide the rings get.
RING_OUTER_PX = ARC_RADIUS_PX + SHIELD_ARC_GAP_PX + SHIELD_ARC_THICKNESS_PX * 0.5
SIGNATURE_RING_OUTER_PX = ARC_RADIUS_PX + SIGNATURE_ARC_GAP_PX + SIGNATURE_ARC_THICKNESS_PX * 0.5
#: The inner edge of a ring caption: how far from the hull the type begins.
ARC_LABEL_RADIUS_PX = RING_OUTER_PX + ARC_LABEL_GAP_PX
ARC_LABEL_TOP_RADIUS_PX = SIGNATURE_RING_OUTER_PX + ARC_LABEL_GAP_PX

#: The signature reading is written above the hull caption rather than at a
#: fixed distance from its own arc, so the two never share a row.
SIGNATURE_LABEL_GAP_PX = (
    ARC_LABEL_TOP_RADIUS_PX + ARC_LABEL_LINE_PX + ARC_LABEL_CLEARANCE_PX - ARC_RADIUS_PX - SIGNATURE_ARC_GAP_PX
)
SIGNATURE_LABEL_LINE_PX = 18.0
SIGNATURE_LABEL_FONT_SCALE = 0.95
SIGNATURE_LABEL = "SIGNATURE {value:.0f}/{maximum:.0f}"
#: How far above the ship the whole signature gauge reaches, label included.
#: Whatever sits above the ring measures from here rather than from the ring,
#: or it lands on the reading.
SIGNATURE_GAUGE_TOP_PX = ARC_RADIUS_PX + SIGNATURE_ARC_GAP_PX + SIGNATURE_LABEL_GAP_PX + SIGNATURE_LABEL_LINE_PX

#: What the lock says. It is an instruction, not a status: by the time it is up
#: the only question the pilot has is what to do about it. The stamp is the
#: headline and the standing line is the answer, because a stamp that fades has
#: told a first-time pilot nothing.
#:
#: The answer is the warp drive and only the warp drive. Silent running is what
#: keeps the meter off the ceiling, and it does nothing once the ceiling has
#: been hit: ``SignatureMeter.locked`` latches for the whole sector and the
#: ladder is already running. Offering it here would be an instruction that
#: does not work, which is worse than no instruction at all.
SIGNATURE_LOCKED_STAMP = "SIGNATURE LOCKED"
SIGNATURE_LOCKED_INSTRUCTION = "SIGNATURE LOCKED: the Shrike is inbound. Warp out (R) before it lands"

#: The inbound Shrike's countdown and the marker on its approach vector. The
#: telegraph ladder is generous with seconds, and a sound alone would spend all
#: of them; this is the same warning written down.
HUNTER_COUNTDOWN = "SHRIKE INBOUND: {seconds:.0f} s"
HUNTER_MARKER_RADIUS_PX = 11.0
HUNTER_MARKER_EDGE_MARGIN_PX = 54.0
HUNTER_MARKER_FONT_SCALE = 1.0
#: How far along the approach bearing the marker is planted. Past the edge of
#: the visible field on purpose, so the marker rides the screen edge and reads
#: as a bearing rather than drifting over the play area as a thing that is
#: already there.
HUNTER_MARKER_RANGE_UNITS = 60.0

#: Seconds the lost chunk holds at full length before it starts draining, and
#: seconds it then takes to drain onto the new level. Both are fixed times
#: rather than a rate across the whole ring: a rate would give the heaviest
#: blow in the game the *shortest* animation, because a chunk a third of the
#: ring long would be a third of the way through the drain before it was drawn.
#: A blow reads as a blow at any size, and the size is in how much of the ring
#: lights up rather than in how long it takes to go.
HULL_CHIP_HOLD_S = 0.35
HULL_CHIP_DECAY_S = 0.35
#: How much thicker the lost chunk is drawn than the arc it came off. Colour
#: alone cannot carry it: every Shrike arrival happens at a full signature
#: meter, which puts a saturated red arc twenty pixels outside the hull arc and
#: a red border behind both, and a red chunk is a small sliver inside all of
#: that. A chunk that stands proud of the ring reads as a loss on a red screen
#: and reads for a pilot who cannot separate the two reds at all.
HULL_CHIP_THICKNESS_MULT = 2.2

#: How long one edge stays desaturated after a hit from that bearing.
DAMAGE_EDGE_DECAY_S = 1.1
#: Damage, in hull points, that saturates the edge hook at 1.0.
DAMAGE_EDGE_FULL_HIT = 25.0
DAMAGE_EDGE_BAND_PX = 26.0
#: Weight the smallest hit still raises its edge to. A scratch from behind is
#: exactly the hit a pilot needs to be told the bearing of, and a band drawn at
#: a tenth of an alpha is a band nobody sees.
DAMAGE_EDGE_MIN_WEIGHT = 0.4

#: Window height every pixel constant in this module is authored against, and
#: the height at which :func:`screen_scale_for` returns 1.0.
UI_SCALE_REFERENCE_HEIGHT_PX = 720.0
#: Clamps on the height-derived half of the UI scale. The floor keeps a small
#: window legible, the ceiling stops a 4K screen drawing a HUD that eats the
#: playfield.
UI_SCALE_FROM_SCREEN_MIN = 0.75
UI_SCALE_FROM_SCREEN_MAX = 2.0
#: Height of one text unit in pixels: ``text(scale=s)`` draws glyphs about
#: ``TEXT_EM_PX * s`` tall. Used to state text sizes as a share of the screen.
TEXT_EM_PX = 16.0

SUBTITLE_HOLD_S = 2.6
SUBTITLE_MAX_LINES = 3
SUBTITLE_LINE_HEIGHT_PX = 26.0
SUBTITLE_BOTTOM_MARGIN_PX = 74.0
#: Captions are read at a glance from the middle of a dodge, so the floor is a
#: share of the screen rather than a pixel count: at the reference height this
#: scale draws them at :data:`SUBTITLE_MIN_HEIGHT_FRACTION` of the screen, and
#: the screen half of the UI scale holds that share at any other height.
SUBTITLE_FONT_SCALE = 1.2
SUBTITLE_MIN_HEIGHT_FRACTION = 0.02
#: The plate the caption stack is written on. Bare text floating over the star
#: field read as debug output rather than as a subtitle track; a caption needs
#: the same dark strip a film gives one before the words mean "this is a sound".
SUBTITLE_PLATE_PADDING_X_PX = 18.0
SUBTITLE_PLATE_PADDING_Y_PX = 6.0
#: Rough advance width of one glyph as a share of its em, used to size plates
#: and to wrap captions. The renderer's font is close enough to monospaced at
#: HUD sizes that a plate measured this way never crops a line.
GLYPH_ADVANCE_FRACTION = 0.56

#: The control card. Onboarding's channel: one panel, big type, no queue.
CONTROL_CARD_FONT_SCALE = 2.0
CONTROL_CARD_HINT_FONT_SCALE = 1.1
#: Where the panel's top edge sits, as a fraction of the screen's height. High
#: enough to clear the ship and its gauge ring at the centre of the screen.
CONTROL_CARD_TOP_FRACTION = 0.11
CONTROL_CARD_WIDTH_PX = 640.0
CONTROL_CARD_PADDING_PX = 10.0
CONTROL_CARD_LINE_HEIGHT_PX = 36.0
CONTROL_CARD_HINT_LINE_HEIGHT_PX = 24.0
#: How far a long lesson line may be shrunk to stay inside its own plate. The
#: card is authored at :data:`CONTROL_CARD_FONT_SCALE`, but the lesson lines are
#: sentences of varying length, and unshrunk the long ones run off both ends.
CONTROL_CARD_MIN_FONT_SCALE = 0.9
#: How far above the screen's top edge the card may be pushed when it has to
#: yield, and the gap it keeps from whatever it is yielding to.
CONTROL_CARD_MIN_TOP_PX = 8.0
CONTROL_CARD_CLEARANCE_PX = 10.0
#: The card's yielded form: title only, in smaller type on a tighter plate. A
#: pilot flying with the mouse high puts the ship near the top of the screen,
#: and the full card then has nowhere to be that is not on top of the ship's
#: own status band. The lesson shrinks; the ship's readings do not move.
CONTROL_CARD_COMPACT_FONT_SCALE = 1.35
CONTROL_CARD_COMPACT_LINE_PX = 26.0
CONTROL_CARD_COMPACT_PADDING_PX = 8.0
#: The card's hold meter: a real bar across the foot of the panel, drawn as a
#: dim track with a bright fill, never typed characters in the hint line: a
#: row of hashes inside square brackets in the middle of a tutorial panel is
#: what unfinished software looks like.
CONTROL_CARD_BAR_HEIGHT_PX = 6.0
CONTROL_CARD_BAR_GAP_PX = 6.0
#: The typed form, still read off a hint so it can be turned into the drawn one.
TYPED_BAR_OPEN = "["
TYPED_BAR_CLOSE = "]"
TYPED_BAR_FULL = "#"
TYPED_BAR_EMPTY = "."
TYPED_BAR_GLYPHS = TYPED_BAR_FULL + TYPED_BAR_EMPTY

#: The sector arrival card: the name of the place and one line about it, held
#: long enough to read from the middle of a warp-in and then gone. It is not a
#: control card and never queues behind one; it owns the band under the card.
ARRIVAL_CARD_HOLD_S = 2.5
ARRIVAL_CARD_FADE_S = 0.45
ARRIVAL_CARD_TOP_FRACTION = 0.24
ARRIVAL_CARD_FONT_SCALE = 2.2
ARRIVAL_CARD_FLAVOUR_FONT_SCALE = 1.15
ARRIVAL_CARD_LINE_PX = 40.0
ARRIVAL_CARD_FLAVOUR_LINE_PX = 24.0

#: The standing sector name, top right, so "where am I" survives the card that
#: announced it. Sits opposite the scrap and notoriety stack.
SECTOR_NAME_FONT_SCALE = 1.05
SECTOR_NAME_LINE_PX = 20.0
#: The box the name is right-aligned inside. Named because a waypoint label has
#: to know how much of the top right corner the name is actually holding.
SECTOR_NAME_BOX_PX = 320.0

STAMP_HOLD_S = 1.6
STAMP_FADE_S = 0.5
STAMP_FONT_SCALE = 2.4
#: Where the stamp lands, as fractions of the screen height. Named rather than
#: inlined because the top band has to know what it must not draw over.
STAMP_TOP_FRACTION = 0.32
STAMP_HEIGHT_FRACTION = 0.12

READOUT_MARGIN_PX = 22.0
READOUT_FONT_SCALE = 1.0
READOUT_LINE_HEIGHT_PX = 20.0

#: The developer frame readout, behind :data:`DEBUG_FRAME_STATS_ACTION`. A
#: rolling window rather than the live dt: one frame's wall clock on a laptop is
#: mostly scheduler noise, and the question the readout exists to answer is
#: whether this build is hotter than the last one. The worst frame in the window
#: is printed beside the mean, because a stutter is what a pilot actually feels
#: and a mean hides it.
DEBUG_FRAME_STATS_ACTION = "debug_frame_stats"
FRAME_STATS_WINDOW = 90
FRAME_STATS_FONT_SCALE = 0.85
FRAME_STATS_LINE_PX = 16.0
FRAME_STATS_WIDTH_PX = 300.0
#: How many GPU phases the readout prints, worst first. A driver with timestamp
#: pools reports every pass; the list is long and the hot end is the only part
#: worth reading off a screen.
FRAME_STATS_GPU_ROWS = 6

#: The toast line: one short answer to a key press, above the caption stack.
TOAST_HOLD_S = 3.2
TOAST_FADE_S = 0.4
TOAST_FONT_SCALE = 1.4
TOAST_LINE_HEIGHT_PX = 30.0
#: Pixels between the toast line and the top of the caption stack.
TOAST_GAP_PX = 12.0
#: Clearance the message line keeps from every standing line it steps around.
#:
#: The answer to a key press is anchored to the screen and the ship's standing
#: lines are anchored to the hull, so the two rows cross whenever the pilot
#: flies at the height that puts them together, and a refusal written straight
#: through OBJECTIVE reads as neither. The message keeps its row unless a
#: standing line is in it, and then it takes the nearest free row rather than
#: sharing one (:meth:`Hud.message_row`).
MESSAGE_ROW_GAP_PX = 10.0
#: How a second answer is folded into the line rather than replacing it.
#:
#: Two systems can answer one key press in the same frame: the tutorial says
#: what the script wants first, the run says why the key refused. Both land,
#: in one sentence: if whichever spoke last were the whole answer, a pilot
#: pressing Z in the first minute would read "FIRST: FLY: W A S D" and file the
#: generator key as dead.
TOAST_WITH_NOTE = "{text} ({note})"
#: Seconds a note stays open to being joined by a later answer to the same
#: press. Long enough to cross a frame, short enough that the next key press is
#: answered on its own.
TOAST_NOTE_JOIN_S = 0.5

#: World-anchored floating text: a pickup's value, a first-sighting tag.
FLOAT_TEXT_HOLD_S = 1.6
FLOAT_TEXT_FADE_S = 0.45
FLOAT_TEXT_RISE_PX = 46.0
FLOAT_TEXT_FONT_SCALE = 1.1
#: Ceiling on how many float labels are alive at once. A shoal dying into a
#: scoop pass must not be able to paper the screen.
FLOAT_TEXT_MAX = 8
#: A pickup label that credits a counter flies to it rather than drifting off
#: into space. "+12 SCRAP" rising over the wreck it came out of and fading
#: never points at the SCRAP readout, which then stays a number in a corner
#: that nobody connects to anything they did. The flight eases
#: in, so the label is still legible where it landed before it goes.
FLOAT_TEXT_FLIGHT_EASE = 2.4
#: Which counters a float can be addressed to. The ids are the resource words
#: the labels themselves use, lowercased, so a label that names a counted
#: resource finds its counter without the caller having to say so twice.
FLOAT_TARGET_SCRAP = "scrap"
FLOAT_TARGETS: frozenset[str] = frozenset({FLOAT_TARGET_SCRAP})
#: How a banked credit is written once a whole unit of it has landed.
CREDIT_FLOAT_FORMAT = "+{amount:.0f} {label}"

#: Hull fraction below which the border pulses and the klaxon keeps returning.
LOW_HULL_FRACTION = 0.30
#: Seconds between repeats of the low-hull klaxon while the hull stays there.
LOW_HULL_KLAXON_S = 5.0
#: Pulse rate of the low-hull border, in cycles per second, and its alpha band.
LOW_HULL_PULSE_HZ = 1.6
LOW_HULL_PULSE_MIN_ALPHA = 0.18
LOW_HULL_PULSE_MAX_ALPHA = 0.55
LOW_HULL_BAND_PX = 30.0
#: The dark gutter between the signature border and the low-hull pulse, and
#: how far inboard that puts the pulse. Both warnings are red rings on the same
#: four edges, and drawn concentric from the same edge they read as one band: a
#: pilot at low hull would not see the signature border collapse on arrival,
#: which is the whole point of having jumped. The pulse steps inboard past the
#: signature band's widest, leaving the outermost pixels to the meter alone, so
#: what a jump does to the screen is visible whatever the hull is doing. In
#: unscaled pixels because the band it steps around is: see
#: :meth:`Hud._draw_signature_border`.
LOW_HULL_GUTTER_PX = 8.0
LOW_HULL_INSET_PX = SIGNATURE_BORDER_MAX_PX + LOW_HULL_GUTTER_PX
#: The warning lines under the gauge ring, and their type size.
WARNING_FONT_SCALE = 1.25
WARNING_LINE_HEIGHT_PX = 24.0
LOW_HULL_WARNING = "HULL CRITICAL"

# ---------------------------------------------------------------------------
# Reserved layout slots under the ship
#
# Each kind of line the HUD writes below the hull owns a band and never leaves
# it: measured from one shared offset, the warp chip, the boundary line and the
# survival warnings would land on one row and overprint each other into an
# unreadable smear. A band holds its place whether or not its
# neighbours have anything to say: a slot that is empty stays empty, because a
# line that moves when its neighbour appears is a line the pilot has to find
# again every time.
#
# Offsets are pixels below the ship's centre at UI scale 1, from the top of the
# band. Bands are sized by the lines they can hold, so widening one is a matter
# of raising its line count and letting the next band fall where it falls.
# ---------------------------------------------------------------------------

#: The resource strip: every number the run can charge or credit, in one row
#: under the gauge ring. It is the first band because it is the one a pilot
#: glances at mid-manoeuvre, and it is never subtracted: the game quotes prices
#: in scrap, fuel and air from the first minute of the first run, and a price
#: quoted against a number nobody can see is a price nobody can pay.
#: It starts below the capacitor caption, which is the lowest thing the ring
#: cluster writes, rather than at a hand-set offset that the caption could land
#: on, and its own plate's padding is part of the offset at both ends: the
#: plate is what the eye reads as the edge of the strip, so a neighbour that
#: clears the type but not the plate still reads as touching it.
RESOURCE_LINE_PX = 22.0
#: Width of one resource cell. Fixed, so a number growing a digit never shoves
#: its neighbours sideways.
RESOURCE_CELL_PX = 116.0
RESOURCE_FONT_SCALE = 1.05
#: Margin the strip's plate keeps around the widest of its two rows.
RESOURCE_PLATE_PADDING_PX = 6.0
BAND_RESOURCES_PX = ARC_LABEL_RADIUS_PX + ARC_LABEL_LINE_PX + ARC_LABEL_CLEARANCE_PX + RESOURCE_PLATE_PADDING_PX

#: The context line: what the drive can do right now. One line.
BAND_CONTEXT_PX = BAND_RESOURCES_PX + RESOURCE_LINE_PX + STATE_PIP_LINE_PX + RESOURCE_PLATE_PADDING_PX
BAND_CONTEXT_LINES = 1
#: The survival warnings: hull, air, and the air's own advice. Three lines.
BAND_WARNING_PX = BAND_CONTEXT_PX + BAND_CONTEXT_LINES * WARNING_LINE_HEIGHT_PX
BAND_WARNING_LINES = 3
#: The objective line: what the run is asking for, the lock's instruction most
#: of all. Two lines, because the lock's instruction is a long sentence.
BAND_OBJECTIVE_PX = BAND_WARNING_PX + BAND_WARNING_LINES * WARNING_LINE_HEIGHT_PX
BAND_OBJECTIVE_LINES = 2
#: The boundary line: where the sector stops. One line, furthest out, because
#: it is the least urgent thing down here.
BAND_BOUNDARY_PX = BAND_OBJECTIVE_PX + BAND_OBJECTIVE_LINES * WARNING_LINE_HEIGHT_PX
BAND_BOUNDARY_LINES = 1
#: How far the whole ladder reaches under the hull. The bands are pinned to the
#: ship and the ship is not pinned to anything: thrust makes the camera lag and
#: the hull rides down the screen, carrying the bottom of this ladder toward
#: the controls strip along the foot of the frame.
BAND_LADDER_PX = BAND_BOUNDARY_PX + BAND_BOUNDARY_LINES * WARNING_LINE_HEIGHT_PX
#: The two lowest bands ride up together when the hull is low enough that the
#: ladder would otherwise reach the bottom furniture, and this is as far as they
#: can ever go: the foot of the resource strip's plate, which is up for the
#: whole run. What they actually get is whatever of it the bands between are
#: not using this frame (:meth:`Hud._lower_band_ceiling`).
BAND_LOWER_LIFT_MAX_PX = BAND_OBJECTIVE_PX - BAND_CONTEXT_PX

#: Half-width of the band the lines are laid out in, so a long instruction has
#: somewhere to go rather than being clipped into a shorter sentence.
BAND_HALF_WIDTH_PX = 380.0

#: What to do about the air, in the same breath as the countdown. A number
#: counting down with no acquisition beside it is a death sentence with a
#: clock; these are the two places oxygen actually comes from.
LOW_O2_HINT = "LOW O2: canisters at depots; ice fields refill (M: chart)"

#: The same for the other clock. An empty tank does not suffocate anybody, it
#: strands them, and a pilot who learns that at the moment the drive refuses
#: has already spent the scrap that would have bought the way out. So the tank
#: warns while there is still something to do about it, and names the one
#: place fuel comes from in the same breath.
#:
#: The advice is named on its own because the drive's own refusal carries it
#: too, and once the tank will not cover a jump both lines are on screen a
#: hand's width apart. Two spellings of one instruction read as two errands.
LOW_FUEL_SOURCE = "depots sell fuel cells"
LOW_FUEL_HINT = f"LOW FUEL: {LOW_FUEL_SOURCE}"
#: Jumps left in the tank at or under which the hint stands up, measured at
#: ``balance.WARP_FUEL_BASE`` because that is the fare the chart quotes for a
#: hop to the next column. It is the depot screen's own threshold
#: (``flow.DEPOT_LOW_FUEL_JUMPS``), and test_hud pins the two together: a bay
#: that says the tank is low and a HUD that does not is two answers to one
#: question.
LOW_FUEL_JUMPS = 2.0

#: The standing cue for a pilot flying out of the sector, pushed per frame by
#: whoever owns the boundary, and cleared this long after the pushes stop.
BOUNDARY_NOTICE_HOLD_S = 0.25

#: Screen-edge compass markers for the nearest thing of each kind, pushed per
#: frame the same way. They are suppressed the moment any of them is on screen:
#: a marker over something the pilot can already see is noise.
COMPASS_HOLD_S = 0.25
COMPASS_RADIUS_PX = 7.0
COMPASS_EDGE_MARGIN_PX = 40.0
COMPASS_FONT_SCALE = 0.9
#: How far inside the screen a target has to land to count as visible.
COMPASS_ON_SCREEN_MARGIN_PX = 24.0
#: One short word per kind, and a silhouette to go with it. A vein is a
#: "VEIN" and never "ORE": the number beside a waypoint is a range, and a
#: waypoint labelled with the name of a resource reads as a second currency.
COMPASS_LABELS: dict[str, str] = {"deposit": "VEIN", "wreck": "HULK", "depot": "DEPOT"}
COMPASS_SEGMENTS: dict[str, int] = {"deposit": 3, "wreck": 4, "depot": 8}
#: The unit on every waypoint range. A bare number next to a word is read as a
#: quantity of that word; "41 u" is read as a distance, which is what it is.
RANGE_UNIT_SUFFIX = "u"
#: Minimum vertical separation between two waypoint labels before the later one
#: is pushed clear of the earlier.
MARKER_LABEL_SEPARATION_PX = 22.0
#: Half the width of the rect a waypoint label is centred in, and the wider one
#: the Shrike countdown uses.
MARKER_LABEL_HALF_WIDTH_PX = 90.0
HUNTER_LABEL_HALF_WIDTH_PX = 130.0
#: How far inside the screen's side edges a marker label's rect is kept. The
#: marker itself is clamped by :meth:`Hud._marker_point`, but a label rect
#: centred on it would hang half off the edge ("SHRIKE INBOUND: 60 s" would
#: start at x=-33 in a 1280-wide frame), so the rect slides inboard instead.
LABEL_EDGE_INSET_PX = 6.0
#: How far inside the bottom edge a marker is allowed to pin, whatever edge
#: margin its own kind uses. The caption strip and the controls strip own the
#: bottom of the screen between them, and a range written through either of
#: them is two unreadable lines rather than one reading. The marker's own
#: label hangs below it, so the reservation carries the label's row as well.
MARKER_LABEL_GAP_PX = 16.0
MARKER_BOTTOM_MARGIN_PX = (
    SUBTITLE_BOTTOM_MARGIN_PX
    + SUBTITLE_LINE_HEIGHT_PX * SUBTITLE_MAX_LINES
    + MARKER_LABEL_GAP_PX
    + WARNING_LINE_HEIGHT_PX
)
#: Clearance a waypoint label keeps from every piece of standing HUD it steps
#: around (:meth:`Hud._label_zones`). A label butted flush against the edge of
#: the sector name or of a caption plate is still two readings the eye has to
#: separate; a few pixels of dark between them is what makes them two lines.
MARKER_ZONE_CLEARANCE_PX = 5.0
#: How far a waypoint label may step from the row under its own ring before it
#: stops being that ring's label. The stack under the hull is wide and deep, so
#: "the nearest free row" can be most of a screen away, and a range floating at
#: the top of the frame over a ring at the bottom of it is worse than no range
#: at all. Past this the marker stands down for the frame instead.
MARKER_LABEL_MAX_TRAVEL_PX = 120.0

#: The spool's endings. A ring that simply disappears is the whole of "the
#: circle goes big then small and nothing happens", so an ending that is not a
#: jump holds the ring for a beat in red with its name under it, and a jump
#: whites out the screen the way arriving somewhere should.
WARP_OUTCOME_FLASH_S = 1.2
WARP_ABORTED_LABEL = "SPOOL ABORTED"
WARP_JUMP_FLASH_S = 0.45
WARP_JUMP_FLASH_ALPHA = 0.85

#: The depot beacon: a ring at the depot's bearing with the range under it.
BEACON_RADIUS_PX = 9.0
BEACON_EDGE_MARGIN_PX = 48.0
BEACON_FONT_SCALE = 1.0
#: How close the hull has to be for the beacon to become the dock prompt.
#: Pinned by test to ``trading.DOCK_RADIUS``, which is the radius the bay
#: actually docks at: a prompt that appears outside the bay is a key that does
#: nothing, and one that appears inside it and is written somewhere else is a
#: key nobody finds: with "F: DOCK" as one small line at the top of the screen
#: under a tutorial card, a pilot can cross the ring three times without
#: docking.
DOCK_PROMPT_RANGE_UNITS = 14.0
#: What the ring says when nothing else has claimed the verb line.
DOCK_PROMPT = "F: DOCK"
#: The word that marks a pushed affordance as being about the dock, so the
#: ring can carry the run's own wording ("DOCKED: hold F to sell") instead of
#: a fixed line that is wrong the moment the bay opens.
DOCK_PROMPT_KEYWORD = "DOCK"
#: The ring's armed form: filled, larger, and in the affordance's own colour,
#: so being inside the bay is a state the ring shows rather than a fact the
#: pilot has to infer from a range that stopped going down.
BEACON_ARMED_RADIUS_MULT = 1.7
BEACON_ARMED_FONT_SCALE = 1.25

#: An interact fill is pushed per frame while the button is held; it clears
#: this long after the last push so a released button does not leave a ghost.
INTERACT_FILL_HOLD_S = 0.12

#: The affordance line: pushed per frame by whoever owns the reach, and cleared
#: this long after the pushes stop, so a verb that has just left range goes with
#: it instead of hanging over empty space.
AFFORDANCE_HOLD_S = 0.20
#: How far above the signature gauge the affordance line sits, and its type.
#: Measured from the top of the gauge rather than from the ring, so the verb
#: in reach never lands on the meter's reading.
AFFORDANCE_GAP_PX = 22.0
AFFORDANCE_LINE_PX = 24.0
AFFORDANCE_FONT_SCALE = 1.3

#: The persistent controls bar along the bottom edge.
CONTROLS_BAR_MARGIN_PX = 12.0
CONTROLS_BAR_LINE_PX = 20.0
CONTROLS_BAR_FONT_SCALE = 0.95
#: The default bar, in two rows. The first is written in the order a pilot
#: needs the keys rather than the order the action map lists them: fly, aim,
#: shoot, harvest, act, leave, look. The second covers every remaining bound
#: key, because a verb the strip does not name is a verb the player does not
#: have, and silent running is the answer to half of what kills them.
CONTROLS_BAR_TEXT = "WASD FLY   MOUSE AIM   LMB FIRE   RMB MINE   F INTERACT   R WARP   M CHART   ESC PAUSE   H HIDE"
CONTROLS_BAR_SECOND_ROW = "C SILENT   SHIFT BURN   Q/E SHIELD   Z GENERATOR   X WINGS   G JETTISON   TAB SCOOP"
#: The strip's own plate. Dim letters over a starfield turn the bar
#: into a smear of motes with words behind it; the plate is what makes the row
#: legible over anything the sector happens to be drawing under it.
CONTROLS_BAR_PLATE_PADDING_PX = 5.0
#: How much of the bottom edge the strip owns. Waypoint labels are kept above
#: it: a range written through a key list is two unreadable lines, not one.
CONTROLS_BAR_BAND_PX = CONTROLS_BAR_MARGIN_PX + 2.0 * CONTROLS_BAR_LINE_PX + 2.0 * CONTROLS_BAR_PLATE_PADDING_PX

#: Seconds between rescans while any wanted signal still has no emitter.
SOURCE_RESCAN_S = 0.5
#: Seconds between re-reads of the hull's magazines. A depot refit is the one
#: thing that changes the ammunition aboard without a shot being fired.
AMMO_POLL_S = 0.5

# Palette. Low-albedo environments and emissive gameplay colours mean the HUD
# can stay dim: these are read against near-black, not against daylight.
#: The dim rail behind every gauge fill. Nearly opaque rather than a wash: the
#: track is what tells a bright frame where the ring is, and at about half alpha
#: it dissolves into a lit lantern cone along with the fill it is backing.
COLOUR_TRACK = (0.10, 0.12, 0.16, 0.88)
COLOUR_HULL = (0.86, 0.89, 0.95, 0.92)
COLOUR_CAPACITOR = (0.42, 0.84, 1.00, 0.92)
COLOUR_O2 = (0.55, 1.00, 0.78, 0.92)
COLOUR_FUEL = (1.00, 0.72, 0.34, 0.92)
COLOUR_SIGNATURE_COLD = (0.20, 0.48, 0.72, 0.35)
COLOUR_SIGNATURE_HOT = (0.92, 0.13, 0.10, 0.90)
COLOUR_WARP_RING = (0.62, 0.82, 1.00, 0.88)
COLOUR_INTERACT = (1.00, 0.94, 0.72, 0.90)
COLOUR_STAMP = (1.00, 0.96, 0.92, 1.00)
COLOUR_SUBTITLE = (0.92, 0.94, 1.00, 0.90)
COLOUR_READOUT = (0.78, 0.82, 0.90, 0.85)
#: The developer readout and the plate under it. Deliberately not a game colour:
#: nothing in the fiction is this green, so a screenshot with it on can never be
#: mistaken for a build that shipped with a debug overlay lit.
COLOUR_FRAME_STATS = (0.62, 1.00, 0.72, 0.95)
COLOUR_FRAME_STATS_PLATE = (0.02, 0.05, 0.03, 0.72)
COLOUR_DESATURATION = (0.52, 0.53, 0.56, 0.60)
#: The PWR arc while a lantern blackout holds the bus at zero: a dead gauge in
#: grey, not a live one that happens to read empty.
COLOUR_BLACKOUT = (0.45, 0.47, 0.52, 0.80)
COLOUR_TOAST = (1.00, 0.92, 0.68, 0.96)
COLOUR_FLOAT_TEXT = (0.98, 0.90, 0.62, 0.95)
COLOUR_ENEMY_TAG = (1.00, 0.62, 0.86, 0.95)
COLOUR_WARNING = (1.00, 0.42, 0.34, 0.95)
#: The chunk a blow just took off the hull arc. Deliberately not
#: :data:`COLOUR_WARNING`: see :data:`HULL_CHIP_THICKNESS_MULT` for why a red
#: sliver is invisible on the one screen it has to be read on. White-hot
#: separates it from the signature arc, the border and the hull arc at once.
COLOUR_HULL_CHIP = (1.00, 0.98, 0.92, 1.00)
COLOUR_LOW_HULL_PULSE = (0.90, 0.16, 0.14, 1.00)
COLOUR_BEACON = (0.62, 1.00, 0.82, 0.90)
#: The beacon once the hull is inside the bay: the affordance colour, so the
#: ring and the verb line read as one thing.
COLOUR_BEACON_ARMED = (0.72, 1.00, 0.88, 0.98)
COLOUR_COMPASS = (0.72, 0.86, 1.00, 0.82)
COLOUR_HINT = (0.86, 0.90, 1.00, 0.85)
COLOUR_WARP_FAILED = (1.00, 0.32, 0.26, 0.95)
COLOUR_JUMP_FLASH = (1.00, 1.00, 1.00, 1.00)
COLOUR_AFFORDANCE = (0.72, 1.00, 0.88, 0.98)
COLOUR_CONTROLS_BAR = (0.62, 0.66, 0.76, 0.72)
COLOUR_WARP_STATUS = (0.62, 0.82, 1.00, 0.80)
COLOUR_WARP_STATUS_BLOCKED = (1.00, 0.62, 0.40, 0.85)
COLOUR_CONTROL_CARD_PANEL = (0.05, 0.07, 0.12, 0.82)
COLOUR_CONTROL_CARD_EDGE = (0.42, 0.84, 1.00, 0.55)
COLOUR_CONTROL_CARD_TEXT = (1.00, 0.97, 0.90, 0.98)
COLOUR_CONTROL_CARD_HINT = (0.72, 0.80, 0.92, 0.88)
COLOUR_CONTROL_CARD_BAR = (0.42, 0.84, 1.00, 0.95)
COLOUR_CONTROL_CARD_BAR_TRACK = (0.16, 0.20, 0.28, 0.85)
COLOUR_CONTROLS_BAR_PLATE = (0.03, 0.04, 0.07, 0.72)
COLOUR_OBJECTIVE = (1.00, 0.86, 0.52, 0.96)
COLOUR_HUNTER_MARKER = (1.00, 0.38, 0.30, 0.95)
COLOUR_SUBTITLE_PLATE = (0.02, 0.03, 0.06, 0.80)
COLOUR_SCRAP = (0.98, 0.90, 0.62, 0.95)
COLOUR_ARRIVAL_CARD = (0.86, 0.96, 1.00, 1.00)
COLOUR_ARRIVAL_FLAVOUR = (0.72, 0.82, 0.94, 0.95)
COLOUR_SHIELD = (0.52, 0.92, 1.00, 0.95)
COLOUR_SHIELD_BROKEN = (1.00, 0.46, 0.36, 0.90)
COLOUR_STATE_PIP_ON = (0.62, 1.00, 0.78, 0.95)
COLOUR_STATE_PIP_OFF = (0.42, 0.46, 0.54, 0.75)
COLOUR_AMMO = (1.00, 0.84, 0.62, 0.95)
#: The plate under the resource strip and its pips. Faint, because these numbers
#: sit over the playfield and the plate is there to stop a bright nebula or a
#: passing wreck washing the row out, not to box it in.
COLOUR_RESOURCE_PLATE = (0.02, 0.03, 0.06, 0.55)
#: The plate under each reading around the hull. Darker and more opaque than
#: the strip's, because the thing it has to survive is not a nebula: it is a
#: lantern cone drawn several stops over white across the middle of the frame.
COLOUR_READING_PLATE = (0.02, 0.03, 0.06, 0.78)
#: The plate under the drive's chip. Heavier again than a reading's, because
#: what it has to keep off those numbers is not a backdrop but a line: the
#: failed spool's ring holds its radius across this band for a beat.
COLOUR_WARP_STATUS_PLATE = (0.02, 0.03, 0.06, 0.92)


def screen_scale_for(height: float) -> float:
    """The height-derived half of the UI scale for a window *height* tall.

    Linear in the window's height against :data:`UI_SCALE_REFERENCE_HEIGHT_PX`
    and clamped to :data:`UI_SCALE_FROM_SCREEN_MIN` ..
    :data:`UI_SCALE_FROM_SCREEN_MAX`, so text keeps its share of the screen
    instead of shrinking into it.
    """
    scale = float(height) / UI_SCALE_REFERENCE_HEIGHT_PX
    return min(UI_SCALE_FROM_SCREEN_MAX, max(UI_SCALE_FROM_SCREEN_MIN, scale))


# ============================================================================
# Element vocabulary and the subtraction schedule
# ============================================================================


class HudElements:
    """Ids for every subtractable HUD element.

    ``flow.Onboarding.visible_hud_elements`` returns a subset of these and the
    run scene hands it to :meth:`Hud.set_visible_elements`. Ids are strings so
    a saved assist profile can round-trip them.
    """

    HULL = "hull"
    CAPACITOR = "capacitor"
    O2 = "o2"
    FUEL = "fuel"
    #: The numeric strip under the ring, and the power-state pips beside it.
    RESOURCES = "resources"
    STATE_PIPS = "state_pips"
    SHIELD = "shield"
    SECTOR = "sector"
    ARRIVAL_CARD = "arrival_card"
    SIGNATURE = "signature"
    AMMO = "ammo"
    SCRAP = "scrap"
    NOTORIETY = "notoriety"
    GENERATOR = "generator"
    SILENT_RUNNING = "silent_running"
    WARP_SPOOL = "warp_spool"
    INTERACT_FILL = "interact_fill"
    DAMAGE_DIRECTION = "damage_direction"
    SUBTITLES = "subtitles"
    STAMP = "stamp"
    CONTROL_CARD = "control_card"
    TOAST = "toast"
    FLOAT_TEXT = "float_text"
    WARNINGS = "warnings"
    BEACON = "beacon"
    AFFORDANCE = "affordance"
    CONTROLS_BAR = "controls_bar"
    WARP_STATUS = "warp_status"


ALL_HUD_ELEMENTS: frozenset[str] = frozenset(
    value for name, value in vars(HudElements).items() if not name.startswith("_") and isinstance(value, str)
)

#: The run-one floor: the core gauges, plus the diegetic and accessibility
#: elements that are never subtracted. The spool ring, the interact fill and the
#: damage edge are part of the fiction rather than a readout, and subtitles and
#: stamps carry information the mix would otherwise gate on hearing, so
#: onboarding hides none of them. The control card is in the floor for the same
#: reason in reverse: run one is the run that needs it, and so are the survival
#: warnings, the toast line, world-anchored labels and the depot beacon: they
#: answer a question the pilot has just asked, or tell them they are about to
#: die, and neither is a readout to be earned. The affordance line, the controls
#: bar and the warp chip are in the floor for the same reason: they name the
#: verbs, and a game that hides its verbs from a first-time pilot has subtracted
#: the wrong thing.
#:
#: The resource numbers are in the floor because of one rule: **anything the
#: run can charge or credit carries a visible number from the first moment it
#: is touched.** Run one quotes five scrap for a patch, fifteen fuel for a jump
#: and ten air for a canister, so subtracting any of those readouts would leave
#: a price charged against a number nobody can see. Only ammunition and
#: notoriety may still wait, because run one neither spends nor earns either.
MINIMAL_HUD_ELEMENTS: frozenset[str] = frozenset(
    {
        HudElements.HULL,
        HudElements.CAPACITOR,
        HudElements.O2,
        HudElements.FUEL,
        HudElements.SCRAP,
        HudElements.RESOURCES,
        HudElements.STATE_PIPS,
        HudElements.SHIELD,
        HudElements.SECTOR,
        HudElements.ARRIVAL_CARD,
        HudElements.GENERATOR,
        HudElements.SIGNATURE,
        HudElements.WARP_SPOOL,
        HudElements.INTERACT_FILL,
        HudElements.DAMAGE_DIRECTION,
        HudElements.SUBTITLES,
        HudElements.STAMP,
        HudElements.CONTROL_CARD,
        HudElements.TOAST,
        HudElements.FLOAT_TEXT,
        HudElements.WARNINGS,
        HudElements.BEACON,
        HudElements.AFFORDANCE,
        HudElements.CONTROLS_BAR,
        HudElements.WARP_STATUS,
    }
)

#: The resources whose numbers the strip carries, as
#: ``(element_id, label, colour)``. Every one of them is a price the game
#: quotes out loud somewhere in run one.
RESOURCE_CELLS: tuple[tuple[str, str, tuple[float, float, float, float]], ...] = (
    (HudElements.SCRAP, "SCRAP", COLOUR_SCRAP),
    (HudElements.FUEL, "FUEL", COLOUR_FUEL),
    (HudElements.O2, "O2", COLOUR_O2),
)

#: The ammunition cell, which joins the strip only once the hull has a ballistic
#: weapon or a box aboard. It counts loaded rounds and stowed boxes together,
#: because "can I keep shooting" is one question. A hull with a gun and nothing
#: to feed it reads ``AMMO 0``, which is the reading that matters most.
AMMO_CELL = "AMMO {rounds:.0f}"


# ============================================================================
# Subtitle glyphs
# ============================================================================

#: Every audio cue, as ``cue_id -> caption``. ``audio.AudioDirector`` plays
#: these ids and the HUD captions them; the two must agree, so the ids here are
#: the registry and a new cue is added to both in one change. The wordings match
#: ``audio.CUES`` exactly for every shared id.
#:
#: A caption is a diegetic phrase in small caps naming what was heard: KLAXON,
#: HULL BREACHED, WHISTLE. It is never the cue's id, never a developer shorthand
#: and never punctuated: a line such as ``!! klaxon``, ``[klaxon]`` or
#: ``* klaxon *`` in the middle of the screen reads as placeholder text that
#: shipped, because punctuation around a word is what unfinished software looks
#: like. The dark plate under the stack (:data:`COLOUR_SUBTITLE_PLATE`) is the
#: whole of the convention: a caption track is a strip of prose on a plate.
CUE_SUBTITLES: dict[str, str] = {
    "generator_hum": "GENERATOR HUM",
    "hull_creak": "HULL CREAKS",
    "silent_running": "HULL CREAKS ONLY",
    "klaxon": "KLAXON",
    "sonar_ping": "SONAR PING",
    "groan": "DISTANT GROAN",
    "heartbeat": "HEARTBEAT",
    "kill": "KILL CHIME",
    "kill_chime": "KILL CHIME",
    "weapon_fire": "SHOT",
    "breathing": "LABOURED BREATHING",
    "spool_stutter": "SPOOL STUTTERS",
    "spawn_chevron": "HOSTILES INBOUND",
    "mortar_whistle": "WHISTLE",
    "signature_locked": "SIGNATURE LOCKED",
    "tear_in": "IT TEARS IN",
    "lantern_burn": "LANTERN BURN",
    "lantern_charge": "LANTERN CHARGING",
    "energy_denied": "CAPACITOR EMPTY",
    "breach": "HULL BREACHED",
}

#: How a positional cue names the side it came from, in the order of
#: :data:`_EDGES` (left, right, top, bottom). Words rather than arrows: an arrow
#: welded to a caption is one more piece of punctuation to be read as scaffolding.
CAPTION_DIRECTIONS = ("LEFT", "RIGHT", "ABOVE", "BELOW")
#: How a direction is joined to its caption.
CAPTION_DIRECTION_FORMAT = "{caption}, {direction}"


def caption_for(cue: str) -> str:
    """The caption line for audio cue *cue*.

    An id with no entry in :data:`CUE_SUBTITLES` is captioned from the id
    itself rather than dropped: a missing caption is an accessibility defect
    and a clumsy one is a cosmetic defect, and they are not the same size. It
    is still written in the caption track's own voice, so an id that slips
    through reads as a sound rather than as an instruction.
    """
    caption = CUE_SUBTITLES.get(cue)
    return caption if caption is not None else str(cue).replace("_", " ").upper()


def _caption_base(line: str) -> str:
    """*line* without its side suffix, for de-duplicating one sound's captions."""
    for direction in CAPTION_DIRECTIONS:
        suffix = CAPTION_DIRECTION_FORMAT.format(caption="", direction=direction)
        if line.endswith(suffix):
            return line[: -len(suffix)]
    return line


# ============================================================================
# Geometry helpers
# ============================================================================

#: ``element_id -> (centre_degrees, span_degrees, colour, caption, compass)``.
#: Screen angles run clockwise from +X because screen Y points down, so 90 is
#: below the ship. *compass* is the fixed point the caption is pinned to, which
#: is always the arc's own bearing: the caption is placed outside every ring
#: there, not on the arc, so four coloured strokes read as four named gauges
#: rather than as four strokes with words written through them.
_ARC_SPECS: tuple[tuple[str, float, float, tuple[float, float, float, float], str, str], ...] = (
    (HudElements.CAPACITOR, 90.0, 84.0, COLOUR_CAPACITOR, "PWR", "bottom"),
    (HudElements.HULL, 270.0, 84.0, COLOUR_HULL, "HULL", "top"),
    (HudElements.O2, 180.0, 58.0, COLOUR_O2, "O2", "left"),
    (HudElements.FUEL, 0.0, 58.0, COLOUR_FUEL, "FUEL", "right"),
)

#: Which gauges write their number beside their caption. Hull and capacitor have
#: no cell in the resource strip, and a bar with no number is a reading nobody
#: can quote back: "how much hull have I got" would have no answer anywhere on
#: the screen.
_ARC_VALUE_ELEMENTS: frozenset[str] = frozenset({HudElements.HULL, HudElements.CAPACITOR})

_EDGES = ("left", "right", "top", "bottom")

#: Every signal the HUD listens for, mapped to the method that handles it.
#: Discovery stops rescanning once each of these has an emitter.
_SIGNAL_HANDLERS: dict[str, str] = {
    SignalNames.HULL_CHANGED: "_on_hull_changed",
    SignalNames.BREACH_OPENED: "_on_breach_opened",
    SignalNames.BREACH_PATCHED: "_on_breach_patched",
    SignalNames.CAPACITOR_CHANGED: "_on_capacitor_changed",
    SignalNames.ENERGY_DENIED: "_on_energy_denied",
    SignalNames.O2_CHANGED: "_on_o2_changed",
    SignalNames.FUEL_CHANGED: "_on_fuel_changed",
    SignalNames.GENERATOR_CHANGED: "_on_generator_changed",
    SignalNames.SILENT_RUNNING_CHANGED: "_on_silent_running_changed",
    SignalNames.SOLAR_STATE_CHANGED: "_on_solar_state_changed",
    SignalNames.AFTERBURNER_CHANGED: "_on_afterburner_changed",
    SignalNames.SIGNATURE_CHANGED: "_on_signature_changed",
    SignalNames.SIGNATURE_LOCKED: "_on_signature_locked",
    SignalNames.AMMO_CHANGED: "_on_ammo_changed",
    SignalNames.SCRAP_CHANGED: "_on_scrap_changed",
    SignalNames.NOTORIETY_CHANGED: "_on_notoriety_changed",
    SignalNames.PLAYER_DAMAGED: "_on_player_damaged",
    SignalNames.ENEMY_KILLED: "_on_enemy_killed",
    SignalNames.WAVE_SPAWNED: "_on_wave_spawned",
    SignalNames.HUNTER_TELEGRAPH: "_on_hunter_telegraph",
    SignalNames.WARP_SPOOL_STARTED: "_on_warp_spool_started",
    SignalNames.WARP_SPOOL_INTERRUPTED: "_on_warp_spool_interrupted",
    SignalNames.WARP_SPOOL_CANCELLED: "_on_warp_spool_cancelled",
    SignalNames.WARP_COMPLETED: "_on_warp_completed",
    # The audio director's own announcement of every cue it plays, however the
    # play was reached. It is what keeps a cue played directly by a system
    # (the hunter's burn klaxon) on the caption track.
    SignalNames.AUDIO_CUE: "_on_audio_cue",
}

_WANTED_SIGNALS: frozenset[str] = frozenset(_SIGNAL_HANDLERS)


class CardLayout(NamedTuple):
    """Where a top-band panel is drawn, and how much of it survived the fit."""

    x: float
    y: float
    width: float
    height: float
    padding: float
    line: float
    font_scale: float
    second_line: float
    second_font_scale: float
    #: Height reserved under the text for the drawn hold bar, 0 when there is none.
    bar: float = 0.0

    @property
    def bottom(self) -> float:
        return self.y + self.height

    @property
    def shows_second_line(self) -> bool:
        return self.second_line > 0.0


def _clamp01(value: float) -> float:
    return 0.0 if value < 0.0 else 1.0 if value > 1.0 else value


def _fraction(current: float, maximum: float) -> float:
    return 0.0 if maximum <= 0.0 else _clamp01(current / maximum)


def _lerp_colour(a, b, t: float) -> tuple[float, float, float, float]:
    """Blend two RGBA tuples, landing exactly on an endpoint at 0 and 1."""
    if t <= 0.0:
        return tuple(a)
    if t >= 1.0:
        return tuple(b)
    return tuple(a[i] + (b[i] - a[i]) * t for i in range(4))


def _with_alpha(colour, alpha: float) -> tuple[float, float, float, float]:
    return (colour[0], colour[1], colour[2], colour[3] * _clamp01(alpha))


def _opaque(colour) -> tuple[float, float, float, float]:
    """*colour* at full alpha, for the elements that are read rather than felt."""
    return (colour[0], colour[1], colour[2], 1.0)


def _read_typed_bar(hint: str) -> tuple[float | None, str]:
    """Split a typed progress bar off *hint*, as ``(fraction, remaining_text)``.

    A hint may report a hold as :data:`TYPED_BAR_OPEN` around a run of fill and
    empty glyphs. On the screen that is a line of punctuation in the middle of a
    tutorial panel, which reads as debug output; as a fraction it is exactly the
    bar the card should be drawing. Callers pass
    :meth:`Hud.show_control_card`'s ``progress`` argument instead, and this
    guard means a caller that does not still gets the drawn version and the
    typed form never reaches the glass.
    """
    start = hint.find(TYPED_BAR_OPEN)
    end = hint.find(TYPED_BAR_CLOSE, start + 1) if start >= 0 else -1
    if start < 0 or end < 0:
        return (None, hint)
    body = hint[start + 1 : end]
    if not body or set(body) - set(TYPED_BAR_GLYPHS):
        return (None, hint)
    filled = sum(1 for glyph in body if glyph == TYPED_BAR_FULL)
    remainder = f"{hint[:start]}{hint[end + 1 :]}".strip()
    return (filled / len(body), remainder)


def _credits_nothing(text: str) -> bool:
    """True for a label like ``"+0 SCRAP"``: a credit that rounds away to nothing.

    Such a label is never drawn. It is not a small credit, it is a wrong one:
    the counter beside it climbs by the fraction the label rounded off, so the
    pilot is shown a zero and a number that moved, in the same breath.
    """
    head = str(text).split(maxsplit=1)
    if not head or not head[0].startswith("+"):
        return False
    try:
        return float(head[0][1:]) == 0.0
    except ValueError:
        return False


def _plate_width(text: str, font_scale: float, scale: float, padding_px: float, limit: float) -> float:
    """Width of a dark plate wide enough to hold *text*, capped at *limit*."""
    width = len(str(text)) * TEXT_EM_PX * GLYPH_ADVANCE_FRACTION * font_scale * scale
    return min(limit, width + 2.0 * padding_px * scale)


def _gpu_phase_rows() -> tuple[tuple[str, float], ...]:
    """The hottest GPU passes the running engine is publishing, worst first.

    Read off ``App.last_telemetry``, which the windowed loop refreshes every
    frame. Empty on every backend that has no timestamp pools, on a headless
    run, and before the first frame has resolved a query.
    """
    try:
        from simvx.graphics import App
    except Exception:
        return ()
    app = App.current()
    telemetry = getattr(app, "last_telemetry", None) if app is not None else None
    phases = telemetry.get("gpu_phase_times") if telemetry else None
    if not phases:
        return ()
    rows = sorted(((str(name), float(value)) for name, value in phases.items()), key=lambda row: -row[1])
    return tuple(rows[:FRAME_STATS_GPU_ROWS])


def _draw_arc(
    renderer, cx: float, cy: float, radius: float, start_deg: float, sweep_deg: float, thickness: float, colour
) -> None:
    """Stroke an arc as a short polyline of thick segments."""
    if abs(sweep_deg) < 1e-3 or radius <= 0.0:
        return
    steps = max(2, int(abs(sweep_deg) / ARC_SEGMENT_DEGREES) + 1)
    step = math.radians(sweep_deg) / steps
    angle = math.radians(start_deg)
    px, py = cx + math.cos(angle) * radius, cy + math.sin(angle) * radius
    for _ in range(steps):
        angle += step
        nx, ny = cx + math.cos(angle) * radius, cy + math.sin(angle) * radius
        renderer.line((px, py), (nx, ny), stroke=colour, width=thickness)
        px, py = nx, ny


# ============================================================================
# Hud
# ============================================================================


class Hud(Control):
    """The run's heads-up display; registered as ``Services.HUD``.

    Anchored full-rect and never positioned absolutely, so it survives a window
    resize and a UI scale change without relayout code. It emits nothing: every
    value it shows arrives on a signal it discovered for itself.
    """

    dynamic = True

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # A full-screen HUD must never eat a click meant for the guns.
        self.pointer_filter = PointerFilter.IGNORE

        # Accessibility: the player's UI-scale slider, multiplied by the scale
        # the window's own height asks for. Only the slider is settable.
        self._settings_scale: float = 1.0
        self._screen_scale: float = 1.0

        self._visible_elements: frozenset[str] = ALL_HUD_ELEMENTS

        self._gauges: dict[str, float] = {
            HudElements.HULL: 1.0,
            HudElements.CAPACITOR: 1.0,
            HudElements.O2: 1.0,
            HudElements.FUEL: 1.0,
        }
        #: Absolute readings behind the arcs. The arcs carry the fraction and
        #: the strip carries the number, and both come off the one signal.
        self._levels: dict[str, float] = {
            HudElements.HULL: 0.0,
            HudElements.CAPACITOR: 0.0,
            HudElements.O2: 0.0,
            HudElements.FUEL: 0.0,
            HudElements.SCRAP: 0.0,
        }
        self._signature = 0.0
        #: Whether the meter has locked and the arrival it bought is still to
        #: come. Cleared by the tear-in and by leaving the sector, which are
        #: the two things that make the instruction stale.
        self._signature_locked = False
        self._notoriety = 0
        self._open_breaches = 0
        self._generator_running = False
        self._silent_running = False
        self._wings_state = ""
        self._afterburner = False
        self._ammo: dict[str, int] = {}

        self._sector_name = ""
        self._arrival_name = ""
        self._arrival_flavour = ""
        self._arrival_remaining = 0.0

        self._warp_active = False
        self._warp_elapsed = 0.0
        self._warp_total = balance.WARP_SPOOL_S
        self._warp_stutter = 0.0
        self._warp_target = ""
        self._warp_fuel = 0.0
        self._warp_price_text = ""
        self._warp_interrupt_text = ""
        self._warp_interrupt_remaining = 0.0

        self._edge_damage: dict[str, float] = dict.fromkeys(_EDGES, 0.0)

        #: The hull fraction before the last blow, while the lost chunk is
        #: still draining off the arc. Equal to the gauge once it has settled.
        self._hull_chip = 1.0
        #: Seconds the chunk still holds at full length, and the fraction of
        #: the ring per second it gives back once the hold runs out. The rate
        #: is set per blow so the drain takes HULL_CHIP_DECAY_S whatever the
        #: blow cost.
        self._hull_chip_hold = 0.0
        self._hull_chip_rate = 0.0

        #: Seconds of air left at the drain rate reported with the last reading.
        self._o2_seconds = float("inf")
        #: Ordinary jumps the tank still covers, at the base fare. Infinite
        #: until a reading lands, so a HUD nobody has told is never "low".
        self._fuel_jumps = float("inf")
        self._low_hull = False
        self._low_hull_klaxon_in = 0.0

        self._beacon_position: Vec3 | None = None
        self._beacon_label = ""

        self._boundary_notice = ""
        self._boundary_remaining = 0.0
        self._objective = ""
        self._compass: tuple[tuple[Vec3, str], ...] = ()
        self._compass_remaining = 0.0

        self._warp_outcome_text = ""
        self._warp_outcome_remaining = 0.0
        self._warp_outcome_fraction = 0.0
        self._warp_jump_flash = 0.0

        self._subtitles: list[list] = []  # [caption, remaining_seconds]
        self._toast_text = ""
        self._toast_remaining = 0.0
        #: The second clause of the answer line and how long a later answer may
        #: still join it. See :meth:`set_toast_note`.
        self._toast_note = ""
        self._toast_note_join = 0.0
        #: Rows waypoint labels have already taken this frame, as
        #: ``(row, left, right)``. Shared by the beacon, the compass and the
        #: Shrike countdown, so no one of them writes "DEPOT 8 u" straight
        #: through another's "VEIN 7 u".
        self._marker_rows: list[tuple[float, float, float]] = []
        #: [text, remaining, total, colour, node_ref, position, toward]
        self._floats: list[list] = []
        #: Sub-unit credits waiting for a whole one, per source. See
        #: :meth:`credit_float`.
        self._credit_banks: dict[str, float] = {}
        self._stamp_text = ""
        self._stamp_remaining = 0.0

        self._card_text = ""
        self._card_hint = ""
        self._card_verb = ""
        self._card_progress: float | None = None

        self._interact_fraction = 0.0
        self._interact_remaining = 0.0

        self._affordance_text = ""
        self._affordance_remaining = 0.0

        self._controls_bar_text = CONTROLS_BAR_TEXT
        self._controls_bar_second_row = CONTROLS_BAR_SECOND_ROW
        self._controls_bar_visible = True

        self._warp_status = ""
        self._warp_status_blocked = False

        self._elapsed = 0.0
        self._rescan_in = 0.0
        self._ammo_poll_in = AMMO_POLL_S
        # Which signals each emitter is already wired for. Keyed weakly and by
        # the node itself rather than by ``id()``: enemies and hunters are
        # freed mid-run, and a recycled address would otherwise look like an
        # emitter the HUD had already connected to.
        self._connected: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
        self._connected_names: set[str] = set()
        self._ship = None
        self._rig: CameraRig | None = None
        #: The developer frame readout: off until :data:`DEBUG_FRAME_STATS_ACTION`,
        #: then a rolling window of wall-clock frame times and whatever per-pass
        #: GPU timings the driver is publishing.
        self._frame_stats = False
        self._frame_times: list[float] = []
        self._gpu_phases: tuple[tuple[str, float], ...] = ()
        #: The inbound hunter, while one is inbound. Looked up from the hunter
        #: group rather than injected, and only while the meter is locked, so a
        #: run with no hunter in it pays nothing for the lookup.
        self._hunter = None

    # ------------------------------------------------------------------ setup

    def on_ready(self):
        self.anchor = Anchor.FULL_RECT
        self._refresh_screen_scale()
        tree = self.tree
        if tree is not None:
            tree.screen_resized.connect(self._on_screen_resized)
        self._connect_sources()

    def on_exit_tree(self):
        tree = self.tree
        if tree is not None:
            tree.screen_resized.disconnect(self._on_screen_resized)

    # --------------------------------------------------------------- scaling

    @property
    def ui_scale(self) -> float:
        """The player's UI-scale slider. The window's height scales on top."""
        return self._settings_scale

    @ui_scale.setter
    def ui_scale(self, value: float) -> None:
        self._settings_scale = max(0.0, float(value))

    @property
    def screen_scale(self) -> float:
        """The height-derived half of the scale, from :func:`screen_scale_for`."""
        return self._screen_scale

    @property
    def effective_scale(self) -> float:
        """What the HUD actually draws at: window height times the slider."""
        return self._screen_scale * self._settings_scale

    def _on_screen_resized(self, size) -> None:
        del size
        self._refresh_screen_scale()

    def _refresh_screen_scale(self) -> None:
        """Re-derive the height half of the UI scale from the live window."""
        tree = self.tree
        if tree is None:
            return
        self._screen_scale = screen_scale_for(float(tree.screen_size[1]))

    # ------------------------------------------------------- public interface

    def flash_stamp(self, text: str) -> None:
        """Stamp *text* across the centre of the screen for a beat."""
        self._stamp_text = str(text)
        self._stamp_remaining = STAMP_HOLD_S + STAMP_FADE_S

    def show_interact_fill(self, fraction: float) -> None:
        """Draw the interact hold as a radial fill on the ship.

        Push this every frame the button is held; it clears shortly after the
        pushes stop. A *fraction* of zero or less clears it at once.
        """
        fraction = float(fraction)
        if fraction <= 0.0:
            self._interact_fraction = 0.0
            self._interact_remaining = 0.0
            return
        self._interact_fraction = _clamp01(fraction)
        self._interact_remaining = INTERACT_FILL_HOLD_S

    def set_affordance(self, text: str) -> None:
        """Name the verb currently in reach, or clear the line with ``""``.

        Push this every frame something is in range; it clears itself
        :data:`AFFORDANCE_HOLD_S` after the pushes stop, so a resolver that
        simply stops calling does not leave a stale prompt over empty space.
        The line is one short imperative naming the key and the verb, and only
        ever one: two prompts at once is a menu, and this is a reticle.
        """
        text = str(text)
        if not text:
            self._affordance_text = ""
            self._affordance_remaining = 0.0
            return
        self._affordance_text = text
        self._affordance_remaining = AFFORDANCE_HOLD_S

    @property
    def affordance(self) -> str:
        """The verb line currently up, empty when nothing is in reach."""
        return self._affordance_text if self._affordance_remaining > 0.0 else ""

    def set_controls_bar(self, text: str, second_row: str | None = None) -> None:
        """Replace the persistent controls strip along the bottom edge.

        *second_row* replaces the strip's lower row; left out, the row already
        there is kept, so a caller rewriting the primary verbs does not have to
        restate the whole keyboard to hold on to the rest of it.
        """
        self._controls_bar_text = str(text)
        if second_row is not None:
            self._controls_bar_second_row = str(second_row)

    @property
    def controls_bar(self) -> str:
        """The strip's first row as it is drawn, empty while it is hidden."""
        return self._controls_bar_text if self._controls_bar_visible else ""

    @property
    def controls_bar_second_row(self) -> str:
        """The strip's second row as it is drawn, empty while it is hidden."""
        return self._controls_bar_second_row if self._controls_bar_visible else ""

    @property
    def controls_bar_visible(self) -> bool:
        """Whether the bar is showing. On by default, for every run."""
        return self._controls_bar_visible

    @controls_bar_visible.setter
    def controls_bar_visible(self, value: bool) -> None:
        self._controls_bar_visible = bool(value)

    def toggle_controls_bar(self) -> bool:
        """Flip the bar and return its new state."""
        self._controls_bar_visible = not self._controls_bar_visible
        return self._controls_bar_visible

    # ------------------------------------------------- the developer readout

    def toggle_frame_stats(self) -> bool:
        """Flip the developer frame readout and return its new state."""
        self._frame_stats = not self._frame_stats
        if not self._frame_stats:
            self._frame_times.clear()
            self._gpu_phases = ()
        return self._frame_stats

    @property
    def frame_stats_visible(self) -> bool:
        return self._frame_stats

    def frame_stats_lines(self) -> tuple[str, ...]:
        """What the readout is saying: the CPU window, then the hottest passes.

        A tuple rather than a drawing, so a test can assert on the numbers and
        so the same lines can be printed to a terminal from a headless probe.
        """
        if not self._frame_times:
            return ()
        mean = sum(self._frame_times) / len(self._frame_times)
        worst = max(self._frame_times)
        fps = 1.0 / mean if mean > 0.0 else 0.0
        lines = [
            f"FRAME {mean * 1000.0:6.2f} ms  ({fps:5.1f} fps)",
            f"WORST {worst * 1000.0:6.2f} ms  over {len(self._frame_times)} frames",
        ]
        if self._gpu_phases:
            lines.append("GPU PASSES (ms)")
            lines.extend(f"  {name[:22]:<22} {value:6.3f}" for name, value in self._gpu_phases)
        else:
            lines.append("GPU PASSES: no timestamp pool")
        return tuple(lines)

    def _tick_frame_stats(self, dt: float) -> None:
        """Sample the frame clock, and the driver's pass timings where they exist.

        Every access in :func:`_gpu_phase_rows` is guarded, so a backend with no
        timestamp pool prints nothing rather than failing.
        """
        if Input.just_pressed(DEBUG_FRAME_STATS_ACTION):
            self.toggle_frame_stats()
        if not self._frame_stats:
            return
        if dt > 0.0:
            self._frame_times.append(float(dt))
            if len(self._frame_times) > FRAME_STATS_WINDOW:
                del self._frame_times[: len(self._frame_times) - FRAME_STATS_WINDOW]
        self._gpu_phases = _gpu_phase_rows()

    def set_warp_status(self, text: str, *, blocked: bool = False) -> None:
        """Say whether the drive can leave, and at what price.

        Drawn where the spool ring will close, and only while no spool is
        running: once the ring is up it is answering the same question itself.
        *blocked* colours the line as a refusal ("not enough fuel") rather than
        as an offer.
        """
        self._warp_status = str(text)
        self._warp_status_blocked = bool(blocked)

    @property
    def warp_status(self) -> str:
        """The warp chip's line, empty when the drive has nothing to say."""
        return self._warp_status

    def show_subtitle(self, cue: str, *, direction: Vec3 | None = None) -> None:
        """Caption an audio *cue* by its id, through :func:`caption_for`.

        Pass *direction* (the bearing from the ship to the sound) for a spatial
        cue and the caption names the side it came from, the way a caption track
        writes an off-screen sound.
        """
        line = caption_for(cue)
        if direction is not None:
            line = CAPTION_DIRECTION_FORMAT.format(
                caption=line, direction=CAPTION_DIRECTIONS[self._edge_index(direction)]
            )
        self._push_subtitle(line)

    def _push_subtitle(self, line: str) -> None:
        """Add *line* to the caption stack, one line per sound.

        A cue often reaches the track twice, once from the signal the HUD
        consumes itself and once from the audio director's announcement, and
        the two spellings may differ only by a side suffix. Lines are
        de-duplicated on the caption without its suffix, keeping whichever
        spelling names a side, so one klaxon is always one line.
        """
        base = _caption_base(line)
        for entry in self._subtitles:
            if _caption_base(entry[0]) == base:
                if len(line) > len(entry[0]):
                    entry[0] = line
                entry[1] = SUBTITLE_HOLD_S
                return
        self._subtitles.append([line, SUBTITLE_HOLD_S])
        del self._subtitles[:-SUBTITLE_MAX_LINES]

    def show_toast(self, text: str) -> None:
        """Put one short line up, replacing whichever toast was showing.

        The toast is the answer to something the player just did: a key that
        needs a destination first, a depot one jump out. It sits above the
        caption stack in its own type so a combat caption cannot bury it, and
        it goes away on its own after :data:`TOAST_HOLD_S`.

        A note set within :data:`TOAST_NOTE_JOIN_S` survives the replacement and
        is folded into the new line, because a note and a toast that arrive in
        the same frame are two halves of one answer to one key press.
        """
        if self._toast_note_join <= 0.0:
            self._toast_note = ""
        self._toast_text = str(text)
        self._toast_remaining = TOAST_HOLD_S + TOAST_FADE_S

    def set_toast_note(self, text: str) -> None:
        """Add a second clause to the answer line instead of replacing it.

        The tutorial's "what the script wants first" and the run's own refusal
        are both answers to the same press, and they are raised by different
        nodes in an order neither of them controls. If whichever spoke last were
        the whole line, a first-run pilot who pressed the generator key would
        read ``FIRST: FLY: W A S D`` and never learn there was no generator
        fitted. A note joins whatever the line says, in either order, and stands
        alone when nothing else answered.
        """
        text = str(text).strip()
        if not text:
            return
        self._toast_note = text
        self._toast_note_join = TOAST_NOTE_JOIN_S
        if self._toast_remaining <= 0.0:
            self._toast_text = text
            self._toast_remaining = TOAST_HOLD_S + TOAST_FADE_S

    @property
    def toast(self) -> str:
        """The toast currently up, note folded in, empty when none is."""
        if self._toast_remaining <= 0.0:
            return ""
        note = self._toast_note
        if not note or note == self._toast_text or note in self._toast_text:
            return self._toast_text
        return TOAST_WITH_NOTE.format(text=self._toast_text, note=note)

    def float_text(
        self,
        text: str,
        *,
        position: Vec3 | None = None,
        node: Node | None = None,
        hold_s: float = FLOAT_TEXT_HOLD_S,
        colour=COLOUR_FLOAT_TEXT,
        toward: str | None = None,
        plate: bool = False,
    ) -> None:
        """Float *text* up from a point in the world and fade it out.

        Anchor it to a *node* to have the label follow something that moves
        (an enemy wearing its first-sighting tag), or to a fixed *position*
        for something that does not (a pickup's value at the point it was
        scooped). A label with neither anchor is dropped rather than drawn in
        a corner: world text that is not in the world says nothing.

        A label whose credit rounds to zero is dropped rather than drawn (see
        :func:`_credits_nothing`); use :meth:`credit_float` for anything paid in
        fractions, which is every beam and every vent.

        *toward* names a counter from :data:`FLOAT_TARGETS` and makes the label
        fly to it instead of drifting: a credit the pilot can watch land is the
        whole of how a corner readout becomes a consequence. Left as ``None``
        it is inferred from the label's own words, so ``"+12 SCRAP"`` finds the
        scrap counter without the caller having to say so twice; pass ``""`` to
        turn the flight off for a label that credits nothing.

        Set *plate* for a label that has to survive its own effect. Unbacked
        text is fine over the near-black arena and useless inside a flare: the
        Shrike's burn writes its price into the middle of the white cone that
        has just delivered it, and the caption plate is the one treatment on
        this HUD that reads through a flood of light.
        """
        if node is None and position is None:
            return
        if _credits_nothing(text):
            return
        reference = weakref.ref(node) if node is not None else None
        anchor = Vec3(position) if position is not None else None
        hold = max(0.05, float(hold_s))
        target = self._infer_float_target(text) if toward is None else str(toward)
        self._floats.append([str(text), hold, hold, tuple(colour), reference, anchor, target, bool(plate)])
        del self._floats[:-FLOAT_TEXT_MAX]

    def credit_float(
        self,
        source: str,
        amount: float,
        label: str,
        *,
        node: Node | None = None,
        position: Vec3 | None = None,
        colour=COLOUR_FLOAT_TEXT,
        toward: str | None = None,
    ) -> bool:
        """Bank *amount* against *source* and float a label per whole unit earned.

        A mining beam pays a fraction of a unit per frame and a vent pays for as
        long as the ship sits in it, so a label per tick is a column of
        ``+0 SCRAP`` beside a counter that is visibly climbing: the number is
        right and the label calls it a lie. Credits bank per source and
        only the whole part is ever written, so the labels sum to exactly what
        the counter took and not one of them says nothing.

        The remainder is carried, never dropped, which is what makes ten ticks
        of a tenth of a unit one honest ``+1``. Returns True when a label went up.
        """
        bank = self._credit_banks.get(source, 0.0) + max(0.0, float(amount))
        whole = math.floor(bank)
        self._credit_banks[source] = bank - whole
        if whole < 1.0:
            return False
        self.float_text(
            CREDIT_FLOAT_FORMAT.format(amount=whole, label=label),
            node=node,
            position=position,
            colour=colour,
            toward=toward,
        )
        return True

    def credit_bank(self, source: str) -> float:
        """The fraction of a unit *source* is carrying toward its next label."""
        return self._credit_banks.get(source, 0.0)

    @staticmethod
    def _infer_float_target(text: str) -> str:
        """The counter a label credits, read off the label, or ``""``."""
        for word in str(text).lower().replace(",", " ").split():
            if word in FLOAT_TARGETS:
                return word
        return ""

    @property
    def float_texts(self) -> tuple[str, ...]:
        """The world-anchored labels currently alive, oldest first."""
        return tuple(entry[0] for entry in self._floats)

    def set_depot_beacon(self, position: Vec3 | None, label: str = "DEPOT") -> None:
        """Mark *position* with an edge beacon and a live range, or clear it.

        The sector's depot is the only thing a scrap hold can be spent on, so
        it gets the one persistent world marker the HUD draws. Pass ``None``
        for a sector that has no depot.
        """
        self._beacon_position = Vec3(position) if position is not None else None
        self._beacon_label = str(label)

    @property
    def depot_beacon(self) -> Vec3 | None:
        """Where the beacon is pointing, or None when there is nothing to mark."""
        return self._beacon_position

    @property
    def beacon_range(self) -> float:
        """Plane distance from the hull to the beacon, ``inf`` when there is none."""
        target = self._beacon_position
        ship = self._ship
        if target is None or ship is None:
            return float("inf")
        offset = Vec3(target) - Vec3(ship.world_position)
        return math.hypot(float(offset.x), float(offset.z))

    @property
    def beacon_in_range(self) -> bool:
        """Whether the hull is inside the bay the beacon marks.

        Readable state, because it is what the ring's own look is driven off:
        a marker that changes when the ship crosses a line the pilot cannot see
        is the only thing on the screen that says the line is there.
        """
        return self.beacon_range <= DOCK_PROMPT_RANGE_UNITS

    @property
    def dock_prompt(self) -> str:
        """The verb written on the ring, or ``""`` when the hull is not in the bay.

        The run's own affordance whenever it is talking about the dock, so
        "DOCKED: hold F to sell" reaches the ring the same way "F: DOCK" does,
        and the fixed prompt otherwise: a pilot inside a bay that says nothing
        is a pilot who flies back out of it.
        """
        if not self.beacon_in_range:
            return ""
        affordance = self.affordance
        if affordance and DOCK_PROMPT_KEYWORD in affordance.upper():
            return affordance
        return DOCK_PROMPT

    def set_boundary_notice(self, text: str) -> None:
        """Say that the ship is outside the sector, for as long as it is.

        Pushed every frame by whoever owns the boundary and cleared
        :data:`BOUNDARY_NOTICE_HOLD_S` after the pushes stop, so turning back
        takes the line down without anyone having to remember to.
        """
        text = str(text)
        if not text:
            self._boundary_notice = ""
            self._boundary_remaining = 0.0
            return
        self._boundary_notice = text
        self._boundary_remaining = BOUNDARY_NOTICE_HOLD_S

    @property
    def boundary_notice(self) -> str:
        """The standing boundary line, empty when the ship is inside."""
        return self._boundary_notice if self._boundary_remaining > 0.0 else ""

    def set_objective(self, text: str) -> None:
        """Set the standing line saying what the run wants of this sector.

        A standing line, not a toast: it stays up until the next call replaces
        it or ``""`` clears it, because "what am I here for" is a question a
        pilot asks minutes after the answer was first given. It shares the
        objective band with the lock's instruction, which outranks it: once the
        Shrike is inbound there is only one objective.
        """
        self._objective = str(text)

    @property
    def objective(self) -> str:
        """The standing objective line, empty when nothing has been asked."""
        return self._objective

    def set_compass_targets(self, targets) -> None:
        """Offer the screen-edge compass the things worth flying to.

        *targets* is a sequence of ``(world_position, kind)`` with kinds from
        :data:`COMPASS_LABELS`. The HUD decides whether to draw them, because
        only it knows what is on screen: markers appear exactly when none of
        them is visible, which is the moment the sector looks empty.
        """
        self._compass = tuple((Vec3(position), str(kind)) for position, kind in targets)
        self._compass_remaining = COMPASS_HOLD_S if self._compass else 0.0

    @property
    def compass_targets(self) -> tuple[tuple[Vec3, str], ...]:
        """The targets the compass is currently holding, empty when none is."""
        return self._compass if self._compass_remaining > 0.0 else ()

    def set_warp_target(self, name: str, fuel: float = 0.0, *, price_text: str = "") -> None:
        """Name the destination the running spool is buying, and its price.

        The ring is a countdown either way; this is what turns it into a
        decision the pilot can read. Clearing the name (empty *name*) leaves
        the ring unlabelled, which is what an unattributed spool deserves.

        *price_text* is the caller's own spelling of the price, for a caller
        that has already itemised it ("22 (15 +7 HUNTED)"). Without it the
        ring spells *fuel* as a bare number, which is right for a caller that
        only has one. The two must not disagree: a ring quoting a total beside
        a status chip quoting the itemisation reads as two separate charges,
        so anything that itemises anywhere itemises here too.
        """
        self._warp_target = str(name)
        self._warp_fuel = max(0.0, float(fuel))
        self._warp_price_text = str(price_text)

    @property
    def warp_target(self) -> str:
        """The destination the spool is labelled with, empty when unlabelled."""
        return self._warp_target

    @property
    def warp_price(self) -> str:
        """The price the ring is quoting, as the ring spells it.

        Empty while the spool has no destination or no price, so a caller can
        tell "free" from "unpriced" without re-deriving either.
        """
        if not self._warp_target:
            return ""
        if self._warp_price_text:
            return self._warp_price_text
        return f"{self._warp_fuel:.0f}" if self._warp_fuel > 0.0 else ""

    def fail_warp_spool(self, reason: str) -> None:
        """Say why a channel could not finish, on the ring and on the toast.

        The ship calls this after standing the drive down, so the red flash
        already up gains the reason that caused it. An abort the pilot asked
        for keeps the plain :data:`WARP_ABORTED_LABEL`; this is for the two
        endings they did not choose.
        """
        reason = str(reason)
        if not reason:
            return
        self._warp_outcome_text = reason
        self._warp_outcome_remaining = WARP_OUTCOME_FLASH_S
        self.show_toast(reason)

    @property
    def warp_outcome_text(self) -> str:
        """The ending currently flashing on the ring, empty between spools."""
        return self._warp_outcome_text if self._warp_outcome_remaining > 0.0 else ""

    @property
    def warp_jump_flash(self) -> float:
        """Seconds of white-out left from the last jump, 0 when none is running."""
        return self._warp_jump_flash

    def _flash_warp_outcome(self, text: str) -> None:
        """Hold the ring for a beat on *text*, at the radius it had reached."""
        self._warp_outcome_fraction = self.warp_spool_fraction
        self._warp_outcome_text = str(text)
        self._warp_outcome_remaining = WARP_OUTCOME_FLASH_S

    def end_warp_spool(self) -> None:
        """Take the spool ring down for a channel that ended without a jump.

        ``WARP_COMPLETED`` and ``WARP_SPOOL_CANCELLED`` both land here on their
        own; this is the direct entry for a refuser that stands the drive down
        before the ring has anything to answer to. It clears the ring and not
        the ending flashing on it: those are two different sentences, and the
        second one is the one the pilot needed.
        """
        self._warp_active = False
        self._warp_elapsed = 0.0
        self._warp_stutter = 0.0
        self._warp_target = ""
        self._warp_fuel = 0.0
        self._warp_price_text = ""
        self._warp_interrupt_remaining = 0.0

    @property
    def low_hull(self) -> bool:
        """Whether the hull is under :data:`LOW_HULL_FRACTION`."""
        return self._gauges[HudElements.HULL] < LOW_HULL_FRACTION

    @property
    def low_o2(self) -> bool:
        """Whether the air is under ``balance.O2_LOW_WARNING_SECONDS``."""
        return self._o2_seconds <= balance.O2_LOW_WARNING_SECONDS

    @property
    def low_fuel(self) -> bool:
        """Whether the tank covers :data:`LOW_FUEL_JUMPS` ordinary jumps or fewer.

        Counted in jumps rather than in units, the way the bay counts them:
        what decides this is how many more times the drive will fire, and a
        full tank on a short-ranged hull is still a short range. A HUD that
        has not been told the fuel yet is not low on it, so the count starts
        at infinity and the first ``FUEL_CHANGED`` writes the truth.
        """
        return self._fuel_jumps <= LOW_FUEL_JUMPS

    def show_control_card(self, text: str, *, verb: str = "", hint: str = "", progress: float | None = None) -> None:
        """Put one control card up, replacing whichever card was showing.

        *text* is the line that names the keys and *hint* an optional smaller
        line under it. *verb* is bookkeeping for the caller: it records what
        this card is waiting for, and the HUD hands it back on
        :attr:`control_card_verb` so a schedule can ask what is on screen
        without keeping a second copy of it. The card never expires on its own;
        it is a lesson, not a caption.

        *progress* fills a drawn bar across the foot of the card, from 0 to 1,
        and ``None`` leaves the card without one. A hold that reports itself as
        ``[####....]`` in the hint tells the pilot the game is printing debug
        text at them; a bar is what a hold looks like. A hint that carries a
        typed bar is read for its fraction and stripped, so a caller that does
        not pass the argument still gets the drawn version.
        """
        hint = str(hint)
        if progress is None:
            progress, hint = _read_typed_bar(hint)
        self._card_text = str(text)
        self._card_hint = hint
        self._card_verb = str(verb)
        self._card_progress = None if progress is None else _clamp01(float(progress))

    def clear_control_card(self) -> None:
        """Take the control card down."""
        self._card_text = ""
        self._card_hint = ""
        self._card_verb = ""
        self._card_progress = None

    @property
    def control_card_progress(self) -> float | None:
        """The card's hold fraction, or None when the card has no bar."""
        return self._card_progress

    @property
    def control_card(self) -> str:
        """The card currently up, empty when none is."""
        return self._card_text

    @property
    def control_card_hint(self) -> str:
        """The card's second line, empty when it has none."""
        return self._card_hint

    @property
    def control_card_verb(self) -> str:
        """What the card on screen is waiting for, empty when none is up."""
        return self._card_verb

    # ------------------------------------------------------------ the sector

    def reset_for_sector(self) -> None:
        """Wipe everything the last sector was still saying.

        Every transient on the glass is timed rather than scoped, so without
        this a jump would carry the old sector's whole answer layer across:
        its stamp, its answer line, its captions, its floating credits, the
        edges reddened by a blow taken light-years away, a boundary notice
        for an edge that no longer exists, the ending flashed on a ring that
        has already fired, and a half-finished interact fill. None of them
        outlive the place they were raised in, so the arrival clears them all
        at once rather than each of them separately deciding it should.

        Not cleared: :attr:`warp_jump_flash`, which is this jump's own
        white-out and the thing covering the camera cut, and the standing
        readings, which belong to the ship rather than to the sector. The
        caller announces the new sector *after* this, so the arrival card and
        the new objective are raised onto clean glass.
        """
        self._stamp_text = ""
        self._stamp_remaining = 0.0
        self._toast_text = ""
        self._toast_remaining = 0.0
        self._toast_note = ""
        self._toast_note_join = 0.0
        self._subtitles.clear()
        self._floats.clear()
        for edge in self._edge_damage:
            self._edge_damage[edge] = 0.0
        self._boundary_notice = ""
        self._boundary_remaining = 0.0
        self._warp_outcome_text = ""
        self._warp_outcome_remaining = 0.0
        self._warp_outcome_fraction = 0.0
        self._warp_interrupt_text = ""
        self._warp_interrupt_remaining = 0.0
        self._interact_fraction = 0.0
        self._interact_remaining = 0.0
        self.clear_control_card()

    def set_sector_name(self, name: str) -> None:
        """Name the place the ship is in. Stands until the next sector."""
        self._sector_name = str(name)

    @property
    def sector_name(self) -> str:
        """The standing sector name, empty when none has been set."""
        return self._sector_name

    def show_arrival_card(self, name: str, flavour: str = "") -> None:
        """Announce an arrival: the name of the place and one line about it.

        Held for :data:`ARRIVAL_CARD_HOLD_S` and then gone, which is why the
        name is also latched onto :meth:`set_sector_name`: a title card
        answers "where am I" once, and the corner answers it for the rest of
        the sector. Without a name, a jump lands the ship in a field of rocks
        indistinguishable from the last one, and nothing about a warp reads as
        travel.
        """
        self._arrival_name = str(name)
        self._arrival_flavour = str(flavour)
        self._arrival_remaining = ARRIVAL_CARD_HOLD_S if self._arrival_name else 0.0
        if self._arrival_name:
            self.set_sector_name(self._arrival_name)

    @property
    def arrival_card(self) -> str:
        """The arrival card's headline while it is up, else empty."""
        return self._arrival_name if self._arrival_remaining > 0.0 else ""

    @property
    def arrival_flavour(self) -> str:
        """The arrival card's second line while it is up, else empty."""
        return self._arrival_flavour if self._arrival_remaining > 0.0 else ""

    # --------------------------------------------------------- ship readings

    def resource_lines(self) -> tuple[str, ...]:
        """The resource strip's cells, in the order they are drawn.

        One cell per resource the run can charge or credit and that this HUD
        is drawing. The pause overlay prints the same tuple, so the numbers
        the pilot reads mid-flight and the numbers on the paused panel can
        never be two different readings of the same tanks.
        """
        return tuple(text for text, _colour in self._resource_cells())

    @property
    def ammo_total(self) -> int:
        """Rounds aboard: every magazine plus every stowed box, or 0 for none."""
        return sum(self._ammo.values())

    def _resource_cells(self) -> list[tuple[str, tuple[float, float, float, float]]]:
        """The strip's cells as ``(text, colour)``, empty when it is subtracted."""
        if not self.is_element_visible(HudElements.RESOURCES):
            return []
        cells = [
            (f"{label} {self._levels[element]:.0f}", _opaque(colour))
            for element, label, colour in RESOURCE_CELLS
            if self.is_element_visible(element)
        ]
        if self._ammo and self.is_element_visible(HudElements.AMMO):
            cells.append((AMMO_CELL.format(rounds=self.ammo_total), _opaque(COLOUR_AMMO)))
        return cells

    def state_pips(self) -> tuple[tuple[str, bool], ...]:
        """The power-state pips as ``(text, lit)``, in the order they are drawn.

        Wings and generator always have a pip, lit or not: a key whose only
        output is a lamp that is off still answered the press. The afterburner
        pip is only there while it burns, because thrust is its own answer.
        """
        if not self.is_element_visible(HudElements.STATE_PIPS):
            return ()
        wings_out = self._wings_state in ("deployed", "deploying")
        running = self._generator_running
        burning = self._afterburner
        return (
            (PIP_WINGS[0] if wings_out else PIP_WINGS[1], wings_out),
            (PIP_GENERATOR[0] if running else PIP_GENERATOR[1], running),
            (PIP_AFTERBURNER[0] if burning else PIP_AFTERBURNER[1], burning),
        )

    @property
    def shield_bearing(self) -> float | None:
        """Screen angle of the shield arc's centre in degrees, or None.

        Screen angles run clockwise from +X because screen Y points down, and
        the flight plane maps straight onto the screen axes, so a world heading
        is its own screen angle negated.
        """
        shield = getattr(self._ship, "shield", None)
        if shield is None or not self.is_element_visible(HudElements.SHIELD):
            return None
        return -math.degrees(float(shield.absolute_centre()))

    def set_visible_elements(self, elements) -> None:
        """Restrict the HUD to *elements* (ids from :class:`HudElements`).

        Onboarding calls this once per run; passing :data:`ALL_HUD_ELEMENTS`
        restores the full display.
        """
        unknown = set(elements) - ALL_HUD_ELEMENTS
        if unknown:
            raise ValueError(f"unknown HUD element ids: {sorted(unknown)}")
        self._visible_elements = frozenset(elements)

    def is_element_visible(self, element: str) -> bool:
        """Whether *element* is currently drawn."""
        return element in self._visible_elements

    @property
    def visible_elements(self) -> frozenset[str]:
        """The element ids this HUD is currently drawing."""
        return self._visible_elements

    def edge_desaturation(self) -> dict[str, float]:
        """Per-edge desaturation weights in 0..1, for the post-process hook.

        Keys are ``"left"``, ``"right"``, ``"top"`` and ``"bottom"``. A hit
        raises the edge nearest its bearing and the value decays over
        :data:`DAMAGE_EDGE_DECAY_S`.
        """
        return dict(self._edge_damage)

    # Read-only state, for tests and for anything that mirrors the HUD.

    @property
    def hull_fraction(self) -> float:
        return self._gauges[HudElements.HULL]

    @property
    def hull_chip(self) -> float:
        """Where the draining damage chunk still reaches on the hull arc.

        Above :attr:`hull_fraction` while a just-lost chunk is animating off
        the ring, equal to it once the arc has settled.
        """
        return max(self._hull_chip, self._gauges[HudElements.HULL])

    @property
    def capacitor_fraction(self) -> float:
        return self._gauges[HudElements.CAPACITOR]

    @property
    def capacitor_blacked_out(self) -> bool:
        """True while a lantern blackout is holding the power bus at zero.

        Read off the power system's own state, so the PWR arc greys for the
        held second rather than drawing a live gauge that happens to be empty.
        """
        power = self.tree.singletons.get(Services.POWER) if self.tree is not None else None
        return bool(getattr(power, "blacked_out", False))

    @property
    def o2_fraction(self) -> float:
        return self._gauges[HudElements.O2]

    @property
    def fuel_fraction(self) -> float:
        return self._gauges[HudElements.FUEL]

    @property
    def signature_fraction(self) -> float:
        """Signature as a fraction of :data:`balance.SIGNATURE_MAX`."""
        return _fraction(self._signature, balance.SIGNATURE_MAX)

    @property
    def signature_value(self) -> float:
        """The meter's own reading, in the units the gauge writes."""
        return self._signature

    @property
    def signature_locked(self) -> bool:
        """Whether an arrival the meter bought is still inbound."""
        return self._signature_locked

    @property
    def hunter_countdown(self) -> float:
        """Seconds until the tear-in, or 0 when nothing is inbound."""
        approach = self._hunter_approach()
        return approach[0] if approach is not None else 0.0

    def _hunter_approach(self) -> tuple[float, float] | None:
        """The inbound hunter's ``(seconds, bearing)``, or None when none is.

        The hunter does not exist until the meter locks and is freed when it
        leaves, so this refreshes the reference from the hunter group rather
        than holding one. It is only ever called while the lock is up.
        """
        hunter = self._hunter
        approach = getattr(hunter, "approach", None) if hunter is not None else None
        if approach is not None:
            return approach
        tree = self.tree
        if tree is None:
            return None
        for node in tree.group(Groups.HUNTER):
            approach = getattr(node, "approach", None)
            if approach is not None:
                self._hunter = node
                return approach
        self._hunter = None
        return None

    @property
    def warp_spooling(self) -> bool:
        """Whether the ring is up, whether or not it has closed any distance."""
        return self._warp_active

    @property
    def warp_spool_fraction(self) -> float:
        """How far the spool ring has closed, 0 when no spool is running."""
        if not self._warp_active:
            return 0.0
        return _fraction(self._warp_elapsed, self._warp_total)

    @property
    def warp_stutter(self) -> float:
        """Decaying 0..1 stutter weight, raised by every spool interruption."""
        return self._warp_stutter

    @property
    def subtitles(self) -> tuple[str, ...]:
        """The captions currently on screen, oldest first."""
        return tuple(entry[0] for entry in self._subtitles)

    @property
    def stamp_text(self) -> str:
        """The stamp currently on screen, empty when none is."""
        return self._stamp_text if self._stamp_remaining > 0.0 else ""

    @property
    def interact_fraction(self) -> float:
        """The interact hold fill, 0 when nothing is being held."""
        return self._interact_fraction

    # ------------------------------------------------------------ per-frame

    def on_update(self, dt: float):
        self._elapsed += dt
        self._tick_frame_stats(dt)

        for entry in self._subtitles:
            entry[1] -= dt
        self._subtitles = [entry for entry in self._subtitles if entry[1] > 0.0]

        for entry in self._floats:
            entry[1] -= dt
        self._floats = [entry for entry in self._floats if entry[1] > 0.0]

        if self._toast_note_join > 0.0:
            self._toast_note_join = max(0.0, self._toast_note_join - dt)
        if self._toast_remaining > 0.0:
            self._toast_remaining = max(0.0, self._toast_remaining - dt)
            if self._toast_remaining <= 0.0:
                self._toast_note = ""

        if self._stamp_remaining > 0.0:
            self._stamp_remaining = max(0.0, self._stamp_remaining - dt)

        if self._arrival_remaining > 0.0:
            self._arrival_remaining = max(0.0, self._arrival_remaining - dt)

        self._tick_low_hull(dt)

        if self._interact_remaining > 0.0:
            self._interact_remaining -= dt
            if self._interact_remaining <= 0.0:
                self._interact_fraction = 0.0

        if self._affordance_remaining > 0.0:
            self._affordance_remaining -= dt
            if self._affordance_remaining <= 0.0:
                self._affordance_text = ""

        if self._boundary_remaining > 0.0:
            self._boundary_remaining -= dt
            if self._boundary_remaining <= 0.0:
                self._boundary_notice = ""

        if self._compass_remaining > 0.0:
            self._compass_remaining -= dt
            if self._compass_remaining <= 0.0:
                self._compass = ()

        if self._warp_outcome_remaining > 0.0:
            self._warp_outcome_remaining = max(0.0, self._warp_outcome_remaining - dt)
            if self._warp_outcome_remaining <= 0.0:
                self._warp_outcome_text = ""

        if self._warp_jump_flash > 0.0:
            self._warp_jump_flash = max(0.0, self._warp_jump_flash - dt)

        if self._warp_active:
            self._warp_elapsed += dt
        if self._warp_stutter > 0.0:
            self._warp_stutter = max(0.0, self._warp_stutter - dt / WARP_STUTTER_S)
        if self._warp_interrupt_remaining > 0.0:
            self._warp_interrupt_remaining = max(0.0, self._warp_interrupt_remaining - dt)

        if any(self._edge_damage.values()):
            decay = dt / DAMAGE_EDGE_DECAY_S
            for edge in _EDGES:
                self._edge_damage[edge] = max(0.0, self._edge_damage[edge] - decay)

        if self._hull_chip > self._gauges[HudElements.HULL]:
            if self._hull_chip_hold > 0.0:
                self._hull_chip_hold = max(0.0, self._hull_chip_hold - dt)
            else:
                rate = self._hull_chip_rate or (1.0 / HULL_CHIP_DECAY_S)
                self._hull_chip = max(self._gauges[HudElements.HULL], self._hull_chip - rate * dt)

        if self._connected_names != _WANTED_SIGNALS:
            self._rescan_in -= dt
            if self._rescan_in <= 0.0:
                self._connect_sources()

        # A refit changes what is aboard without firing a shot, so the
        # magazines are re-read on a slow poll rather than only on the signal.
        self._ammo_poll_in -= dt
        if self._ammo_poll_in <= 0.0:
            self._ammo_poll_in = AMMO_POLL_S
            self._poll_ammo()

    def _tick_low_hull(self, dt: float) -> None:
        """Keep the klaxon coming back while the hull is in the red.

        A single caption at the moment the hull crossed the line is a warning
        the player can miss under fire, so the low-hull state re-raises it
        every :data:`LOW_HULL_KLAXON_S` for as long as it holds. Climbing back
        out of the red arms it again, which is the only way a repair reads.
        """
        low = self.low_hull
        if not low:
            self._low_hull = False
            self._low_hull_klaxon_in = 0.0
            return
        if not self._low_hull:
            self._low_hull = True
            self._low_hull_klaxon_in = LOW_HULL_KLAXON_S
            self.show_subtitle("klaxon")
            return
        self._low_hull_klaxon_in -= dt
        if self._low_hull_klaxon_in <= 0.0:
            self._low_hull_klaxon_in = LOW_HULL_KLAXON_S
            self.show_subtitle("klaxon")

    # ------------------------------------------------------------- discovery

    def _scan_roots(self) -> list[Node]:
        tree = self.tree
        if tree is None:
            return []
        roots: list[Node] = [node for node in tree.singletons.values() if node is not self]
        for group in (Groups.SHIP, Groups.HUNTER, Groups.DEPOTS):
            roots.extend(tree.group(group))
        return roots

    def _connect_sources(self) -> None:
        """Connect to every wanted signal that now has an emitter.

        Modules mount in whatever order the run scene builds them, and the
        hunter does not exist until the signature locks, so this runs again
        every :data:`SOURCE_RESCAN_S` until nothing is missing.
        """
        self._rescan_in = SOURCE_RESCAN_S
        seen: set[int] = set()
        for root in self._scan_roots():
            self._connect_subtree(root, seen)
        ships = self.tree.group(Groups.SHIP) if self.tree is not None else []
        self._ship = ships[0] if ships else None
        if self._rig is None and self.tree is not None and self.tree.root is not None:
            self._rig = self.tree.root.find(CameraRig)
        self._seed_readings()

    def _seed_readings(self) -> None:
        """Read the tanks and the hold once, rather than waiting for a change.

        Every gauge here is fed by a change signal, and a full tank that has
        not changed yet emits nothing: unseeded, the strip would open every run
        reading ``FUEL 0`` beside a tank with a hundred in it until the first
        burn.
        """
        singletons = self.tree.singletons if self.tree is not None else {}
        power = singletons.get(Services.POWER)
        for current, maximum, handler in (
            ("o2", "o2_max", self._on_o2_changed),
            ("fuel", "fuel_max", self._on_fuel_changed),
            ("capacitor", "capacitor_max", self._on_capacitor_changed),
        ):
            value = getattr(power, current, None)
            ceiling = getattr(power, maximum, None)
            if value is not None and ceiling is not None:
                handler(float(value), float(ceiling))
        hull = getattr(self._ship, "hull", None)
        hull_max = getattr(self._ship, "hull_max", None)
        if hull is not None and hull_max is not None:
            self._on_hull_changed(float(hull), float(hull_max))
        scrap = getattr(singletons.get(Services.ECONOMY), "scrap", None)
        if scrap is not None:
            self._on_scrap_changed(float(scrap))
        self._poll_ammo()
        for node in self._emitters_of(self._ship, SignalNames.SOLAR_STATE_CHANGED):
            self._on_solar_state_changed(getattr(node, "state", ""))
        for node in self._emitters_of(self._ship, SignalNames.GENERATOR_CHANGED):
            self._on_generator_changed(getattr(node, "running", False))

    def _poll_ammo(self) -> None:
        """Read the hull's magazines and its stowed boxes into the strip.

        ``AMMO_CHANGED`` fires when a magazine moves, which never happens for a
        gun that has been bought and not yet fired, so a refit would otherwise
        leave the readout empty beside a loaded weapon. The magazines are read
        off the hardpoints instead and the signal keeps the number live between
        polls. A hull with no ballistic weapon and no box reads nothing at all:
        the cell exists only once there is ammunition to spend.
        """
        rounds: dict[str, int] = {}
        for node in self._magazines(self._ship):
            rounds[str(node.weapon_id)] = int(node.rounds)
        racks = [
            rack for rack in self._emitters_of(self._ship, SignalNames.AMMO_CHANGED) if hasattr(rack, "ammo_boxes")
        ]
        for rack in racks:
            for weapon_id in list(rounds):
                rounds[weapon_id] += int(rack.ammo_boxes(weapon_id)) * int(balance.AMMO_BOX_ROUNDS)
        # A rack that can be read is the authority, empty answer included: that
        # is how a weapon sold at a depot takes its count off the strip.
        if racks or rounds:
            self._ammo = rounds

    @staticmethod
    def _magazines(root):
        """Every ballistic weapon under *root*: a node with rounds and an id."""
        if root is None:
            return
        stack = [root]
        while stack:
            node = stack.pop()
            if isinstance(getattr(node, "rounds", None), int) and getattr(node, "weapon_id", None):
                yield node
            stack.extend(node.children)

    @staticmethod
    def _emitters_of(root, signal_name: str):
        """Every node under *root* that emits *signal_name*, root included."""
        if root is None:
            return
        stack = [root]
        while stack:
            node = stack.pop()
            if isinstance(getattr(node, signal_name, None), Signal):
                yield node
            stack.extend(node.children)

    def _connect_subtree(self, node: Node, seen: set[int]) -> None:
        if id(node) in seen:
            return
        seen.add(id(node))
        done = self._connected.get(node)
        if done is None:
            done = set()
            self._connected[node] = done
        for name, method in _SIGNAL_HANDLERS.items():
            if name in done:
                continue
            signal = getattr(node, name, None)
            if isinstance(signal, Signal):
                signal.connect(getattr(self, method))
                done.add(name)
                self._connected_names.add(name)
        for child in node.children:
            self._connect_subtree(child, seen)

    # -------------------------------------------------------------- handlers

    def _on_hull_changed(self, current: float, maximum: float) -> None:
        fraction = _fraction(current, maximum)
        previous = self._gauges[HudElements.HULL]
        if fraction < previous:
            # A blow: hold the chunk that was just lost lit, then drain it over
            # a fixed time. Re-arming the hold on a second blow is deliberate:
            # two hits in quick succession are one wound to look at.
            self._hull_chip = max(self._hull_chip, previous)
            self._hull_chip_hold = HULL_CHIP_HOLD_S
            self._hull_chip_rate = max(self._hull_chip - fraction, 1e-6) / HULL_CHIP_DECAY_S
        elif fraction > previous:
            # A repair (or the seed): a rising reading has no chunk to mourn.
            self._hull_chip = fraction
            self._hull_chip_hold = 0.0
            self._hull_chip_rate = 0.0
        # An unchanged reading is a re-announcement, not a repair, and it must
        # leave the chunk alone. The ship re-states its hull a few frames after
        # a blow (the breach bookkeeping does it), and clearing on "not lower"
        # would delete the chunk three frames into an animation authored to
        # last most of a second. On the one hit that matters, the Shrike's
        # lantern, the ring would snap to its new length while the screen was
        # still white, and the arc would read as never having moved at all.
        self._gauges[HudElements.HULL] = fraction
        self._levels[HudElements.HULL] = float(current)

    def _on_breach_opened(self, open_breaches: int) -> None:
        self._open_breaches = int(open_breaches)
        self.show_subtitle("breach")

    def _on_breach_patched(self, open_breaches: int) -> None:
        self._open_breaches = int(open_breaches)

    def _on_capacitor_changed(self, current: float, maximum: float) -> None:
        self._gauges[HudElements.CAPACITOR] = _fraction(current, maximum)
        self._levels[HudElements.CAPACITOR] = float(current)

    def _on_energy_denied(self, consumer: str) -> None:
        del consumer
        self.show_subtitle("energy_denied")

    def _on_o2_changed(self, current: float, maximum: float) -> None:
        self._gauges[HudElements.O2] = _fraction(current, maximum)
        self._levels[HudElements.O2] = float(current)
        drain = balance.O2_DRAIN_PER_S + balance.O2_DRAIN_PER_BREACH_PER_S * self._open_breaches
        self._o2_seconds = float(current) / drain if drain > 0.0 else float("inf")
        if self.low_o2:
            self.show_subtitle("breathing")

    def _on_fuel_changed(self, current: float, maximum: float) -> None:
        self._gauges[HudElements.FUEL] = _fraction(current, maximum)
        self._levels[HudElements.FUEL] = float(current)
        fare = float(balance.WARP_FUEL_BASE)
        self._fuel_jumps = float(current) / fare if fare > 0.0 else float("inf")

    def _on_generator_changed(self, running: bool) -> None:
        self._generator_running = bool(running)
        if running:
            self.show_subtitle("generator_hum")

    def _on_solar_state_changed(self, state: str) -> None:
        self._wings_state = str(state)

    def _on_afterburner_changed(self, active: bool) -> None:
        self._afterburner = bool(active)

    def _on_silent_running_changed(self, active: bool) -> None:
        self._silent_running = bool(active)
        if active:
            self.show_subtitle("silent_running")

    def _on_signature_changed(self, value: float) -> None:
        self._signature = float(value)

    def _on_signature_locked(self) -> None:
        # The stamp is the headline and the objective band carries the answer.
        # A toast as well would be a third copy of one sentence on one screen.
        self._signature_locked = True
        self.flash_stamp(SIGNATURE_LOCKED_STAMP)
        self.show_subtitle("klaxon")

    def _on_ammo_changed(self, weapon_id: str, rounds: int) -> None:
        self._ammo[str(weapon_id)] = int(rounds)

    def _on_scrap_changed(self, total: float) -> None:
        self._levels[HudElements.SCRAP] = float(total)

    def _on_notoriety_changed(self, value: int, reason: str) -> None:
        del reason
        self._notoriety = int(value)

    def _on_player_damaged(self, amount: float, direction: Vec3) -> None:
        edge = _EDGES[self._edge_index(direction)]
        weight = max(DAMAGE_EDGE_MIN_WEIGHT, _clamp01(float(amount) / DAMAGE_EDGE_FULL_HIT))
        self._edge_damage[edge] = max(self._edge_damage[edge], weight)

    def _on_audio_cue(self, cue: str, caption: str) -> None:
        """Caption a cue straight off the audio director's own announcement.

        Every played cue lands here whoever played it, so a system that talks
        to the director directly (the hunter's burn klaxon) reaches the
        caption track without also having to know the HUD. The wording is
        audio's, side suffix included; :meth:`_push_subtitle` folds it with
        any caption the HUD raised for the same sound from a signal.
        """
        del cue
        self._push_subtitle(str(caption))

    def _on_enemy_killed(self, archetype: str, position: Vec3, elite: bool) -> None:
        del archetype, position, elite
        self.show_subtitle("kill_chime")

    def _on_wave_spawned(self, count: int) -> None:
        del count
        self.show_subtitle("spawn_chevron")

    def _on_hunter_telegraph(self, stage: str) -> None:
        if stage == "t60":
            self.show_subtitle("groan")
        elif stage == "t30":
            self.show_subtitle("klaxon")
        elif stage == "t0":
            # The countdown has run out and the beast is on screen: the
            # instruction it was carrying has been overtaken by events.
            self._signature_locked = False
            self.flash_stamp("ARRIVAL")

    def _on_warp_spool_started(self, emergency: bool) -> None:
        del emergency
        self._warp_active = True
        self._warp_elapsed = 0.0
        self._warp_total = balance.WARP_SPOOL_S
        self._warp_stutter = 0.0
        self._warp_target = ""
        self._warp_fuel = 0.0
        self._warp_price_text = ""
        self._warp_interrupt_remaining = 0.0

    def _on_warp_spool_interrupted(self, added_seconds: float) -> None:
        added = float(added_seconds)
        self._warp_total += added
        self._warp_stutter = 1.0
        # Named cost and named cause: "INTERRUPTED" alone teaches nothing, and
        # the one thing the pilot needs is that being shot is what lengthens it.
        self._warp_interrupt_text = f"{WARP_INTERRUPT_PREFIX} +{added:.1f} s ({WARP_INTERRUPT_CAUSE})"
        self._warp_interrupt_remaining = WARP_INTERRUPT_FLASH_S
        self.show_subtitle("spool_stutter")

    def _on_warp_spool_cancelled(self) -> None:
        self._flash_warp_outcome(WARP_ABORTED_LABEL)
        self.end_warp_spool()

    def _on_warp_completed(self, emergency: bool) -> None:
        del emergency
        self._warp_jump_flash = WARP_JUMP_FLASH_S
        # Leaving is one of the two answers the lock's instruction offers, so
        # arriving somewhere else is the moment it stops being true.
        self._signature_locked = False
        self._hunter = None
        self.end_warp_spool()

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

    @staticmethod
    def _edge_index(direction: Vec3) -> int:
        """Screen edge nearest *direction*, as an index into :data:`_EDGES`.

        *direction* is the bearing from the ship toward the threat, the same
        convention ``ShieldArc.covers`` takes. On screen +X is right and -Z is
        up, so the plane components map straight onto screen axes.
        """
        dx = float(direction.x)
        dy = float(direction.z)  # world +Z is screen down
        if abs(dx) >= abs(dy):
            return 1 if dx > 0.0 else 0  # right / left
        return 2 if dy < 0.0 else 3  # top / bottom

    def _project(self, world: Vec3, rect: tuple[float, float, float, float]) -> tuple[float, float] | None:
        """Where *world* lands on screen, or None when it is behind the camera."""
        x, y, w, h = rect
        rig = self._rig
        if rig is None or rig.camera is None or h <= 0.0:
            return None
        camera = rig.camera
        vp = camera.projection_matrix(w / h) @ camera.view_matrix
        clip = vp @ np.array([float(world.x), float(world.y), float(world.z), 1.0], dtype=np.float64)
        if clip[3] <= 1e-6:
            return None
        return (x + (clip[0] / clip[3] * 0.5 + 0.5) * w, y + (clip[1] / clip[3] * 0.5 + 0.5) * h)

    def _ship_screen_position(self, rect: tuple[float, float, float, float]) -> tuple[float, float]:
        """Where the ship sits on screen, falling back to the rect centre."""
        x, y, w, h = rect
        centre = (x + w * 0.5, y + h * 0.5)
        ship = self._ship
        if ship is None:
            return centre
        return self._project(Vec3(ship.world_position), rect) or centre

    # ----------------------------------------------------------------- draw

    def on_draw(self, renderer):
        rect = self.get_global_rect()
        cx, cy = self._ship_screen_position(rect)
        scale = self.effective_scale
        self._marker_rows = []

        self._draw_signature_border(renderer, rect)
        self._draw_damage_edges(renderer, rect, scale)
        self._draw_low_hull_pulse(renderer, rect, scale)
        self._draw_reading_plates(renderer, cx, cy, scale)
        self._draw_gauge_arcs(renderer, cx, cy, scale)
        self._draw_shield_arc(renderer, cx, cy, scale)
        self._draw_resource_strip(renderer, cx, cy, scale)
        self._draw_signature_gauge(renderer, cx, cy, scale)
        self._draw_warp_ring(renderer, rect, cx, cy, scale)
        self._draw_warp_outcome(renderer, rect, cx, cy, scale)
        self._draw_warp_status(renderer, cx, cy, scale)
        self._draw_interact_fill(renderer, cx, cy, scale)
        self._draw_affordance(renderer, cx, cy, scale)
        self._draw_hunter_marker(renderer, rect, scale)
        self._draw_beacon(renderer, rect, scale)
        self._draw_compass(renderer, rect, scale)
        self._draw_float_texts(renderer, rect, scale)
        self._draw_warnings(renderer, rect, cx, cy, scale)
        self._draw_controls_bar(renderer, rect, scale)
        self._draw_readouts(renderer, rect, scale)
        self._draw_sector_name(renderer, rect, scale)
        self._draw_control_card(renderer, rect, scale)
        self._draw_arrival_card(renderer, rect, scale)
        self._draw_toast(renderer, rect, scale)
        self._draw_subtitles(renderer, rect, scale)
        self._draw_stamp(renderer, rect, scale)
        self._draw_jump_flash(renderer, rect)
        self._draw_frame_stats(renderer, rect, scale)

    def _draw_signature_border(self, renderer, rect) -> None:
        if not self.is_element_visible(HudElements.SIGNATURE):
            return
        x, y, w, h = rect
        heat = self.signature_fraction
        colour = _lerp_colour(COLOUR_SIGNATURE_COLD, COLOUR_SIGNATURE_HOT, heat)
        thickness = SIGNATURE_BORDER_MIN_PX + (SIGNATURE_BORDER_MAX_PX - SIGNATURE_BORDER_MIN_PX) * heat
        renderer.rect((x, y), (w, thickness), fill=colour)
        renderer.rect((x, y + h - thickness), (w, thickness), fill=colour)
        renderer.rect((x, y), (thickness, h), fill=colour)
        renderer.rect((x + w - thickness, y), (thickness, h), fill=colour)

    def _draw_signature_gauge(self, renderer, cx: float, cy: float, scale: float) -> None:
        """The signature meter as a gauge you can read, over the ship's nose.

        The border is the same reading felt rather than read, and the two are
        driven by the one fraction so they can never disagree. This one carries
        the number, because "how close am I" is a question with an answer and
        the border can only ever say "closer than before".
        """
        if not self.is_element_visible(HudElements.SIGNATURE):
            return
        heat = self.signature_fraction
        colour = _lerp_colour(COLOUR_SIGNATURE_COLD, COLOUR_SIGNATURE_HOT, heat)
        radius = (ARC_RADIUS_PX + SIGNATURE_ARC_GAP_PX) * scale
        thickness = SIGNATURE_ARC_THICKNESS_PX * scale
        start = 270.0 - SIGNATURE_ARC_SPAN_DEGREES * 0.5
        _draw_arc(renderer, cx, cy, radius, start, SIGNATURE_ARC_SPAN_DEGREES, thickness, COLOUR_TRACK)
        filled = SIGNATURE_ARC_SPAN_DEGREES * heat
        if filled > 0.0:
            _draw_arc(renderer, cx, cy, radius, start, filled, thickness, _opaque(colour))
        line = SIGNATURE_LABEL_LINE_PX * scale
        renderer.text(
            SIGNATURE_LABEL.format(value=self._signature, maximum=balance.SIGNATURE_MAX),
            fill=_opaque(_lerp_colour(COLOUR_READOUT, COLOUR_SIGNATURE_HOT, heat)),
            scale=SIGNATURE_LABEL_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(cx - 160.0 * scale, cy - radius - SIGNATURE_LABEL_GAP_PX * scale - line, 320.0 * scale, line),
        )

    def _draw_hunter_marker(self, renderer, rect, scale: float) -> None:
        """Point at where the Shrike is coming from, and count it down.

        Without it, the ladder between the lock and the tear-in has exactly one
        visible channel, a border that is already red, and a pilot can spend the
        whole warning not knowing there is one. The marker rides the approach
        bearing and the label carries the seconds, so the warning is a bearing
        and a clock rather than a mood.
        """
        if not self._signature_locked or not self.is_element_visible(HudElements.SIGNATURE):
            return
        approach = self._hunter_approach()
        if approach is None:
            return
        seconds, bearing = approach
        ship = self._ship
        if ship is None:
            return
        direction = heading_to_direction(bearing)
        world = Vec3(ship.world_position) + Vec3(direction) * HUNTER_MARKER_RANGE_UNITS
        px, py = self._marker_point(world, rect, HUNTER_MARKER_EDGE_MARGIN_PX * scale, scale)
        renderer.circle((px, py), HUNTER_MARKER_RADIUS_PX * scale, stroke=COLOUR_HUNTER_MARKER, segments=3)
        half = HUNTER_LABEL_HALF_WIDTH_PX * scale
        wanted = py + MARKER_LABEL_GAP_PX * scale
        # Required: the countdown is the one marker that never stands down. A
        # pilot who cannot see the clock cannot spend it.
        row = self._marker_label_y(wanted, px, half, self._marker_rows, rect, scale, required=True)
        renderer.text(
            HUNTER_COUNTDOWN.format(seconds=max(0.0, seconds)),
            fill=COLOUR_HUNTER_MARKER,
            scale=HUNTER_MARKER_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(
                self._marker_label_left(px, half, rect, scale),
                row,
                2.0 * half,
                WARNING_LINE_HEIGHT_PX * scale,
            ),
        )

    def _draw_damage_edges(self, renderer, rect, scale: float) -> None:
        if not self.is_element_visible(HudElements.DAMAGE_DIRECTION):
            return
        x, y, w, h = rect
        band = DAMAGE_EDGE_BAND_PX * scale
        for edge, weight in self._edge_damage.items():
            if weight <= 0.0:
                continue
            colour = _with_alpha(COLOUR_DESATURATION, weight)
            if edge == "left":
                renderer.rect((x, y), (band, h), fill=colour)
            elif edge == "right":
                renderer.rect((x + w - band, y), (band, h), fill=colour)
            elif edge == "top":
                renderer.rect((x, y), (w, band), fill=colour)
            else:
                renderer.rect((x, y + h - band), (w, band), fill=colour)

    def _draw_low_hull_pulse(self, renderer, rect, scale: float) -> None:
        """Pulse the whole border while the hull is under the low mark.

        The signature border is a different animal: it warms slowly and never
        blinks. This one breathes, on all four edges at once, which is the one
        thing on the screen that means the next hit may be the last.

        It is also drawn :data:`LOW_HULL_INSET_PX` inboard rather than off the
        screen edge, so the two rings are a pair rather than a smear. The
        outermost pixels belong to the signature meter alone, which is what
        lets a jump be seen: arriving collapses that band to a cold hairline,
        and drawn at the edge, a low-hull ring would hide the change under a
        wider, brighter, almost identically red ring on top of it.
        """
        if not self.low_hull or not self.is_element_visible(HudElements.WARNINGS):
            return
        x, y, w, h = rect
        inset = LOW_HULL_INSET_PX
        x, y, w, h = x + inset, y + inset, w - inset * 2.0, h - inset * 2.0
        band = min(LOW_HULL_BAND_PX * scale, w * 0.5, h * 0.5)
        if band <= 0.0:
            return
        wave = 0.5 + 0.5 * math.sin(self._elapsed * LOW_HULL_PULSE_HZ * math.tau)
        alpha = LOW_HULL_PULSE_MIN_ALPHA + (LOW_HULL_PULSE_MAX_ALPHA - LOW_HULL_PULSE_MIN_ALPHA) * wave
        colour = _with_alpha(COLOUR_LOW_HULL_PULSE, alpha)
        renderer.rect((x, y), (w, band), fill=colour)
        renderer.rect((x, y + h - band), (w, band), fill=colour)
        renderer.rect((x, y), (band, h), fill=colour)
        renderer.rect((x + w - band, y), (band, h), fill=colour)

    def _draw_band(self, renderer, cx: float, cy: float, scale: float, offset: float, lines, font: float) -> None:
        """Write *lines* into the reserved band *offset* pixels under the ship.

        Every line under the hull goes through here, which is what keeps the
        bands from drifting into each other: a caller picks its band and the
        band picks the pixels. *lines* is a sequence of ``(text, colour)``.
        """
        line_height = WARNING_LINE_HEIGHT_PX * scale
        top = cy + offset * scale
        width = BAND_HALF_WIDTH_PX * 2.0 * scale
        for index, (text, colour) in enumerate(lines):
            renderer.text(
                text,
                fill=colour,
                scale=font * scale,
                align="centre",
                valign="centre",
                rect=(cx - BAND_HALF_WIDTH_PX * scale, top + index * line_height, width, line_height),
            )

    def _warning_lines(self) -> list[tuple[str, tuple[float, float, float, float]]]:
        """The survival lines the warning band is carrying, at most its height.

        Ordered by what kills first, because the band is shorter than the
        worst case and the tail is what gets dropped: a breached hull, then
        the air, then the tank. An empty tank strands a pilot who is otherwise
        fine, so it yields to both of the clocks that do not.
        """
        if not self.is_element_visible(HudElements.WARNINGS):
            return []
        lines: list[tuple[str, tuple[float, float, float, float]]] = []
        if self.low_hull:
            lines.append((LOW_HULL_WARNING, COLOUR_WARNING))
        if self.low_o2:
            lines.append((f"OXYGEN {max(0.0, self._o2_seconds):.0f}s", COLOUR_WARNING))
            lines.append((LOW_O2_HINT, COLOUR_HINT))
        if self.low_fuel and LOW_FUEL_SOURCE not in self._warp_status.lower():
            # The drive's own refusal already names the shop once the tank
            # will not cover a jump, and the two lines land a hand's width
            # apart. The refusal is the better of the two, because it quotes
            # the shortfall as well, so the hint is the one that stands down.
            lines.append((LOW_FUEL_HINT, COLOUR_HINT))
        return lines[:BAND_WARNING_LINES]

    def caption_block(self, rect, scale: float) -> tuple[float, float] | None:
        """Top and bottom of the caption track's plate, or ``None`` when it is empty.

        The track grows upward from a fixed base as sounds stack, so how far up
        the screen it reaches is a thing that changes several times a second.
        The standing lines under the hull are pinned to the ship, and the two
        meet at whatever height the camera is holding, which can put
        ``IT TEARS IN`` straight through ``OBJECTIVE: MINE THE GLOWING VEINS``
        and leave neither readable.
        """
        if not self._subtitles or not self.is_element_visible(HudElements.SUBTITLES):
            return None
        _x, y, _w, h = rect
        line = SUBTITLE_LINE_HEIGHT_PX * scale
        padding = SUBTITLE_PLATE_PADDING_Y_PX * scale
        base = y + h - SUBTITLE_BOTTOM_MARGIN_PX * scale - line * len(self._subtitles)
        return (base - padding, base + line * len(self._subtitles) + padding)

    def _band_is_clear(self, offset: float, lines: int, rect, scale: float) -> bool:
        """Whether a band *offset* under the hull is clear of the caption track."""
        block = self.caption_block(rect, scale)
        if block is None:
            return True
        top = self._band_top(offset, rect, scale)
        bottom = top + WARNING_LINE_HEIGHT_PX * scale * max(1, lines)
        return bottom <= block[0] or top >= block[1]

    def _bottom_furniture_top(self, rect, scale: float) -> float:
        """The topmost pixel the permanent furniture along the bottom edge owns.

        That is the controls strip and nothing else. It is the floor the
        ladder under the hull stops at: the strip is up for the whole run, so a
        standing line written through it is not a collision that clears, it is
        two sentences ruined for as long as the pilot flies that low.
        """
        _x, y, _w, h = rect
        return y + h - (CONTROLS_BAR_BAND_PX * scale if self.controls_bar else 0.0)

    def _lower_band_lift(self, rect, scale: float) -> float:
        """Pixels the objective and boundary bands ride up, together, off the floor.

        Everything above them is a reading of the ship and stays welded to the
        hull. These two are statements about the run and the sector, they are
        the bottom of the ladder, and they are the pair a diving camera walks
        into the controls strip: holding thrust puts the hull most of the way
        down the frame and the boundary notice off the bottom of it entirely.

        The pair moves as one, by the whole overflow, so the gap between them
        never changes and neither appearing shifts the other. It rides up only
        over rows nothing is using (:meth:`_lower_band_ceiling`): a reserved
        row is free ground while its own line is silent and never while it is
        not, and a survival warning is not a thing that yields. When the lift
        that is available is not enough the line stands down for the frame, the
        way it already does for the caption track, because a sentence written
        half off the bottom edge is not a sentence anybody read.
        """
        _cx, cy = self._ship_screen_position(rect)
        overflow = cy + BAND_LADDER_PX * scale - self._bottom_furniture_top(rect, scale)
        if overflow <= 0.0:
            return 0.0
        spare = max(0.0, BAND_OBJECTIVE_PX - self._lower_band_ceiling())
        return min(overflow, spare * scale)

    def _lower_band_ceiling(self) -> float:
        """The offset the objective band may not ride above, in unscaled pixels.

        The bottom of the lowest band over the pair that is writing something
        this frame, so the lift takes empty rows and stops dead at a used one.
        The resource strip's own plate reaches to :data:`BAND_CONTEXT_PX`, and
        the strip is up for the whole run, so that is the hard ceiling.
        """
        warnings = len(self._warning_lines())
        if warnings:
            return BAND_WARNING_PX + warnings * WARNING_LINE_HEIGHT_PX
        if self._warp_chip_is_up():
            return BAND_CONTEXT_PX + BAND_CONTEXT_LINES * WARNING_LINE_HEIGHT_PX
        return BAND_CONTEXT_PX

    def _warp_chip_is_up(self) -> bool:
        """Whether the drive's one-line answer is occupying the context band."""
        return bool(self._warp_status) and not self._warp_active and self.is_element_visible(HudElements.WARP_STATUS)

    def _band_top(self, offset: float, rect, scale: float) -> float:
        """The top pixel of the band *offset* under the hull, lift included."""
        _cx, cy = self._ship_screen_position(rect)
        top = cy + offset * scale
        if offset >= BAND_OBJECTIVE_PX:
            top -= self._lower_band_lift(rect, scale)
        return top

    def _band_clears_floor(self, offset: float, rect, scale: float) -> bool:
        """Whether one lifted line at *offset* still fits above the bottom furniture."""
        top = self._band_top(offset, rect, scale)
        return top + WARNING_LINE_HEIGHT_PX * scale <= self._bottom_furniture_top(rect, scale)

    def _objective_line(self, rect, scale: float) -> str:
        """What the objective band is carrying: the lock's instruction, or the run's."""
        if self._warp_active or not self.is_element_visible(HudElements.WARNINGS):
            return ""
        if not self._band_is_clear(BAND_OBJECTIVE_PX, 1, rect, scale):
            return ""
        if not self._band_clears_floor(BAND_OBJECTIVE_PX, rect, scale):
            return ""
        return SIGNATURE_LOCKED_INSTRUCTION if self._signature_locked else self._objective

    def _boundary_line(self, rect, scale: float) -> str:
        """What the boundary band is carrying, empty while the drive is spooling."""
        if self._warp_active or not self.is_element_visible(HudElements.WARNINGS):
            return ""
        if not self._band_is_clear(BAND_BOUNDARY_PX, 1, rect, scale):
            return ""
        if not self._band_clears_floor(BAND_BOUNDARY_PX, rect, scale):
            return ""
        return self.boundary_notice

    def _draw_warnings(self, renderer, rect, cx: float, cy: float, scale: float) -> None:
        """The survival states and the standing cues, in their reserved bands.

        Three bands rather than one stack: what the ship is in trouble about,
        what the run is asking of it, and where the sector stops. Sharing one
        offset with each other and with the warp chip, a pilot flying out of a
        sector while the meter is locked would get all four sentences printed
        through one another.

        While the drive is spooling the standing lines stand down: the ring's
        own label sweeps down through these bands as it closes, and it is the
        live version of what the objective is asking for anyway. They stand
        down for the caption track on the same principle: a sound the pilot is
        hearing right now is the live version of what is happening, the
        objective is a standing reminder that will still be true in two
        seconds, and the two written through each other are neither. The
        survival band never stands down for anything, because a hull warning
        buried under a caption is the death nobody saw coming.

        The two lowest bands also ride up off the controls strip when a diving
        camera has put the hull low enough to walk them into it
        (:meth:`_lower_band_lift`).
        """
        if not self.is_element_visible(HudElements.WARNINGS):
            return
        self._draw_band(renderer, cx, cy, scale, BAND_WARNING_PX, self._warning_lines(), WARNING_FONT_SCALE)
        lifted = cy - self._lower_band_lift(rect, scale)
        objective = self._objective_line(rect, scale)
        if objective:
            lines = [(objective, COLOUR_OBJECTIVE)]
            self._draw_band(renderer, cx, lifted, scale, BAND_OBJECTIVE_PX, lines, WARNING_FONT_SCALE)
        boundary = self._boundary_line(rect, scale)
        if boundary:
            row = [(boundary, COLOUR_HINT)]
            self._draw_band(renderer, cx, lifted, scale, BAND_BOUNDARY_PX, row, WARNING_FONT_SCALE)

    def _marker_point(self, target: Vec3, rect, margin: float, scale: float) -> tuple[float, float]:
        """Where a waypoint marker for *target* is pinned, *margin* inside the edge.

        A pitched camera puts anything far enough behind it outside the frustum,
        and the projection then says nothing at all. Falling back to the centre
        of the screen would plant the marker on the ship, and a pilot flying at
        a DEPOT marker that sits over their own hull flies out of the sector
        doing it. The flight plane maps straight onto the screen axes, so a
        failed projection is answered with the plane bearing, which is a real
        direction rather than a shrug.

        The bottom edge keeps :data:`MARKER_BOTTOM_MARGIN_PX` whatever *margin*
        asks for, because the captions and the controls strip live down there.
        """
        x, y, w, h = rect
        floor = max(margin, MARKER_BOTTOM_MARGIN_PX * scale)
        point = self._project(target, rect)
        if point is None:
            sx, sy = self._ship_screen_position(rect)
            ship = self._ship
            if ship is None:
                return (x + w * 0.5, y + h * 0.5)
            offset = Vec3(target) - Vec3(ship.world_position)
            dx, dz = float(offset.x), float(offset.z)  # world +Z is screen down
            reach = math.hypot(dx, dz)
            if reach < 1e-6:
                return (sx, sy)
            span = w + h
            point = (sx + dx / reach * span, sy + dz / reach * span)
        return (
            min(x + w - margin, max(x + margin, point[0])),
            min(y + h - floor, max(y + margin, point[1])),
        )

    def _range_label(self, base: str, target: Vec3) -> str:
        """``"DEPOT 41 u"``: a waypoint's name, its range and the unit.

        The unit is not decoration. A bare ``ORE 147`` in the corner of the
        screen reads as a second currency standing against the SCRAP counter,
        and sends the pilot looking for the shop that takes it.
        """
        ship = self._ship
        if ship is None:
            return base
        offset = Vec3(target) - Vec3(ship.world_position)
        return f"{base} {math.hypot(float(offset.x), float(offset.z)):.0f} {RANGE_UNIT_SUFFIX}"

    def _marker_label_left(self, px: float, half_width: float, rect, scale: float) -> float:
        """The left edge of a centred marker label, slid inboard of the screen.

        The marker is clamped to the edge margin, but a label centred on it is
        wider than the margin is deep, so a marker pinned to a side edge would
        print the outer half of its text off the screen. The rect keeps its
        width and slides until it fits; the text stays centred inside it.
        """
        x, _y, w, _h = rect
        inset = LABEL_EDGE_INSET_PX * scale
        left = px - half_width
        return min(max(left, x + inset), x + w - 2.0 * half_width - inset)

    def reading_band(self, rect, scale: float) -> tuple[float, float, float, float]:
        """The column of screen the ship's own standing lines own, as a rect.

        Everything the HUD writes about the hull is drawn on one vertical
        column: the affordance line and the signature reading above the ring,
        and the resource strip, the warp chip, the warnings, the objective and
        the boundary notice below it. A waypoint label is the one thing on the
        screen that is placed by where a rock is rather than by a layout, so it
        is the one thing that can land in the middle of them: the warp chip and
        a depot marker sharing a row of pixels read as
        ``PRESS R TO JUMDEPOT ON``.
        """
        cx, _cy = self._ship_screen_position(rect)
        half = BAND_HALF_WIDTH_PX * scale
        bottom = self._band_top(BAND_BOUNDARY_PX, rect, scale) + WARNING_LINE_HEIGHT_PX * scale
        return (cx - half, self.status_band_top(rect, scale), cx + half, bottom)

    def _corner_zones(self, rect, scale: float) -> list[tuple[float, float, float, float]]:
        """The standing furniture in the corners, as rects.

        The sector name in the top right and the two readout stacks down the
        left edge. They are the persistent part of the HUD, and a marker label
        that ignored them would print ``HULK 153 u`` and ``VEIN 131 u`` straight
        through ``DEBRIS FIELD`` from the top edge.
        """
        x, y, w, _h = rect
        margin = READOUT_MARGIN_PX * scale
        pad = READING_PLATE_PADDING_X_PX
        zones: list[tuple[float, float, float, float]] = []
        if self._sector_name and self.is_element_visible(HudElements.SECTOR):
            line = SECTOR_NAME_LINE_PX * scale
            width = _plate_width(self._sector_name, SECTOR_NAME_FONT_SCALE, scale, pad, SECTOR_NAME_BOX_PX * scale)
            zones.append((x + w - margin - width, y + margin, x + w - margin, y + margin + line))
        line = READOUT_LINE_HEIGHT_PX * scale
        stacks = (
            (self._top_left_readouts(), y + margin),
            (self._bottom_left_readouts(), self._bottom_left_base(rect, scale)),
        )
        for texts, top in stacks:
            if not texts:
                continue
            widest = max(texts, key=len)
            width = _plate_width(widest, READOUT_FONT_SCALE, scale, pad, w)
            zones.append((x + margin, top, x + margin + width, top + line * len(texts)))
        return zones

    def _plate_zones(self, rect, scale: float) -> list[tuple[float, float, float, float]]:
        """The two dark plates at the foot of the screen, as rects.

        The caption track and the answer line. Both are transient and both are
        centred, which is exactly where a marker riding the bottom edge puts its
        range: a ``KILL CHIME / HULL BREACHED`` plate dropped over ``HULK 91 u``
        leaves the hulk's range unreadable.
        """
        x, _y, w, _h = rect
        zones: list[tuple[float, float, float, float]] = []
        block = self.caption_block(rect, scale)
        if block is not None:
            widest = max(self._subtitles, key=lambda entry: len(entry[0]))[0]
            plate = _plate_width(widest, SUBTITLE_FONT_SCALE, scale, SUBTITLE_PLATE_PADDING_X_PX, w)
            zones.append((x + (w - plate) * 0.5, block[0], x + (w + plate) * 0.5, block[1]))
        text = self.toast
        if text and self.is_element_visible(HudElements.TOAST):
            padding = SUBTITLE_PLATE_PADDING_Y_PX * scale
            base = self.message_row(rect, scale)
            plate = _plate_width(text, TOAST_FONT_SCALE, scale, SUBTITLE_PLATE_PADDING_X_PX, w)
            top = base - padding
            bottom = base + TOAST_LINE_HEIGHT_PX * scale + padding
            zones.append((x + (w - plate) * 0.5, top, x + (w + plate) * 0.5, bottom))
        return zones

    def _label_zones(self, rect, scale: float) -> list[tuple[float, float, float, float]]:
        """The standing HUD a waypoint label steps around, as screen rects.

        The ship's own readings (:meth:`reading_band`), whichever tutorial or
        arrival card is up, and the standing furniture in the corners. The cards
        yield around the ship's band and the labels are placed by where a rock
        is, so without this the two meet in the one place neither of them is
        watching, with ``HULK 25 u`` written into the middle of the aiming
        lesson.

        Avoiding the other markers is not enough: the sector name and the
        ``HULL 100`` chip beside the ring would each take a range through them.
        A label that dodges only its own kind is a label that lands on
        everything else.

        The transient plates at the foot of the screen are not here: they are
        :meth:`_plate_zones`, and a label treats them differently because they
        go away on their own.
        """
        zones = [self.reading_band(rect, scale)]
        for layout in (self.control_card_layout(rect, scale), self.arrival_card_layout(rect, scale)):
            if layout is not None:
                zones.append((layout.x, layout.y, layout.x + layout.width, layout.bottom))
        zones.extend(self._corner_zones(rect, scale))
        return zones

    def _blocked_rows(
        self, zones, left_edge: float, right_edge: float, taken: list, scale
    ) -> list[tuple[float, float]]:
        """Row spans a label between *left_edge* and *right_edge* may not take.

        One merged, disjoint list rather than a rect at a time, because dodging
        a zone one at a time is how a label ends up oscillating between two of
        them: the tutorial card sits directly above the ship's band, so stepping
        up out of the band lands in the card and stepping down out of the card
        lands back in the band. Merged spans have edges, and an edge is a row
        that is clear of everything at once.
        """
        line = WARNING_LINE_HEIGHT_PX * scale
        clearance = MARKER_ZONE_CLEARANCE_PX * scale
        separation = MARKER_LABEL_SEPARATION_PX * scale
        spans: list[tuple[float, float]] = []
        for left, top, right, bottom in zones:
            if left_edge < right and right_edge > left:
                spans.append((top - line - clearance, bottom + clearance))
        for other_row, other_left, other_right in taken:
            if left_edge < other_right and right_edge > other_left:
                spans.append((other_row - separation, other_row + separation))
        merged: list[list[float]] = []
        for start, end in sorted(spans):
            if merged and start < merged[-1][1]:
                merged[-1][1] = max(merged[-1][1], end)
            else:
                merged.append([start, end])
        return [(start, end) for start, end in merged]

    @staticmethod
    def _nearest_free_row(wanted: float, spans, floor: float, ceiling: float) -> float | None:
        """The row nearest *wanted* between *floor* and *ceiling* and outside *spans*.

        ``None`` when every row in the range is spoken for, which is a marker
        that has been shut out of its own edge. The candidates are *wanted* and
        the edges of the merged spans, because the nearest clear row to a point
        inside a span is that span's own edge.
        """
        if floor > ceiling:
            return None
        candidates = [wanted]
        for start, end in spans:
            candidates.append(start)
            candidates.append(end)
        best: float | None = None
        for candidate in candidates:
            row = min(max(candidate, floor), ceiling)
            if any(start < row < end for start, end in spans):
                continue
            if best is None or abs(row - wanted) < abs(best - wanted):
                best = row
        return best

    def _marker_label_y(
        self,
        wanted: float,
        px: float,
        half_width: float,
        taken: list,
        rect,
        scale,
        *,
        required: bool = False,
    ) -> float | None:
        """A free row for a marker label at *wanted*, clear of the HUD and *taken*.

        Two waypoints on similar bearings pin to the same edge, so the beacon,
        the compass and the Shrike countdown share *taken*, one list for the
        whole frame: with a private list each, ``DEPOT 8 u`` and ``VEIN 7 u``
        would land on one row and read as ``DEPO7 08 u``. It carries each
        label's span as well as its row, so two markers at opposite edges still
        share a row.

        The label steps along its own edge, up or down to whichever free row is
        nearer, until it is clear of the standing HUD too, however far that is:
        the tutorial card and the readings under the hull are not going away and
        a marker without a range is not a waypoint.

        The two transient plates at the foot of the screen are the exception. A
        label steps around them as well, but only as far as
        :data:`MARKER_LABEL_MAX_TRAVEL_PX` from the row it was standing on;
        beyond that it returns ``None`` and the caller stands the whole marker
        down for the frame, because a plate that has taken the row is a plate
        that will hand it back in a second or two. *required* markers never
        stand down: that is the Shrike countdown and an armed dock prompt, and a
        warning that yields to a caption is a warning nobody got.
        """
        _x, y, _w, h = rect
        line = WARNING_LINE_HEIGHT_PX * scale
        ceiling = y + h - CONTROLS_BAR_BAND_PX * scale - line
        floor = y + line
        left_edge = self._marker_label_left(px, half_width, rect, scale)
        right_edge = left_edge + 2.0 * half_width
        standing = self._label_zones(rect, scale)
        spans = self._blocked_rows(standing, left_edge, right_edge, taken, scale)
        row = self._nearest_free_row(wanted, spans, floor, ceiling)
        if row is None:
            row = min(max(wanted, floor), ceiling)
        plates = self._plate_zones(rect, scale)
        if plates:
            spans = self._blocked_rows(standing + plates, left_edge, right_edge, taken, scale)
            clear = self._nearest_free_row(row, spans, floor, ceiling)
            if clear is None or abs(clear - row) > MARKER_LABEL_MAX_TRAVEL_PX * scale:
                if not required:
                    return None
            else:
                row = clear
        taken.append((row, left_edge, right_edge))
        return row

    def _draw_compass(self, renderer, rect, scale: float) -> None:
        """Point at each of the nearest vein and hulk that is not on screen.

        The depot beacon generalised: a pilot who has flown out of the content
        is given the bearing and the range of each kind of thing there is to
        fly back to. A marker goes away when its own target comes into view,
        and only then. Suppressing the whole set the moment any one of them is
        visible would make a depot marker vanish mid-flight and leave a pilot
        holding a heading out of the sector.
        """
        targets = self.compass_targets
        if not targets or not self.is_element_visible(HudElements.BEACON):
            return
        x, y, w, h = rect
        inset = COMPASS_ON_SCREEN_MARGIN_PX * scale
        margin = COMPASS_EDGE_MARGIN_PX * scale
        line = WARNING_LINE_HEIGHT_PX * scale
        rows = self._marker_rows
        for position, kind in targets:
            point = self._project(position, rect)
            if point is not None and x + inset <= point[0] <= x + w - inset and y + inset <= point[1] <= y + h - inset:
                continue  # the thing itself is on screen; a marker over it is noise
            px, py = self._marker_point(position, rect, margin, scale)
            half = MARKER_LABEL_HALF_WIDTH_PX * scale
            row = self._marker_label_y(py + MARKER_LABEL_GAP_PX * scale, px, half, rows, rect, scale)
            if row is None:
                # Shut out of its own edge by a panel. A ring with no range on
                # it is a dot; the panel is transient and the marker returns.
                continue
            renderer.circle(
                (px, py), COMPASS_RADIUS_PX * scale, stroke=COLOUR_COMPASS, segments=COMPASS_SEGMENTS.get(kind, 6)
            )
            renderer.text(
                self._range_label(COMPASS_LABELS.get(kind, kind.upper()), position),
                fill=COLOUR_COMPASS,
                scale=COMPASS_FONT_SCALE * scale,
                align="centre",
                valign="centre",
                rect=(self._marker_label_left(px, half, rect, scale), row, 2.0 * half, line),
            )

    def _draw_beacon(self, renderer, rect, scale: float) -> None:
        """Mark the sector's depot, how far away it is, and when you are in it.

        Drawn where the depot is when that is on screen, and pinned inside the
        edge in its direction when it is not, so the marker is a bearing and a
        range rather than a thing that vanishes the moment it matters.

        Inside the bay it becomes the prompt. A ring whose range just keeps
        counting, with the one line that names the key small, at the top of the
        screen and under a tutorial card, is a ring a pilot crosses three times
        without docking. The ring fills, grows and carries the verb itself, which
        puts the answer where the pilot is already looking.
        """
        target = self._beacon_position
        if target is None or not self.is_element_visible(HudElements.BEACON):
            return
        prompt = self.dock_prompt
        armed = bool(prompt)
        colour = COLOUR_BEACON_ARMED if armed else COLOUR_BEACON
        radius = BEACON_RADIUS_PX * scale * (BEACON_ARMED_RADIUS_MULT if armed else 1.0)
        px, py = self._marker_point(target, rect, BEACON_EDGE_MARGIN_PX * scale, scale)
        half = MARKER_LABEL_HALF_WIDTH_PX * scale
        # An armed bay carries the verb rather than a range, and the verb is the
        # answer to "why am I sitting in this ring": it never stands down.
        row = self._marker_label_y(
            py + MARKER_LABEL_GAP_PX * scale, px, half, self._marker_rows, rect, scale, required=armed
        )
        if row is None:
            return
        # The ring's armed form: filled, with a second ring standing off it.
        if armed:
            renderer.circle((px, py), radius, fill=colour, segments=4)
            renderer.circle((px, py), radius * 1.6, stroke=colour, segments=4)
        else:
            renderer.circle((px, py), radius, stroke=colour, segments=4)
        renderer.text(
            prompt if armed else self._range_label(self._beacon_label, target),
            fill=colour,
            scale=(BEACON_ARMED_FONT_SCALE if armed else BEACON_FONT_SCALE) * scale,
            align="centre",
            valign="centre",
            rect=(self._marker_label_left(px, half, rect, scale), row, 2.0 * half, WARNING_LINE_HEIGHT_PX * scale),
        )

    def _float_target_point(self, name: str, rect, scale: float):
        """Where on screen the counter *name* is drawn, or None when it is not.

        The strip under the ring is the target, because the hold lives there: a
        label flying a hand's width to a number beside the ship reads as
        income, where the same label crossing the whole screen to a corner
        mostly reads as something leaving.
        """
        if name != FLOAT_TARGET_SCRAP:
            return None
        cells = self._resource_cells()
        if not cells or not self.is_element_visible(HudElements.SCRAP):
            return None
        cx, cy = self._ship_screen_position(rect)
        left = cx - RESOURCE_CELL_PX * scale * len(cells) * 0.5
        return (
            left + RESOURCE_CELL_PX * scale * 0.5,
            cy + (BAND_RESOURCES_PX + RESOURCE_LINE_PX * 0.5) * scale,
        )

    def _float_lane(self, point, width: float, line: float, readings, rect, scale: float) -> float:
        """How far sideways a rising float steps to clear the ship's own readings.

        A rising label sweeps :data:`FLOAT_TEXT_RISE_PX` upward from where it
        landed, and the readings around the hull sit in a narrow column in the
        middle of that sweep. The burn float is the case that matters: it is
        anchored on the ship it just hit, and would rise straight through ``HULL``
        on the one frame where the hull number had something to say. The lane
        is decided from the whole flight rather than from this frame's row, so
        a label picks a side once and holds it instead of hopping sideways
        half way up.

        Only labels planted in the world get a lane. One pinned to a node is a
        label *about* that node, and a tag that steps off the enemy it names is
        a tag pointing at nothing; those keep their anchor and their overlap.

        Zero when nothing is in the way, which is almost always.
        """
        if not readings:
            return 0.0
        left = point[0] - width * 0.5
        right = point[0] + width * 0.5
        bottom = point[1]
        top = point[1] - FLOAT_TEXT_RISE_PX * scale - line
        blocked = [
            plate
            for plate in readings
            if left < plate[0] + plate[2] and right > plate[0] and top < plate[1] + plate[3] and bottom > plate[1]
        ]
        if not blocked:
            return 0.0
        wanted_right = max(plate[0] + plate[2] for plate in blocked) + width * 0.5 - point[0]
        wanted_left = min(plate[0] for plate in blocked) - width * 0.5 - point[0]
        x, _y, w, _h = rect
        if point[0] + wanted_right + width * 0.5 <= x + w:
            return wanted_right
        if point[0] + wanted_left - width * 0.5 >= x:
            return wanted_left
        return wanted_right if abs(wanted_right) <= abs(wanted_left) else wanted_left

    def _draw_float_texts(self, renderer, rect, scale: float) -> None:
        """Draw the world-anchored labels, flying to the counter they credit.

        A label with no counter rises and fades where it landed, which is what
        a first-sighting tag or a refill wants. One that names a counter eases
        across to it instead, so the number in the corner visibly grows because
        of the thing the pilot just flew through.

        A riser that would sweep through one of the ship's own readings takes a
        lane beside it (:meth:`_float_lane`): the reading is what the label is
        there to explain, and a label written over it explains nothing.
        """
        if not self._floats or not self.is_element_visible(HudElements.FLOAT_TEXT):
            return
        line = WARNING_LINE_HEIGHT_PX * scale
        # Measured on the first label that could need a lane, and usually never.
        readings: list[tuple[float, float, float, float]] | None = None
        for text, remaining, total, colour, reference, anchor, toward, plate in self._floats:
            node = reference() if reference is not None else None
            world = anchor
            live = getattr(node, "world_position", None) if getattr(node, "tree", None) is not None else None
            if live is not None:
                world = Vec3(live)
            if world is None:
                continue
            point = self._project(world, rect)
            if point is None:
                continue
            travelled = 1.0 - remaining / total
            destination = self._float_target_point(toward, rect, scale) if toward else None
            planted = destination is None and live is None
            # Measured only when it is going to be used, for the plate or for
            # the lane: this runs per label per frame.
            plate_width = (
                _plate_width(text, FLOAT_TEXT_FONT_SCALE, scale, SUBTITLE_PLATE_PADDING_X_PX, rect[2])
                if plate or planted
                else 0.0
            )
            if destination is None:
                px, py = point[0], point[1] - FLOAT_TEXT_RISE_PX * scale * travelled
                if planted:
                    if readings is None:
                        cx, cy = self._ship_screen_position(rect)
                        readings = self.reading_plate_rects(cx, cy, scale)
                    px += self._float_lane(point, plate_width, line, readings, rect, scale)
            else:
                flight = travelled**FLOAT_TEXT_FLIGHT_EASE
                px = point[0] + (destination[0] - point[0]) * flight
                py = point[1] + (destination[1] - point[1]) * flight
            alpha = min(1.0, remaining / FLOAT_TEXT_FADE_S)
            if plate:
                plate_padding = SUBTITLE_PLATE_PADDING_Y_PX * scale
                renderer.rect(
                    (px - plate_width * 0.5, py - line - plate_padding),
                    (plate_width, line + 2.0 * plate_padding),
                    fill=_with_alpha(COLOUR_SUBTITLE_PLATE, alpha),
                )
            renderer.text(
                text,
                fill=_with_alpha(colour, alpha),
                scale=FLOAT_TEXT_FONT_SCALE * scale,
                align="centre",
                valign="centre",
                rect=(px - 140.0 * scale, py - line, 280.0 * scale, line),
            )

    def _band_occupancy(self, rect, scale: float) -> list[tuple[float, float]]:
        """Every row under the hull that is spoken for this frame, outward from the ring.

        The standing lines (:meth:`_standing_bands`) and the failed spool's own
        name, which is not standing but is written into the same column and is
        up long enough to be landed on.
        """
        spans = self._standing_bands(rect, scale)
        outcome = self.warp_outcome_row(rect, scale)
        if outcome is not None:
            spans.append(outcome)
            spans.sort()
        return spans

    def _standing_bands(self, rect, scale: float) -> list[tuple[float, float]]:
        """Top and bottom of every standing line the HUD is writing under the hull.

        Ordered outward from the ring, and only what is actually on screen this
        frame: a band reserved for a warning nobody is having is free ground,
        and the message line is what uses it. The plate under the resource strip
        is part of the strip's extent, because the plate is what the eye reads
        as the edge of the row.
        """
        _cx, cy = self._ship_screen_position(rect)
        spans: list[tuple[float, float]] = []
        cells = self._resource_cells()
        pips = self.state_pips()
        if cells or pips:
            pad = RESOURCE_PLATE_PADDING_PX * scale
            height = (RESOURCE_LINE_PX * bool(cells) + STATE_PIP_LINE_PX * bool(pips)) * scale
            top = cy + BAND_RESOURCES_PX * scale - pad
            spans.append((top, top + height + 2.0 * pad))
        line = WARNING_LINE_HEIGHT_PX * scale
        if self._warp_chip_is_up():
            top = cy + BAND_CONTEXT_PX * scale
            spans.append((top, top + line))
        warnings = len(self._warning_lines())
        if warnings:
            top = cy + BAND_WARNING_PX * scale
            spans.append((top, top + line * warnings))
        if self._objective_line(rect, scale):
            top = self._band_top(BAND_OBJECTIVE_PX, rect, scale)
            spans.append((top, top + line))
        if self._boundary_line(rect, scale):
            top = self._band_top(BAND_BOUNDARY_PX, rect, scale)
            spans.append((top, top + line))
        return spans

    def message_row(self, rect, scale: float) -> float:
        """The row the transient answer line owns this frame.

        The answer to a key press is anchored to the screen and the ship's
        standing lines are anchored to the hull, so the two cross whenever the
        pilot flies at the height that brings them together, which would
        write the chart refusal straight through
        OBJECTIVE. The message keeps its usual row and steps up past whatever
        standing line is in it, taking the first free row it finds. When the
        stack under the hull leaves no free row at all, it goes above the ship's
        whole cluster instead, and the tutorial card yields to it there
        (:meth:`_top_band_ceiling`).
        """
        x, y, w, h = rect
        del x, w
        line = TOAST_LINE_HEIGHT_PX * scale
        gap = MESSAGE_ROW_GAP_PX * scale
        row = y + h - SUBTITLE_BOTTOM_MARGIN_PX * scale - TOAST_GAP_PX * scale
        row -= SUBTITLE_LINE_HEIGHT_PX * scale * SUBTITLE_MAX_LINES + line
        _cx, cy = self._ship_screen_position(rect)
        floor = cy + BAND_RESOURCES_PX * scale - gap - line
        for top, bottom in reversed(self._band_occupancy(rect, scale)):
            if row < bottom + gap and row + line > top - gap:
                row = top - gap - line
        if row < floor:
            return self.status_band_top(rect, scale) - gap - line
        return row

    def _message_in_top_band(self, rect, scale: float) -> bool:
        """Whether the message line has been pushed above the ship's cluster."""
        if self._toast_remaining <= 0.0 or not self.is_element_visible(HudElements.TOAST):
            return False
        return self.message_row(rect, scale) < self.status_band_top(rect, scale)

    def _draw_toast(self, renderer, rect, scale: float) -> None:
        """The answer to the last key press, on its own plate above the captions.

        It gets the caption track's treatment because it is read the same way:
        one line, glanced at mid-manoeuvre, over whatever the sector happens to
        be drawing. Unbacked and dimmed it would lose every contest with the
        standing lines under the hull, and a refusal a pilot cannot read is a
        refusal they file as a broken key.
        """
        text = self.toast
        if not text or not self.is_element_visible(HudElements.TOAST):
            return
        x, _y, w, _h = rect
        line = TOAST_LINE_HEIGHT_PX * scale
        base = self.message_row(rect, scale)
        alpha = min(1.0, self._toast_remaining / TOAST_FADE_S)
        plate_width = _plate_width(text, TOAST_FONT_SCALE, scale, SUBTITLE_PLATE_PADDING_X_PX, w)
        plate_padding = SUBTITLE_PLATE_PADDING_Y_PX * scale
        renderer.rect(
            (x + (w - plate_width) * 0.5, base - plate_padding),
            (plate_width, line + 2.0 * plate_padding),
            fill=_with_alpha(COLOUR_SUBTITLE_PLATE, alpha),
        )
        renderer.text(
            text,
            fill=_with_alpha(_opaque(COLOUR_TOAST), alpha),
            scale=TOAST_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(x, base, w, line),
        )

    def ring_labels(self) -> tuple[tuple[str, str], ...]:
        """The gauge captions as ``(compass_point, text)``, in drawing order.

        Hull and capacitor carry their number; oxygen and fuel do not, because
        theirs is in the resource strip a hand's width below.
        """
        labels = []
        for element, _centre, _span, _colour, caption, compass in _ARC_SPECS:
            if not self.is_element_visible(element):
                continue
            if element in _ARC_VALUE_ELEMENTS:
                caption = ARC_LABEL_WITH_VALUE.format(caption=caption, value=self._levels[element])
            labels.append((compass, caption))
        return tuple(labels)

    @staticmethod
    def _arc_label_rect(compass: str, cx: float, cy: float, scale: float) -> tuple[tuple, str]:
        """Where a ring caption on *compass* is written, and how it is aligned.

        The side captions hang outward from the rings and are aligned to the
        edge nearest the hull, so the type grows away from the ship instead of
        into it. The top and bottom ones are centred above and below every ring
        that reaches their bearing.
        """
        box = ARC_LABEL_BOX_PX * scale
        line = ARC_LABEL_LINE_PX * scale
        side = ARC_LABEL_RADIUS_PX * scale
        if compass == "left":
            return ((cx - side - box, cy - line * 0.5, box, line), "right")
        if compass == "right":
            return ((cx + side, cy - line * 0.5, box, line), "left")
        if compass == "top":
            return ((cx - box * 0.5, cy - ARC_LABEL_TOP_RADIUS_PX * scale - line, box, line), "centre")
        return ((cx - box * 0.5, cy + side, box, line), "centre")

    def reading_plate_rects(self, cx: float, cy: float, scale: float) -> list[tuple[float, float, float, float]]:
        """Backing plates for the readings around the hull, as ``(x, y, w, h)``.

        Every caption the ring cluster writes and the signature reading above
        it. Sized to the type rather than to the caption box, so the plates read
        as chips behind the numbers rather than as a panel drawn around the
        ship. Public because the thing they exist to survive is a rendered
        frame, and a test that cannot ask where they are can only assert that
        some rects were drawn.
        """
        pad_x = READING_PLATE_PADDING_X_PX * scale
        pad_y = READING_PLATE_PADDING_Y_PX * scale
        line = ARC_LABEL_LINE_PX * scale
        plates: list[tuple[float, float, float, float]] = []
        for compass, text in self.ring_labels():
            box, alignment = self._arc_label_rect(compass, cx, cy, scale)
            width = _plate_width(text, ARC_LABEL_FONT_SCALE, scale, READING_PLATE_PADDING_X_PX, box[2] + 2.0 * pad_x)
            if alignment == "right":
                left = box[0] + box[2] - width
            elif alignment == "left":
                left = box[0]
            else:
                left = box[0] + (box[2] - width) * 0.5
            plates.append((left, box[1] - pad_y, width, line + 2.0 * pad_y))
        if self.is_element_visible(HudElements.SIGNATURE):
            text = SIGNATURE_LABEL.format(value=self._signature, maximum=balance.SIGNATURE_MAX)
            width = _plate_width(text, SIGNATURE_LABEL_FONT_SCALE, scale, READING_PLATE_PADDING_X_PX, 320.0 * scale)
            top = cy - (ARC_RADIUS_PX + SIGNATURE_ARC_GAP_PX + SIGNATURE_LABEL_GAP_PX) * scale
            line = SIGNATURE_LABEL_LINE_PX * scale
            plates.append((cx - width * 0.5, top - line - pad_y, width, line + 2.0 * pad_y))
        return plates

    def _draw_reading_plates(self, renderer, cx: float, cy: float, scale: float) -> None:
        """Lay the reading plates down before anything is written on them."""
        for x, y, width, height in self.reading_plate_rects(cx, cy, scale):
            renderer.rect((x, y), (width, height), fill=COLOUR_READING_PLATE)

    def _draw_gauge_arcs(self, renderer, cx: float, cy: float, scale: float) -> None:
        radius = ARC_RADIUS_PX * scale
        thickness = ARC_THICKNESS_PX * scale
        texts = dict(self.ring_labels())
        blacked = self.capacitor_blacked_out
        for element, centre_deg, span_deg, colour, _caption, compass in _ARC_SPECS:
            if not self.is_element_visible(element):
                continue
            if element == HudElements.CAPACITOR and blacked:
                colour = COLOUR_BLACKOUT
            start = centre_deg - span_deg * 0.5
            _draw_arc(renderer, cx, cy, radius, start, span_deg, thickness, COLOUR_TRACK)
            filled = span_deg * self._gauges[element]
            if filled > 0.0:
                _draw_arc(renderer, cx, cy, radius, start, filled, thickness, colour)
            if element == HudElements.HULL:
                chip = span_deg * (self.hull_chip - self._gauges[element])
                if chip > 0.0:
                    # Drawn proud of the ring as well as in its own colour, so
                    # the loss is a shape change and not only a hue change.
                    chip_thickness = thickness * HULL_CHIP_THICKNESS_MULT
                    _draw_arc(renderer, cx, cy, radius, start + filled, chip, chip_thickness, COLOUR_HULL_CHIP)
            box, alignment = self._arc_label_rect(compass, cx, cy, scale)
            renderer.text(
                texts[compass],
                fill=_opaque(colour),
                scale=ARC_LABEL_FONT_SCALE * scale,
                align=alignment,
                valign="centre",
                rect=box,
            )

    def _draw_shield_arc(self, renderer, cx: float, cy: float, scale: float) -> None:
        """Draw the shield pad on the bearing it is actually covering.

        Q and E move it, and an arc that existed only in the collision maths
        would make the two keys read as unbound. It rides just outside the gauge ring and turns red once the
        pad is broken, which is the other state the pilot has to know about.
        """
        shield = getattr(self._ship, "shield", None)
        bearing = self.shield_bearing
        if shield is None or bearing is None:
            return
        span = math.degrees(float(shield.half_width)) * 2.0
        radius = (ARC_RADIUS_PX + SHIELD_ARC_GAP_PX) * scale
        broken = bool(getattr(shield, "broken", False))
        colour = COLOUR_SHIELD_BROKEN if broken else COLOUR_SHIELD
        charge = _fraction(float(getattr(shield, "charge", 0.0)), float(getattr(shield, "charge_max", 0.0)))
        _draw_arc(renderer, cx, cy, radius, bearing - span * 0.5, span, SHIELD_ARC_THICKNESS_PX * scale, COLOUR_TRACK)
        filled = span * (0.0 if broken else charge)
        if filled > 0.0:
            _draw_arc(renderer, cx, cy, radius, bearing - span * 0.5, filled, SHIELD_ARC_THICKNESS_PX * scale, colour)
        elif broken:
            _draw_arc(renderer, cx, cy, radius, bearing - span * 0.5, span, SHIELD_ARC_THICKNESS_PX * scale, colour)

    def _draw_resource_strip(self, renderer, cx: float, cy: float, scale: float) -> None:
        """The numbers the run charges and credits, in one row under the ring.

        Two rows, in fact: the resources on top and the power-state pips under
        them, both in fixed cells so a number growing a digit never shoves its
        neighbours sideways.

        Both rows sit on a faint plate. They are drawn over the playfield rather
        than over a panel, and a bright nebula or a wreck drifting under them
        would take the row with it, leaving the word SCRAP without its
        count. The plate is the cheapest thing that makes
        a number in front of the world stay a number.
        """
        cells = self._resource_cells()
        self._draw_resource_plate(renderer, cx, cy, scale, cells)
        if cells:
            self._draw_cells(
                renderer,
                cx,
                cy + BAND_RESOURCES_PX * scale,
                scale,
                cells,
                RESOURCE_CELL_PX,
                RESOURCE_LINE_PX,
                RESOURCE_FONT_SCALE,
            )
        pips = self.state_pips()
        if pips:
            self._draw_cells(
                renderer,
                cx,
                cy + (BAND_RESOURCES_PX + RESOURCE_LINE_PX) * scale,
                scale,
                [(text, COLOUR_STATE_PIP_ON if lit else COLOUR_STATE_PIP_OFF) for text, lit in pips],
                STATE_PIP_CELL_PX,
                STATE_PIP_LINE_PX,
                STATE_PIP_FONT_SCALE,
            )

    def _draw_resource_plate(self, renderer, cx: float, cy: float, scale: float, cells) -> None:
        """The backing plate under both rows of the strip, sized to the wider one."""
        pips = self.state_pips()
        width = max(RESOURCE_CELL_PX * len(cells), STATE_PIP_CELL_PX * len(pips)) * scale
        if width <= 0.0:
            return
        pad = RESOURCE_PLATE_PADDING_PX * scale
        height = (RESOURCE_LINE_PX * bool(cells) + STATE_PIP_LINE_PX * bool(pips)) * scale
        renderer.rect(
            (cx - width * 0.5 - pad, cy + BAND_RESOURCES_PX * scale - pad),
            (width + 2.0 * pad, height + 2.0 * pad),
            fill=COLOUR_RESOURCE_PLATE,
        )

    @staticmethod
    def _draw_cells(renderer, cx: float, top: float, scale: float, cells, cell_px, line_px, font) -> None:
        """Lay *cells* out as one centred row of fixed-width boxes."""
        cell = cell_px * scale
        line = line_px * scale
        left = cx - cell * len(cells) * 0.5
        for index, (text, colour) in enumerate(cells):
            renderer.text(
                text,
                fill=colour,
                scale=font * scale,
                align="centre",
                valign="centre",
                rect=(left + index * cell, top, cell, line),
            )

    def _draw_affordance(self, renderer, cx: float, cy: float, scale: float) -> None:
        """The one verb in reach, above the gauge ring and under the reticle.

        Stands down when the bay's ring is already carrying this very sentence
        (:meth:`dock_prompt`): the ring is beside the ship the whole time the
        hull is inside it, and the same three words printed twice a hand's
        width apart read as a stutter rather than as emphasis.
        """
        text = self.affordance
        if not text or not self.is_element_visible(HudElements.AFFORDANCE):
            return
        if text == self.dock_prompt and self.is_element_visible(HudElements.BEACON):
            return
        line = AFFORDANCE_LINE_PX * scale
        top = cy - (SIGNATURE_GAUGE_TOP_PX + AFFORDANCE_GAP_PX) * scale - line
        renderer.text(
            text,
            fill=COLOUR_AFFORDANCE,
            scale=AFFORDANCE_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(cx - 260.0 * scale, top, 520.0 * scale, line),
        )

    def warp_chip_plate_rect(self, cx: float, cy: float, scale: float) -> tuple[float, float, float, float] | None:
        """The plate behind the drive's chip as ``(x, y, w, h)``, None when it is down.

        Public for the reason the readings' plates are (:meth:`reading_plate_rects`):
        the thing it exists to survive is a rendered frame, and what it has to
        survive is drawn a moment before it.
        """
        if not self._warp_chip_is_up():
            return None
        width = _plate_width(
            self._warp_status,
            WARP_STATUS_FONT_SCALE,
            scale,
            WARP_STATUS_PLATE_PADDING_X_PX,
            BAND_HALF_WIDTH_PX * 2.0 * scale,
        )
        return (cx - width * 0.5, cy + BAND_CONTEXT_PX * scale, width, WARNING_LINE_HEIGHT_PX * scale)

    def _draw_warp_status(self, renderer, cx: float, cy: float, scale: float) -> None:
        """The drive's standing answer, in the context band under the ship.

        Suppressed while a spool is actually running: the ring and its own
        label are the live version of the same sentence. It is written on a
        plate, and the plate is what the failed ring passes behind: the refusal
        and the red ring that announces it are on screen together, and the ring
        holds the outer radius, which is this row.
        """
        if not self._warp_chip_is_up():
            return
        plate = self.warp_chip_plate_rect(cx, cy, scale)
        if plate is not None:
            x, y, width, height = plate
            renderer.rect((x, y), (width, height), fill=COLOUR_WARP_STATUS_PLATE)
        colour = COLOUR_WARP_STATUS_BLOCKED if self._warp_status_blocked else COLOUR_WARP_STATUS
        self._draw_band(renderer, cx, cy, scale, BAND_CONTEXT_PX, [(self._warp_status, colour)], WARP_STATUS_FONT_SCALE)

    def _draw_controls_bar(self, renderer, rect, scale: float) -> None:
        """The persistent key list along the bottom edge, on its own plate.

        Two rows on a dark plate. Dim letters straight over a star field turn
        the strip into a mote-speckled smear, and one row can only ever name
        half the keyboard.
        """
        rows = [row for row in (self.controls_bar, self.controls_bar_second_row) if row]
        if not rows or not self.is_element_visible(HudElements.CONTROLS_BAR):
            return
        x, y, w, h = rect
        line = CONTROLS_BAR_LINE_PX * scale
        padding = CONTROLS_BAR_PLATE_PADDING_PX * scale
        plate_height = line * len(rows) + 2.0 * padding
        plate_top = y + h - CONTROLS_BAR_MARGIN_PX * scale - plate_height
        renderer.rect((x, plate_top), (w, plate_height), fill=COLOUR_CONTROLS_BAR_PLATE)
        for index, row in enumerate(rows):
            renderer.text(
                row,
                fill=COLOUR_CONTROLS_BAR,
                scale=CONTROLS_BAR_FONT_SCALE * scale,
                align="centre",
                valign="centre",
                rect=(x, plate_top + padding + index * line, w, line),
            )

    def _draw_warp_ring(self, renderer, rect, cx: float, cy: float, scale: float) -> None:
        if not self._warp_active or not self.is_element_visible(HudElements.WARP_SPOOL):
            return
        closed = self.warp_spool_fraction
        outer = WARP_RING_START_RADIUS_PX * scale
        inner = ARC_RADIUS_PX * scale
        radius = outer + (inner - outer) * closed
        if self._warp_stutter > 0.0:
            radius += (
                self._warp_stutter
                * WARP_STUTTER_AMPLITUDE_PX
                * scale
                * math.sin(self._elapsed * WARP_STUTTER_HZ * math.tau)
            )
        radius = max(1.0, radius)
        renderer.circle((cx, cy), radius, stroke=COLOUR_WARP_RING, segments=64)
        self._draw_warp_label(renderer, rect, cx, cy, radius, scale)

    def _warp_label_top(
        self, rect, cy: float, radius: float, scale: float, lines: int, *, standing_only: bool = False
    ) -> float:
        """Where the ring's own caption starts, clear of the standing lines.

        The caption rides the ring inward, so the row it lands on changes every
        frame and sweeps straight through the band under the hull on the way,
        where ``ICE FIELD for 15 fuel`` written through
        ``LOW FUEL: depots sell fuel cells`` leaves neither readable. It is
        pushed outward rather than in, because inward is the hull, the gauge
        ring and every reading on it. Outward is empty screen.

        *standing_only* leaves the ending's own name out of what is stepped
        around, which is what the ending's name has to ask for: it is in the
        occupancy itself, and a line that steps around itself walks off the
        bottom of the screen.
        """
        top = cy + radius + WARP_LABEL_GAP_PX * scale
        block = WARP_LABEL_LINE_PX * scale * lines
        gap = MESSAGE_ROW_GAP_PX * scale
        # Outward in order, so a push clear of one band is tested against the
        # next one out before it is used.
        bands = self._standing_bands(rect, scale) if standing_only else self._band_occupancy(rect, scale)
        for band_top, band_bottom in bands:
            if top < band_bottom + gap and top + block > band_top - gap:
                top = band_bottom + gap
        return top

    def _draw_warp_label(self, renderer, rect, cx: float, cy: float, radius: float, scale: float) -> None:
        """Say what the ring is: the drive, the destination, the price, the abort.

        A closing circle is a countdown to nothing until it is named. The
        lines sit under the ring so they travel inward with it and never cross
        the hull in the middle, stepping outward past whatever standing line
        the ring's own radius has put them in (:meth:`_warp_label_top`).
        """
        line = WARP_LABEL_LINE_PX * scale
        lines = [WARP_LABEL]
        if self._warp_target:
            quoted = self.warp_price
            price = WARP_LABEL_PRICE.format(price=quoted) if quoted else ""
            lines.append(f"{self._warp_target}{price}")
        lines.append(WARP_ABORT_HINT)
        top = self._warp_label_top(rect, cy, radius, scale, len(lines))
        for index, text in enumerate(lines):
            renderer.text(
                text,
                fill=COLOUR_WARP_RING,
                scale=WARP_LABEL_FONT_SCALE * scale,
                align="centre",
                valign="centre",
                rect=(cx - 200.0 * scale, top + index * line, 400.0 * scale, line),
            )
        if self._warp_interrupt_remaining <= 0.0:
            return
        renderer.text(
            self._warp_interrupt_text,
            fill=_with_alpha(COLOUR_WARNING, min(1.0, self._warp_interrupt_remaining / TOAST_FADE_S)),
            scale=WARP_INTERRUPT_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(cx - 200.0 * scale, cy - radius - WARP_LABEL_GAP_PX * scale - line, 400.0 * scale, line),
        )

    def _warp_outcome_radius(self, scale: float) -> float:
        """The radius the ending flash holds: where the ring was when it stopped."""
        outer = WARP_RING_START_RADIUS_PX * scale
        inner = ARC_RADIUS_PX * scale
        return max(1.0, outer + (inner - outer) * self._warp_outcome_fraction)

    def warp_outcome_row(self, rect, scale: float) -> tuple[float, float] | None:
        """Top and bottom of the ending's name, or None when no ending is flashing.

        The flash and the answer line are both transient, both centred and both
        raised by the same key press, and neither knows about the other, so a
        refusal can put the toast plate's top edge through the bottom half of
        ``SPOOL ABORTED``. This is what carries the name into
        :meth:`_band_occupancy`, so the message row steps around it exactly as
        it steps around a standing line.
        """
        if self._warp_outcome_remaining <= 0.0 or not self._warp_outcome_text:
            return None
        if not self.is_element_visible(HudElements.WARP_SPOOL):
            return None
        _cx, cy = self._ship_screen_position(rect)
        top = self._warp_label_top(rect, cy, self._warp_outcome_radius(scale), scale, 1, standing_only=True)
        return (top, top + WARP_LABEL_LINE_PX * scale)

    def _draw_warp_outcome(self, renderer, rect, cx: float, cy: float, scale: float) -> None:
        """Hold the ring in red on the ending it just had, and name it.

        Drawn where the ring was when it stopped, so the flash reads as that
        ring failing rather than as a new element appearing from nowhere. The
        name under it steps outward past the standing lines the way the live
        ring's caption does, and the answer line steps around the name.
        """
        row = self.warp_outcome_row(rect, scale)
        if row is None:
            return
        radius = self._warp_outcome_radius(scale)
        alpha = min(1.0, self._warp_outcome_remaining / WARP_OUTCOME_FLASH_S)
        colour = _with_alpha(COLOUR_WARP_FAILED, alpha)
        renderer.circle((cx, cy), radius, stroke=colour, segments=64)
        renderer.text(
            self._warp_outcome_text,
            fill=colour,
            scale=WARP_LABEL_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(cx - 260.0 * scale, row[0], 520.0 * scale, row[1] - row[0]),
        )

    def _draw_jump_flash(self, renderer, rect) -> None:
        """White out the screen for the instant the drive actually jumps."""
        if self._warp_jump_flash <= 0.0 or not self.is_element_visible(HudElements.WARP_SPOOL):
            return
        x, y, w, h = rect
        alpha = WARP_JUMP_FLASH_ALPHA * min(1.0, self._warp_jump_flash / WARP_JUMP_FLASH_S)
        renderer.rect((x, y), (w, h), fill=_with_alpha(COLOUR_JUMP_FLASH, alpha))

    def _draw_interact_fill(self, renderer, cx: float, cy: float, scale: float) -> None:
        if self._interact_fraction <= 0.0 or not self.is_element_visible(HudElements.INTERACT_FILL):
            return
        _draw_arc(
            renderer,
            cx,
            cy,
            INTERACT_FILL_RADIUS_PX * scale,
            -90.0,
            360.0 * self._interact_fraction,
            ARC_THICKNESS_PX * scale,
            COLOUR_INTERACT,
        )

    def _top_left_readouts(self) -> list[str]:
        """The corner stack above the notoriety line, top down.

        The hold is not here: it is in the strip under the ring, where it is
        read at a glance beside the fuel it competes with. Two copies of one
        number is one copy too many, and the corner is the one a pilot never
        looks at.
        """
        if not self.is_element_visible(HudElements.NOTORIETY):
            return []
        return [f"NOTORIETY {self._notoriety}"]

    def _bottom_left_readouts(self) -> list[str]:
        """The power postures standing in the bottom corner, top down.

        Ammunition is not here either: it is a cell in the strip, beside the
        other numbers the run spends, for the same reason the hold is there.
        """
        lines: list[str] = []
        if self.is_element_visible(HudElements.GENERATOR) and self._generator_running:
            lines.append("GENERATOR")
        if self.is_element_visible(HudElements.SILENT_RUNNING) and self._silent_running:
            lines.append("SILENT RUNNING")
        return lines

    def _bottom_left_base(self, rect, scale: float) -> float:
        """The top of the bottom-left readout stack.

        The controls strip owns the bottom edge whenever it is up, so the stack
        starts above its band rather than through it.
        """
        _x, y, _w, h = rect
        floor = CONTROLS_BAR_BAND_PX if self.controls_bar else 0.0
        return (
            y
            + h
            - READOUT_MARGIN_PX * scale
            - floor * scale
            - READOUT_LINE_HEIGHT_PX * scale * len(self._bottom_left_readouts())
        )

    def _draw_readouts(self, renderer, rect, scale: float) -> None:
        x, y, _w, _h = rect
        margin = READOUT_MARGIN_PX * scale
        line = READOUT_LINE_HEIGHT_PX * scale
        font = READOUT_FONT_SCALE * scale

        for index, text in enumerate(self._top_left_readouts()):
            renderer.text(text, (x + margin, y + margin + index * line), fill=COLOUR_READOUT, scale=font)

        base = self._bottom_left_base(rect, scale)
        for index, text in enumerate(self._bottom_left_readouts()):
            renderer.text(text, (x + margin, base + index * line), fill=COLOUR_READOUT, scale=font)

    def status_band_top(self, rect, scale: float) -> float:
        """The topmost pixel the ship's own status band occupies.

        The affordance line, the signature reading and the gauge ring are the
        ship's band, and nothing in the top band may be drawn over them. A
        pilot flying with the mouse high rides the aim lead and puts the hull
        near the top of the screen, which is exactly when a fixed tutorial card
        would land on ``SIGNATURE LOCKED``.
        """
        _x, _y, _w, _h = rect
        _cx, cy = self._ship_screen_position(rect)
        top = cy - ARC_RADIUS_PX * scale
        if self.is_element_visible(HudElements.SIGNATURE):
            top = min(top, cy - SIGNATURE_GAUGE_TOP_PX * scale)
        if self.affordance and self.is_element_visible(HudElements.AFFORDANCE):
            top = min(
                top,
                cy - (SIGNATURE_GAUGE_TOP_PX + AFFORDANCE_GAP_PX) * scale - AFFORDANCE_LINE_PX * scale,
            )
        return top

    def _top_band_ceiling(self, rect, scale: float) -> float:
        """The lowest pixel the top band may reach: the status band, or a stamp.

        A message that has been pushed above the ship's cluster because the
        stack under the hull was full raises the ceiling too, so the card yields
        to the answer rather than being written over it.
        """
        x, y, w, h = rect
        del x, w
        ceiling = self.status_band_top(rect, scale)
        if self._stamp_remaining > 0.0 and self.is_element_visible(HudElements.STAMP):
            ceiling = min(ceiling, y + h * STAMP_TOP_FRACTION)
        if self._message_in_top_band(rect, scale):
            ceiling = min(ceiling, self.message_row(rect, scale) - MESSAGE_ROW_GAP_PX * scale)
        return ceiling

    def control_card_layout(self, rect, scale: float) -> CardLayout | None:
        """Where the control card fits, or None when there is no card up.

        The card yields in three steps rather than overprinting: it moves up,
        then it drops its hint line, then it shrinks to a compact title. The
        ship's status band never moves for it, because a reading that moves
        when a tutorial appears is a reading the pilot has to find again.

        An arrival card holds the same slot for its two and a half seconds and
        the lesson waits: two panels sharing one band would overprint
        each other, and a lesson that has been up for a minute can
        stand to be off screen while the sector is named.
        """
        if not self._card_text or not self.is_element_visible(HudElements.CONTROL_CARD):
            return None
        if self._arrival_remaining > 0.0 and self.is_element_visible(HudElements.ARRIVAL_CARD):
            return None
        x, y, w, h = rect
        preferred = y + h * CONTROL_CARD_TOP_FRACTION
        minimum = y + CONTROL_CARD_MIN_TOP_PX * scale
        ceiling = self._top_band_ceiling(rect, scale) - CONTROL_CARD_CLEARANCE_PX * scale

        hint = CONTROL_CARD_HINT_LINE_HEIGHT_PX * scale if self._card_hint else 0.0
        forms = (
            (CONTROL_CARD_PADDING_PX, CONTROL_CARD_LINE_HEIGHT_PX, CONTROL_CARD_FONT_SCALE, hint),
            (CONTROL_CARD_PADDING_PX, CONTROL_CARD_LINE_HEIGHT_PX, CONTROL_CARD_FONT_SCALE, 0.0),
            (CONTROL_CARD_COMPACT_PADDING_PX, CONTROL_CARD_COMPACT_LINE_PX, CONTROL_CARD_COMPACT_FONT_SCALE, 0.0),
        )
        bar = 0.0 if self._card_progress is None else (CONTROL_CARD_BAR_HEIGHT_PX + CONTROL_CARD_BAR_GAP_PX) * scale
        chosen = None
        for padding_px, line_px, font, second in forms:
            padding = padding_px * scale
            line = line_px * scale
            width = min(w - 2.0 * padding, CONTROL_CARD_WIDTH_PX * scale)
            height = line + second + bar + 2.0 * padding
            top = min(preferred, ceiling - height)
            chosen = CardLayout(
                x=x + (w - width) * 0.5,
                y=max(minimum, top),
                width=width,
                height=height,
                padding=padding,
                line=line,
                font_scale=font,
                second_line=second,
                second_font_scale=CONTROL_CARD_HINT_FONT_SCALE,
                bar=bar,
            )
            if top >= minimum:
                break
        if chosen is not None and chosen.bottom > ceiling:
            # Nothing fits. A lesson that cannot be drawn without covering the
            # hull's own readings steps aside entirely and comes back the
            # moment the aim lead lets the hull down the screen again: the
            # readings are what keep the pilot alive, and the card is not.
            return None
        return chosen

    def arrival_card_layout(self, rect, scale: float) -> CardLayout | None:
        """Where the arrival title card fits, or None when it is not showing.

        It owns the top band for its two and a half seconds and yields the same
        way the control card does: it drops its flavour line first and then
        rides up, so it never lands on the ship's own readings.
        """
        if self._arrival_remaining <= 0.0 or not self.is_element_visible(HudElements.ARRIVAL_CARD):
            return None
        x, y, w, h = rect
        preferred = y + h * ARRIVAL_CARD_TOP_FRACTION
        minimum = y + CONTROL_CARD_MIN_TOP_PX * scale
        ceiling = self._top_band_ceiling(rect, scale) - CONTROL_CARD_CLEARANCE_PX * scale

        line = ARRIVAL_CARD_LINE_PX * scale
        flavour = ARRIVAL_CARD_FLAVOUR_LINE_PX * scale if self._arrival_flavour else 0.0
        chosen = None
        for second in (flavour, 0.0):
            height = line + second
            top = min(preferred, ceiling - height)
            chosen = CardLayout(
                x=x,
                y=max(minimum, top),
                width=w,
                height=height,
                padding=0.0,
                line=line,
                font_scale=ARRIVAL_CARD_FONT_SCALE,
                second_line=second,
                second_font_scale=ARRIVAL_CARD_FLAVOUR_FONT_SCALE,
            )
            if top >= minimum:
                break
        return None if chosen is not None and chosen.bottom > ceiling else chosen

    def _draw_control_card(self, renderer, rect, scale: float) -> None:
        """Draw the lesson panel: centred, boxed, and in type you cannot miss.

        It sits in the upper band of the screen rather than on the centre, so
        the panel never covers the ship or the gauge ring around it, and it
        yields (:meth:`control_card_layout`) rather than overprinting when the
        hull rides high enough to bring its own band up into the same pixels.
        """
        layout = self.control_card_layout(rect, scale)
        if layout is None:
            return
        renderer.rect((layout.x, layout.y), (layout.width, layout.height), fill=COLOUR_CONTROL_CARD_PANEL)
        renderer.rect((layout.x, layout.y), (layout.width, layout.height), stroke=COLOUR_CONTROL_CARD_EDGE)
        inner = layout.width - 2.0 * layout.padding
        renderer.text(
            self._card_text,
            fill=COLOUR_CONTROL_CARD_TEXT,
            scale=layout.font_scale * scale,
            align="centre",
            valign="centre",
            rect=(layout.x + layout.padding, layout.y + layout.padding, inner, layout.line),
            fit_to_width=True,
            min_scale=CONTROL_CARD_MIN_FONT_SCALE * scale,
        )
        if layout.shows_second_line:
            renderer.text(
                self._card_hint,
                fill=COLOUR_CONTROL_CARD_HINT,
                scale=layout.second_font_scale * scale,
                align="centre",
                valign="centre",
                rect=(
                    layout.x + layout.padding,
                    layout.y + layout.padding + layout.line,
                    inner,
                    layout.second_line,
                ),
                fit_to_width=True,
                min_scale=CONTROL_CARD_MIN_FONT_SCALE * 0.7 * scale,
            )
        if layout.bar > 0.0 and self._card_progress is not None:
            height = CONTROL_CARD_BAR_HEIGHT_PX * scale
            top = layout.bottom - layout.padding - height
            renderer.rect((layout.x + layout.padding, top), (inner, height), fill=COLOUR_CONTROL_CARD_BAR_TRACK)
            filled = inner * _clamp01(self._card_progress)
            if filled > 0.0:
                renderer.rect((layout.x + layout.padding, top), (filled, height), fill=COLOUR_CONTROL_CARD_BAR)

    def _draw_arrival_card(self, renderer, rect, scale: float) -> None:
        """Name the place the ship has just arrived in, once, in large type."""
        layout = self.arrival_card_layout(rect, scale)
        if layout is None:
            return
        alpha = min(1.0, self._arrival_remaining / ARRIVAL_CARD_FADE_S)
        renderer.text(
            self._arrival_name,
            fill=_with_alpha(COLOUR_ARRIVAL_CARD, alpha),
            scale=layout.font_scale * scale,
            align="centre",
            valign="centre",
            rect=(layout.x, layout.y, layout.width, layout.line),
        )
        if layout.shows_second_line:
            renderer.text(
                self._arrival_flavour,
                fill=_with_alpha(COLOUR_ARRIVAL_FLAVOUR, alpha),
                scale=layout.second_font_scale * scale,
                align="centre",
                valign="centre",
                rect=(layout.x, layout.y + layout.line, layout.width, layout.second_line),
            )

    def _draw_sector_name(self, renderer, rect, scale: float) -> None:
        """The standing sector name, top right, opposite the scrap stack."""
        if not self._sector_name or not self.is_element_visible(HudElements.SECTOR):
            return
        x, y, w, _h = rect
        margin = READOUT_MARGIN_PX * scale
        line = SECTOR_NAME_LINE_PX * scale
        width = SECTOR_NAME_BOX_PX * scale
        renderer.text(
            self._sector_name,
            fill=COLOUR_READOUT,
            scale=SECTOR_NAME_FONT_SCALE * scale,
            align="right",
            valign="centre",
            rect=(x + w - margin - width, y + margin, width, line),
        )

    def _draw_frame_stats(self, renderer, rect, scale: float) -> None:
        """The developer readout, top left, over everything and under nothing.

        Not subject to the onboarding subtraction schedule and not a HUD element:
        it is a measuring instrument, so it appears exactly when it is asked for.
        """
        lines = self.frame_stats_lines() if self._frame_stats else ()
        if not lines:
            return
        x, y, _w, _h = rect
        margin = READOUT_MARGIN_PX * scale
        line = FRAME_STATS_LINE_PX * scale
        width = FRAME_STATS_WIDTH_PX * scale
        renderer.rect(
            (x + margin - 6.0 * scale, y + margin - 4.0 * scale),
            (width + 12.0 * scale, line * len(lines) + 8.0 * scale),
            fill=COLOUR_FRAME_STATS_PLATE,
        )
        for index, text in enumerate(lines):
            renderer.text(
                text,
                fill=COLOUR_FRAME_STATS,
                scale=FRAME_STATS_FONT_SCALE * scale,
                align="left",
                valign="centre",
                rect=(x + margin, y + margin + index * line, width, line),
            )

    def _draw_subtitles(self, renderer, rect, scale: float) -> None:
        """The caption track: the sounds, on their own plate, at the bottom.

        The plate is not decoration. Unbacked captions over a star field read
        as debug output that shipped. A dark strip behind the words is the
        convention that says "this
        is the caption track", and the speaker glyphs say "this is a sound".
        """
        if not self._subtitles or not self.is_element_visible(HudElements.SUBTITLES):
            return
        x, y, w, h = rect
        line = SUBTITLE_LINE_HEIGHT_PX * scale
        base = y + h - SUBTITLE_BOTTOM_MARGIN_PX * scale - line * len(self._subtitles)

        widest = max(self._subtitles, key=lambda entry: len(entry[0]))[0]
        plate_width = _plate_width(widest, SUBTITLE_FONT_SCALE, scale, SUBTITLE_PLATE_PADDING_X_PX, w)
        plate_padding = SUBTITLE_PLATE_PADDING_Y_PX * scale
        renderer.rect(
            (x + (w - plate_width) * 0.5, base - plate_padding),
            (plate_width, line * len(self._subtitles) + 2.0 * plate_padding),
            fill=COLOUR_SUBTITLE_PLATE,
        )
        for index, (text, remaining) in enumerate(self._subtitles):
            colour = _with_alpha(COLOUR_SUBTITLE, min(1.0, remaining / 0.4))
            renderer.text(
                text,
                fill=colour,
                scale=SUBTITLE_FONT_SCALE * scale,
                align="centre",
                valign="centre",
                rect=(x, base + index * line, w, line),
            )

    def _draw_stamp(self, renderer, rect, scale: float) -> None:
        if self._stamp_remaining <= 0.0 or not self.is_element_visible(HudElements.STAMP):
            return
        x, y, w, h = rect
        renderer.text(
            self._stamp_text,
            fill=_with_alpha(COLOUR_STAMP, min(1.0, self._stamp_remaining / STAMP_FADE_S)),
            scale=STAMP_FONT_SCALE * scale,
            align="centre",
            valign="centre",
            rect=(x, y + h * STAMP_TOP_FRACTION, w, h * STAMP_HEIGHT_FRACTION),
        )