shrike/chart.py

Part of SHRIKE.

"""The star chart: a branching route eaten from behind, and the warp that pays for it.

Two things live here. :class:`ChartGraph` is the run's map as pure data: 14 to
18 nodes laid out in columns across three acts, every edge carrying its honest
fuel price and whether a drift depot sits on it, and a red Wake front that eats
one column roughly every two jumps. :class:`StarChart` is the full-screen pause
screen that draws it and drives the warp.

**Every line runs both ways.** The generator shapes a forward fan and then
mirrors it, so a charted route can be flown back down at the ordinary price.
That is what makes the Wake front matter: a map you can only walk forward
through is already safe from farming by its own geometry, and a red band behind
such a pilot is decoration. Backtracking is a loan rather than a savings
account, and the front is what charges the interest. A column the front has
taken is still a destination and still priced; what it costs is charged on
arrival (the run scene starts the meter high and the Shrike's warning short),
and the screen says so before the fuel is spent. The front is clamped to the
pilot's own column, so it can close on the ground under their feet but can
never eat the Deep Gate out in front of them.

Honesty is the whole design of this screen. Every destination shows what it is
before you pay for it: its biome, what it is rich and poor in, whether a depot
sits on the way, what the jump costs, and how many jumps remain before the Wake
takes each of the next :data:`~shrike.balance.WAKE_PREVIEW_ADVANCES` columns.
Nothing is revealed on arrival that could have been shown here.

The warp prices, all from ``balance``:

* ``WARP_FUEL_BASE`` for a jump to the next column, plus
  ``WARP_FUEL_PER_COLUMN_SKIPPED`` for each column the edge leaps over.
* ``EMERGENCY_WARP_FUEL_MULT`` on the lot while the hunter is in the sector:
  the panic button is priced, not free.
* ``DEEP_GATE_TOLL`` on top for the jump through the Deep Gate, which is the
  extraction itself and so quotes the toll in the same price the pilot reads.

Honesty runs to what the map must contain as well as to what it shows: a run
cannot be dealt a chart with no air on it, so :data:`O2_GUARANTEE_COLUMNS`
columns in there is always a reachable Ice Field or Vent Field.

It runs to the names too. A chart deals a biome three or four times, so the
biome cannot be what a sector is *called*: every node gets a name no other node
on the chart answers to (:meth:`ChartGraph._name_nodes`), and that name is what
the boxes, the jump button, the warnings and the arrival card all print.
Otherwise "JUMP: SOLAR SHALLOWS, 15 FUEL" names three destinations at once, one
of them swept and one of them the sector the pilot just left.

The channel is the ship's: :class:`StarChart` calls ``begin_warp_spool`` and
banks the fuel only when ``warp_completed`` fires, so a spool broken by fire (
``balance.WARP_SPOOL_PENALTY_PER_HIT_S`` per hit) costs nothing but the time.
A committed route lives exactly as long as its channel: any ending releases it,
and a channel that outlives the fuel to pay for it refuses the jump out loud
rather than arriving somewhere for free.

Run state is read, not owned. :meth:`StarChart.open` takes whatever object the
run scene uses for it and reads ``chart``, ``current_node_id`` and
``jumps_taken`` off it, writing the last two back when a jump completes.
"""

from __future__ import annotations

import math
import random
from collections import Counter
from dataclasses import dataclass, field

from simvx.core import AnchorPreset, Control, Input, Property, Signal, UpdateMode

from . import balance
from .hud import GLYPH_ADVANCE_FRACTION, TEXT_EM_PX
from .runtime import Groups, Services
from .ship import SPOOL_FAILURE_NO_FUEL

# ============================================================================
# Local constants
#
# balance.py owns what changes how the game plays. The generator shape below
# and the pixel geometry further down are this module's own business.
# ============================================================================

#: Chance that a node also gets an edge leaping the next column entirely. Skip
#: edges are what make ``WARP_FUEL_PER_COLUMN_SKIPPED`` a live decision rather
#: than a rule with no instances.
SKIP_EDGE_CHANCE = 0.35

#: The first column is the arrival node and the last is the Deep Gate; every
#: column between them is this wide before the generator widens some of them.
COLUMN_WIDTH_MIN = 2
COLUMN_WIDTH_MAX = 3

#: Biomes the deck may deal per act. Act 1 is the deep breath, so it stays on
#: the gentle three; the Broker Claim is dealt at most once and never in Act 1.
ACT_BIOME_POOL: dict[int, tuple[str, ...]] = {
    1: ("debris_field", "solar_shallows", "ice_field"),
    2: ("debris_field", "solar_shallows", "ice_field", "nebula", "wreck_graveyard", "vent_field"),
    3: ("nebula", "wreck_graveyard", "vent_field", "debris_field", "ice_field"),
}

#: Biomes whose sectors grow breathable ice or vent it. Reading a chart for
#: air means reading for one of these, and the generator guarantees one.
O2_BIOMES: tuple[str, ...] = ("ice_field", "vent_field")
#: How deep the air guarantee reaches: every seed puts a reachable O2 biome no
#: further out than this column. A tank is 400 seconds and a sector is not far
#: short of that, so a map that deals three dry columns is a map that kills a
#: pilot who did nothing wrong.
O2_GUARANTEE_COLUMNS = balance.CHART_O2_GUARANTEE_COLUMNS

#: Short, honest labels for what a node holds. Drawn on the node itself.
ICON_SCRAP_RICH = "SCRAP++"
ICON_SCRAP_POOR = "SCRAP-"
ICON_SOLAR = "SOLAR"
ICON_NO_SOLAR = "DARK"
ICON_O2 = "O2"
ICON_FUEL = "FUEL"
ICON_VAULT = "VAULT"
ICON_MUFFLED = "MUFFLED"
ICON_BROKER = "BROKER"
ICON_GATE = "GATE"
ICON_ROOST = "ROOST"

ACT_LABELS = {1: "THE SHALLOWS", 2: "THE CLAIMS", 3: "THE DEEP"}

ROOST_NODE_ID = "roost"

#: Roman numerals, largest first, for the suffix that tells two sectors of the
#: same biome apart. A chart deals at most ``balance.CHART_NODES_MAX`` nodes,
#: so the ladder never has to climb far, but it is written as a real converter
#: rather than a table because a table is a thing that runs out in silence.
ROMAN_STEPS: tuple[tuple[int, str], ...] = ((10, "X"), (9, "IX"), (5, "V"), (4, "IV"), (1, "I"))


# ============================================================================
# Screen geometry and palette (presentation, in pixels at UI scale 1.0)
# ============================================================================

PANEL_MARGIN_PX = 46.0
FOOTER_HEIGHT_PX = 52.0
NODE_WIDTH_PX = 132.0
NODE_HEIGHT_PX = 74.0
NODE_LINE_HEIGHT_PX = 15.0
NODE_FONT_SCALE = 0.8
#: How far the node's rows are inset from its box, each side. A nine-column
#: chart leaves no gap at all between boxes, so a name that overruns its own
#: box is a name printed into the next sector's; the name row is set smaller
#: to fit rather than allowed to spill.
NODE_TEXT_INSET_PX = 6.0
HEADER_FONT_SCALE = 1.25
LABEL_FONT_SCALE = 0.85
EDGE_THICKNESS_PX = 2.0
SELECTED_THICKNESS_PX = 3.0
DEPOT_MARKER_RADIUS_PX = 6.0
#: The wake preview label's plate, sized for "TAKEN IN N" at the label scale.
WAKE_LABEL_WIDTH_PX = 104.0
WAKE_LABEL_HEIGHT_PX = 20.0
#: The renderer stacks lines of type on this pitch over :data:`hud.TEXT_EM_PX`,
#: so a drawn row occupies :func:`text_line_px` and the row under it starts
#: there. The header band's three rows are derived from that rather than
#: measured by eye: set by hand they overlapped by two pixels at each seam, so
#: the one sentence on this screen that says what the red band is arrived with
#: its ascenders in the title and its descenders under the preview plates,
#: illegible on the only screen that ever explains the mark.
TEXT_LINE_PITCH = 1.2


def text_line_px(font_scale: float) -> float:
    """The height one drawn row of type occupies at *font_scale*, at UI scale 1."""
    return TEXT_EM_PX * TEXT_LINE_PITCH * float(font_scale)


def text_width_px(text: str, font_scale: float) -> float:
    """How wide *text* draws at *font_scale*, in the renderer's own advance."""
    return len(str(text)) * TEXT_EM_PX * GLYPH_ADVANCE_FRACTION * float(font_scale)


def fitted_font_scale(text: str, font_scale: float, width: float) -> float:
    """*font_scale*, shrunk just enough that *text* draws no wider than *width*."""
    drawn = text_width_px(text, font_scale)
    if drawn <= 0.0 or width <= 0.0:
        return float(font_scale)
    return float(font_scale) * min(1.0, width / drawn)


#: The header band, top down: the title, the legend, and the preview plates at
#: its foot. Each row starts where the one above it ends.
HEADER_TITLE_OFFSET_PX = 8.0
LEGEND_OFFSET_PX = HEADER_TITLE_OFFSET_PX + text_line_px(HEADER_FONT_SCALE)
HEADER_HEIGHT_PX = LEGEND_OFFSET_PX + text_line_px(LABEL_FONT_SCALE) + WAKE_LABEL_HEIGHT_PX
#: The footer's jump button: the mouse's way to commit, and the label that
#: names what committing costs.
CONFIRM_WIDTH_PX = 300.0
CONFIRM_HEIGHT_PX = 30.0
#: Seconds a refusal stays on the chart's own status line. The screen answers
#: its own clicks: a HUD toast under this backdrop is a sentence in the dark.
STATUS_HOLD_S = 3.5

#: The cursor's keys. WASD is the flight grip the hands are already in; the
#: menu actions are the arrows every other screen in the game advertises as
#: "W/S OR ARROWS", and a chart that took only WASD was the one screen where
#: that sentence was false. Both halves of the arrow block are read, because
#: the footer offers the block whole: a map is walked sideways as readily as
#: it is walked down, and Left and Right sitting dead beside a working Up and
#: Down answers half of what the footer advertises. Tab is the tractor scoop
#: and means nothing here, so it stays unbound and the footer does not offer
#: it.
CYCLE_FORWARD_ACTIONS = ("thrust_down", "thrust_right", "menu_down", "menu_right")
CYCLE_BACK_ACTIONS = ("thrust_up", "thrust_left", "menu_up", "menu_left")
CONFIRM_ACTIONS = ("interact", "menu_confirm")

#: The footer, in keys rather than in verbs. A player who has only ever seen
#: this screen cannot map "JUMP: INTERACT" onto a keyboard, which is what the
#: blind playtest read off it and then closed the chart. It names every key
#: that works and no key that does not, on its own row; the row under it says
#: what the screen does rather than what it takes. One row carrying both ran
#: wider than the slot it is centred in, so whatever was added to it was paid
#: for by the clauses at either end.
FOOTER_HINT = "MOVE: WASD OR ARROWS   JUMP: F OR ENTER   CLOSE: M   CLICK TO SELECT, CLICK AGAIN TO JUMP"
#: The order the keys walk the offer sheet in, said rather than learned by
#: pressing. The cursor runs the ways deeper first and the ways back last (see
#: :meth:`StarChart._cursor_order`), which is why one press backwards from the
#: opening selection lands on the lane home; a pilot who has not been told that
#: reads their first press as landing somewhere arbitrary.
FOOTER_HINT_SECOND = "CURSOR RUNS DEEPER FIRST, THEN BACK   EVERY LINE RUNS BOTH WAYS"
FOOTER_STRANDED = "NO AFFORDABLE JUMP   LAST STAND"
#: The one line naming what the red band is, under the header, on the only
#: screen that ever shows it. Without it a player reads a red rectangle
#: creeping up behind them, two orange countdowns to something unnamed, and no
#: reason to believe any of it is theirs to act on.
WAKE_LEGEND = "RED IS THE SHRIKE'S SWEPT GROUND: STILL YOURS TO JUMP INTO, BUT THE HUNT STARTS HOT THERE"
#: The jump button's four states.
CONFIRM_LABEL = "JUMP: {label}, {fuel:.0f} FUEL"
CONFIRM_LABEL_WAKE = "JUMP: {label}, {fuel:.0f} FUEL, SHRIKE TERRITORY"
CONFIRM_LABEL_EMPTY = "PICK A SECTOR"
CONFIRM_LABEL_SHORT = "NEEDS {fuel:.0f} FUEL"
#: What a click on a sector the drive cannot take is answered with.
STATUS_NO_ROUTE = "NO ROUTE THERE FROM HERE: PICK A SECTOR THE LINES REACH"
STATUS_UNAFFORDABLE = "NOT ENOUGH FUEL: NEEDS {need:.0f}, YOU HAVE {have:.0f}"
#: The warning a red destination earns, before any fuel is spent on it. The
#: Wake used to refuse the jump outright with "THE WAKE HAS EATEN THAT SECTOR",
#: which was a sentence about a state the generator could not reach.
#: It leads with the name, because the chart deals four Solar Shallows and the
#: warning is about exactly one of them.
STATUS_WAKE_TERRITORY = "{label}: SHRIKE TERRITORY, IT IS WAITING THERE. F OR ANOTHER CLICK JUMPS ANYWAY"
STATUS_SELECTED = "{label} SELECTED: F OR ANOTHER CLICK JUMPS"
#: What the node's price row says instead of a fuel figure once the front has
#: been through, and what the preview lines count down to.
NODE_PRICE_WAKE = "FUEL {fuel:.0f}, SHRIKE"
WAKE_PREVIEW_LABEL = "TAKEN IN {jumps}"

COLOUR_BACKDROP = (0.02, 0.03, 0.05, 0.92)
COLOUR_PANEL = (0.07, 0.09, 0.13, 0.95)
COLOUR_NODE = (0.12, 0.15, 0.21, 0.95)
COLOUR_NODE_CURRENT = (0.20, 0.32, 0.40, 0.95)
COLOUR_NODE_CONSUMED = (0.26, 0.05, 0.05, 0.95)
COLOUR_EDGE = (0.38, 0.44, 0.55, 0.75)
COLOUR_EDGE_REACHABLE = (0.62, 0.86, 1.00, 0.95)
COLOUR_EDGE_UNAFFORDABLE = (0.45, 0.30, 0.30, 0.80)
COLOUR_SELECTED = (1.00, 0.86, 0.42, 1.00)
COLOUR_TEXT = (0.84, 0.88, 0.95, 0.95)
COLOUR_TEXT_DIM = (0.55, 0.60, 0.70, 0.90)
COLOUR_WAKE = (0.72, 0.09, 0.08, 0.55)
COLOUR_WAKE_PREVIEW = (0.86, 0.32, 0.16, 0.85)
COLOUR_DEPOT = (0.55, 1.00, 0.78, 0.95)
COLOUR_BROKER = (0.90, 0.55, 1.00, 0.95)


# ============================================================================
# Chart data
# ============================================================================


def _rect_holds(rect: tuple[float, float, float, float], x: float, y: float) -> bool:
    """Whether a drawn rect contains a screen point."""
    rx, ry, rw, rh = rect
    return rw > 0.0 and rh > 0.0 and rx <= x <= rx + rw and ry <= y <= ry + rh


def _any_just_pressed(actions: tuple[str, ...]) -> bool:
    """Whether any of *actions* went down this frame."""
    return any(Input.is_action_just_pressed(action) for action in actions)


@dataclass(frozen=True)
class ChartEdge:
    """One route between two chart nodes.

    ``columns_skipped`` is how many whole columns the edge leaps over, which is
    what ``balance.WARP_FUEL_PER_COLUMN_SKIPPED`` charges for. ``depot`` marks
    the drift depot sitting on the way; ``broker`` marks that depot as the
    Broker barge, which only a notorious ship ever sees.
    """

    source: str
    target: str
    columns_skipped: int
    depot: bool = False
    broker: bool = False


@dataclass
class ChartNode:
    """One sector the run may visit.

    ``icons`` is the honest read: every entry is derived from the same balance
    tables the sector generator uses, so what the chart promises is what the
    sector holds.

    ``name`` is what the graph settled on once it had seen the whole chart, and
    is the only spelling any screen should print. It is left empty until the
    generator names the map, so a node built by hand still reads as its biome.
    """

    id: str
    column: int
    row: int
    act: int
    biome: str
    icons: tuple[str, ...] = ()
    scrap_estimate: int = 0
    edges: list[ChartEdge] = field(default_factory=list)
    consumed: bool = False
    is_deep_gate: bool = False
    is_roost: bool = False
    requires_notoriety: int = 0
    name: str = ""

    @property
    def base_label(self) -> str:
        """What kind of place this is, before the chart makes it tellable apart."""
        if self.is_deep_gate:
            return "DEEP GATE"
        if self.is_roost:
            return "THE ROOST"
        return self.biome.replace("_", " ").upper()

    @property
    def label(self) -> str:
        """The name drawn on the node, unique across the chart it belongs to.

        A chart deals four Solar Shallows and three Ice Fields as a matter of
        course, so "JUMP: SOLAR SHALLOWS, 15 FUEL" named three different
        destinations on one screen and the pilot could not tell which of them
        the cursor was standing on, nor that the one behind them was the one
        they had come from. Duplicates carry a roman numeral; a biome dealt
        once keeps its bare name.
        """
        return self.name or self.base_label


@dataclass(frozen=True)
class WarpQuote:
    """The whole price of one jump, itemised the way the screen shows it."""

    source: str
    target: str
    columns_skipped: int
    base: float
    skip_surcharge: float
    emergency: bool
    toll: float

    @property
    def total(self) -> float:
        """Fuel the jump actually costs, tolls and emergency premium included."""
        drive = (self.base + self.skip_surcharge) * (balance.EMERGENCY_WARP_FUEL_MULT if self.emergency else 1.0)
        return drive + self.toll


@dataclass(frozen=True)
class WakeAdvance:
    """One of the Wake front's coming meals, as the chart previews it."""

    column: int
    jumps_until: int


@dataclass(frozen=True)
class Destination:
    """A destination as the screen offers it: priced, gated and legible."""

    node_id: str
    quote: WarpQuote
    depot: bool
    broker_depot: bool
    affordable: bool
    consumed: bool

    @property
    def available(self) -> bool:
        """True when this jump can actually be taken right now.

        Fuel is the only thing that can refuse a route. ``consumed`` is a
        warning rather than a wall: the Wake's swept ground is jumpable, and
        the bill for it falls on arrival rather than at the till.
        """
        return self.affordable


def warp_quote(graph: ChartGraph, source_id: str, target_id: str, *, emergency: bool = False) -> WarpQuote:
    """Price the jump from *source_id* to *target_id*.

    Raises ``KeyError`` if no edge joins them: the chart never quotes a route
    the drive cannot fly.
    """
    edge = graph.edge_between(source_id, target_id)
    if edge is None:
        raise KeyError(f"no chart edge from {source_id!r} to {target_id!r}")
    target = graph.nodes[target_id]
    return WarpQuote(
        source=source_id,
        target=target_id,
        columns_skipped=edge.columns_skipped,
        base=balance.WARP_FUEL_BASE,
        skip_surcharge=balance.WARP_FUEL_PER_COLUMN_SKIPPED * edge.columns_skipped,
        emergency=bool(emergency),
        toll=balance.DEEP_GATE_TOLL if target.is_deep_gate else 0.0,
    )


class ChartGraph:
    """The run's branching map, and the Wake front eating it from behind.

    Columns are sector visits: column 0 is where the run starts, the last
    column is the Deep Gate, and a node's act follows from its column through
    ``balance.act_for_sector``. Every node fans out to
    ``balance.CHART_DESTINATIONS_MIN`` to ``MAX`` destinations, some of which
    leap a whole column for the surcharge.

    The Wake is tracked as a float column count so a rate change mid-run (the
    acceleration above ``balance.WAKE_ACCEL_NOTORIETY``) carries the fraction
    already earned. :attr:`wake_column` is the index of the last column eaten,
    and is ``-1`` before the front has taken anything.
    """

    def __init__(self, seed: int, acts: int = balance.CHART_ACTS):
        self.seed = int(seed)
        self.acts = max(1, int(acts))
        self.nodes: dict[str, ChartNode] = {}
        self.columns: list[list[str]] = []
        self.start_id = ""
        self.deep_gate_id = ""
        self.roost_id = ""

        self.wake_column = -1
        self._wake_progress = 0.0
        self._jumps_seen = 0

        self._generate(random.Random(self.seed))

    # -- generation --------------------------------------------------------

    def _generate(self, rng: random.Random) -> None:
        widths = self._column_widths(rng)
        broker_dealt = False
        for column, width in enumerate(widths):
            ids: list[str] = []
            for row in range(width):
                node_id = f"c{column}r{row}"
                act = min(self.acts, balance.act_for_sector(column + 1))
                is_gate = column == len(widths) - 1
                biome, broker_dealt = self._deal_biome(rng, act, is_gate, broker_dealt)
                node = ChartNode(
                    id=node_id,
                    column=column,
                    row=row,
                    act=act,
                    biome=biome,
                    is_deep_gate=is_gate,
                    requires_notoriety=balance.BROKER_NOTORIETY_THRESHOLD if biome == "broker_claim" else 0,
                )
                node.scrap_estimate = _scrap_estimate(act, biome)
                node.icons = _icons_for(node)
                self.nodes[node_id] = node
                ids.append(node_id)
            self.columns.append(ids)

        self.start_id = self.columns[0][0]
        self.deep_gate_id = self.columns[-1][0]
        self._link(rng)
        self._guarantee_oxygen(rng)
        self._name_nodes()

    def _column_widths(self, rng: random.Random) -> list[int]:
        """One entry per column: 1, then 2 or 3 per middle column, then 1.

        Sized so the node count always lands inside
        ``balance.CHART_NODES_MIN..MAX`` for every legal column count.
        """
        count = rng.randint(balance.RUN_SECTOR_VISITS_MIN, balance.RUN_SECTOR_VISITS_MAX)
        middles = count - 2
        widths = [1] + [COLUMN_WIDTH_MIN] * middles + [1]
        base = sum(widths)
        low = max(0, balance.CHART_NODES_MIN - base)
        high = min(middles, balance.CHART_NODES_MAX - base)
        for index in rng.sample(range(1, middles + 1), rng.randint(low, max(low, high))):
            widths[index] = COLUMN_WIDTH_MAX
        return widths

    def _deal_biome(self, rng: random.Random, act: int, is_gate: bool, broker_dealt: bool) -> tuple[str, bool]:
        if is_gate:
            return "debris_field", broker_dealt
        if act > 1 and not broker_dealt and rng.random() < balance.DEPOT_EDGE_FRACTION * 0.5:
            return "broker_claim", True
        return rng.choice(ACT_BIOME_POOL[act]), broker_dealt

    def _link(self, rng: random.Random) -> None:
        """Fan every column out to the next, then guarantee reachability.

        A generated map with an orphan column entry would silently shrink the
        run, so every node in a column takes at least one inbound edge before
        the pass finishes. The fan is the shape the chart is generated with and
        the band ``balance.CHART_DESTINATIONS_MIN..MAX`` governs; the mirror
        pass afterwards is not new map, it is the same lines read the other
        way, so :meth:`forward_edges` is what a shape assertion should ask.
        """
        for column, ids in enumerate(self.columns[:-1]):
            nxt = self.columns[column + 1]
            skippable = self.columns[column + 2] if column + 2 < len(self.columns) else []
            inbound: set[str] = set()
            for node_id in ids:
                node = self.nodes[node_id]
                fan = min(len(nxt), rng.randint(balance.CHART_DESTINATIONS_MIN, balance.CHART_DESTINATIONS_MAX))
                targets = _nearest_rows(self.nodes, nxt, node.row, fan)
                for target in targets:
                    node.edges.append(ChartEdge(node_id, target, 0))
                    inbound.add(target)
                if skippable and rng.random() < SKIP_EDGE_CHANCE:
                    leap = _nearest_rows(self.nodes, skippable, node.row, 1)[0]
                    node.edges.append(ChartEdge(node_id, leap, 1))
            for orphan in nxt:
                if orphan in inbound:
                    continue
                closest = min(ids, key=lambda source: abs(self.nodes[source].row - self.nodes[orphan].row))
                self.nodes[closest].edges.append(ChartEdge(closest, orphan, 0))

        # Depots sit on roughly half the between-node edges; a Broker barge is
        # the depot on the way into a Broker Claim, so notoriety gates the shop
        # and the route to it in one place.
        for node in self.nodes.values():
            resolved: list[ChartEdge] = []
            for edge in node.edges:
                target = self.nodes[edge.target]
                broker = target.biome == "broker_claim"
                depot = broker or rng.random() < balance.DEPOT_EDGE_FRACTION
                resolved.append(ChartEdge(edge.source, edge.target, edge.columns_skipped, depot=depot, broker=broker))
            node.edges = resolved

        self._mirror()

    def _mirror(self) -> None:
        """Run every charted line back the other way, at the same price.

        A jump is a jump: the drive does not care which end of a surveyed lane
        it enters, so a backward hop costs ``WARP_FUEL_BASE`` and the same skip
        surcharge its forward twin does, and the drift depot moored on the lane
        is passed either way. The mirror consumes no random numbers, so a seed
        still deals exactly the chart it always dealt.

        Every mirror is built from a snapshot of the forward pass, or a node
        reached later in the sweep would mirror its own inbound mirrors back
        again and double the map. The Deep Gate takes none: arriving there is
        the extraction, so no hull ever stands on it, and a lane leading out of
        it would be a lane nobody can fly.
        """
        mirrors: list[ChartEdge] = []
        for node in self.nodes.values():
            for edge in node.edges:
                if self.nodes[edge.target].is_deep_gate:
                    continue
                # The broker flag follows the *arriving* node, which is this
                # edge's source once the line is reversed.
                broker = self.nodes[edge.source].biome == "broker_claim"
                mirrors.append(
                    ChartEdge(
                        edge.target,
                        edge.source,
                        edge.columns_skipped,
                        depot=edge.depot or broker,
                        broker=broker,
                    )
                )
        for mirror in mirrors:
            self.nodes[mirror.source].edges.append(mirror)

    def forward_edges(self, node_id: str) -> list[ChartEdge]:
        """The edges of *node_id* that lead deeper, ignoring the mirrored ones.

        The generator's shape guarantees (fan width, depot frequency) are
        properties of this list rather than of :meth:`edges_from`.
        """
        node = self.nodes.get(node_id)
        if node is None:
            return []
        return [edge for edge in node.edges if self.nodes[edge.target].column > node.column]

    def _guarantee_oxygen(self, rng: random.Random) -> None:
        """Make sure air is on the map before the tank could plausibly run out.

        Dealing biomes independently per node leaves a real minority of seeds
        with no O2 biome in reach at all, and a pilot cannot mine their way out
        of that: the chart is the only place the answer could have been. So the
        nearest reachable ordinary node is re-dealt as an Ice Field, which is
        in every act's pool, and its icons are re-derived so the chart still
        promises exactly what the sector will hold. Never the start node, which
        the mirrored lines put back inside its own reachable set: air the pilot
        is already standing in is not air this guarantee is about.
        """
        reachable = self.reachable_within(O2_GUARANTEE_COLUMNS)
        if any(self.nodes[node_id].biome in O2_BIOMES for node_id in reachable):
            return
        candidates = [
            node_id
            for node_id in sorted(reachable)
            if node_id != self.start_id
            and not self.nodes[node_id].is_deep_gate
            and self.nodes[node_id].requires_notoriety == 0
        ]
        if not candidates:
            return
        nearest = min(self.nodes[node_id].column for node_id in candidates)
        chosen = self.nodes[rng.choice([n for n in candidates if self.nodes[n].column == nearest])]
        chosen.biome = O2_BIOMES[0]
        chosen.scrap_estimate = _scrap_estimate(chosen.act, chosen.biome)
        chosen.icons = _icons_for(chosen)

    def _name_nodes(self) -> None:
        """Give every node a name no other node on this chart answers to.

        The biome is what a place *is*, and a chart deals the same biome three
        or four times, so the biome alone cannot be what a place is *called*: a
        jump button reading "JUMP: SOLAR SHALLOWS, 15 FUEL" named any of three
        sectors, one of them the swept one and one of them the sector the pilot
        had just left. Duplicates take a roman numeral in column-then-row
        order, which is the order the screen draws them in, so the numbering
        reads left to right down the map. A biome dealt once keeps its bare
        name rather than being called "I" for no one's benefit.

        The order is the graph's own, not a random one, so a seed names its
        chart the same way every time it is dealt and a suspend that stores
        node ids resumes under the names it was saved with.
        """
        order = [node_id for ids in self.columns for node_id in ids]
        dealt = Counter(self.nodes[node_id].base_label for node_id in order)
        numbered: Counter[str] = Counter()
        for node_id in order:
            node = self.nodes[node_id]
            base = node.base_label
            if dealt[base] < 2:
                node.name = base
                continue
            numbered[base] += 1
            node.name = f"{base} {_roman(numbered[base])}"

    # -- topology ----------------------------------------------------------

    def reachable_within(self, columns: int) -> set[str]:
        """Every node the start can route into without passing *columns* out.

        Presence on the map is not the same as being flyable to: an edge fan
        that never reaches a column entry makes whatever sits there fiction.
        """
        seen: set[str] = set()
        frontier = [self.start_id]
        while frontier:
            for edge in self.edges_from(frontier.pop()):
                target = self.nodes[edge.target]
                if edge.target in seen or target.column > int(columns):
                    continue
                seen.add(edge.target)
                frontier.append(edge.target)
        return seen

    def edges_from(self, node_id: str) -> list[ChartEdge]:
        """Every edge leaving *node_id*, consumed targets included."""
        node = self.nodes.get(node_id)
        return list(node.edges) if node is not None else []

    def edge_between(self, source_id: str, target_id: str) -> ChartEdge | None:
        """The edge joining two nodes, or None when no route exists."""
        for edge in self.edges_from(source_id):
            if edge.target == target_id:
                return edge
        return None

    def visible(self, node_id: str, notoriety: int = 0) -> bool:
        """Whether *node_id* is on the chart at this notoriety.

        The Broker Claim is drawn only for a ship notorious enough to dock
        there: a quiet player never sees the black market, and knows it.
        """
        node = self.nodes.get(node_id)
        if node is None:
            return False
        return int(notoriety) >= node.requires_notoriety

    def reachable(self, from_id: str, fuel: float, *, emergency: bool = False, notoriety: int = 0) -> list[str]:
        """Destinations from *from_id* the ship can both see and afford.

        Swept columns are in the list. The front does not close a route, it
        changes what is standing at the other end of it.
        """
        out: list[str] = []
        for edge in self.edges_from(from_id):
            if not self.visible(edge.target, notoriety):
                continue
            if warp_quote(self, from_id, edge.target, emergency=emergency).total <= float(fuel) + 1e-9:
                out.append(edge.target)
        return out

    def fuel_cost(self, from_id: str, target_id: str, *, emergency: bool = False) -> float:
        """Total fuel for the jump, the number the screen prints."""
        return warp_quote(self, from_id, target_id, emergency=emergency).total

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

    @staticmethod
    def wake_rate(notoriety: int) -> float:
        """Columns eaten per jump at this notoriety."""
        if int(notoriety) >= balance.WAKE_ACCEL_NOTORIETY:
            return balance.WAKE_ACCEL_COLUMNS_PER_JUMP
        return balance.WAKE_COLUMNS_PER_JUMP

    def advance_wake(self, jumps_taken: int, notoriety: int, *, pilot_column: int | None = None) -> int:
        """Feed the front the jumps taken so far. Returns columns eaten now.

        *jumps_taken* is the run's cumulative count, not a delta, so calling
        this twice for one jump eats nothing the second time.

        *pilot_column* is the column the ship is standing in. The front is
        clamped to it, so the furthest it can reach is the ground under the
        pilot's own feet and never the Deep Gate out in front of them: a hull
        that spends its jumps bouncing backwards is caught, not cut off from
        the exit. Progress keeps accruing while the clamp holds, so the front
        takes back what it was owed the moment the pilot moves on. Passing
        ``None`` leaves it unclamped, which is what a chart with nobody on it
        (a suspend being replayed, a headless probe) wants.
        """
        jumps_taken = max(0, int(jumps_taken))
        delta = jumps_taken - self._jumps_seen
        if delta <= 0:
            return 0
        self._jumps_seen = jumps_taken
        self._wake_progress += delta * self.wake_rate(notoriety)
        wanted = min(int(self._wake_progress), len(self.columns))
        if pilot_column is not None:
            wanted = min(wanted, int(pilot_column) + 1)
        eaten = wanted - (self.wake_column + 1)
        if eaten <= 0:
            return 0
        for column in range(self.wake_column + 1, wanted):
            for node_id in self.columns[column]:
                self.nodes[node_id].consumed = True
        self.wake_column = wanted - 1
        return eaten

    def wake_preview(
        self, jumps_taken: int, notoriety: int, count: int = balance.WAKE_PREVIEW_ADVANCES
    ) -> list[WakeAdvance]:
        """The front's next *count* advances, as the chart always shows them."""
        rate = self.wake_rate(notoriety)
        progress = self._wake_progress + max(0, int(jumps_taken) - self._jumps_seen) * rate
        out: list[WakeAdvance] = []
        for step in range(1, int(count) + 1):
            column = self.wake_column + step
            if column >= len(self.columns):
                break
            owed = (column + 1) - progress
            out.append(WakeAdvance(column=column, jumps_until=max(0, math.ceil(owed / rate)) if rate > 0 else 0))
        return out

    # -- the Roost ---------------------------------------------------------

    def reveal_roost(self) -> str:
        """Place the Roost beside the Deep Gate. Returns its node id.

        The assembled Lure is what puts it on the chart, so extraction and
        predation become one fork taken with the same fuel in the same tank.
        Calling this twice is harmless.

        Its approaches are the one place on the map that is not mirrored: the
        duel has no warp-out, so a line back out of the nest would be a lie.
        """
        if self.roost_id:
            return self.roost_id
        gate = self.nodes[self.deep_gate_id]
        node = ChartNode(
            id=ROOST_NODE_ID,
            column=gate.column,
            row=gate.row + 1,
            act=gate.act,
            biome="roost",
            is_roost=True,
        )
        node.icons = _icons_for(node)
        self.nodes[node.id] = node
        self.columns[gate.column].append(node.id)
        for source in self.columns[gate.column - 1]:
            if self.edge_between(source, gate.id) is not None:
                self.nodes[source].edges.append(ChartEdge(source, node.id, 0))
        self.roost_id = node.id
        # The nest is the only node added after the chart was named. Renaming
        # is stable rather than incremental, so nothing already on the map
        # changes its spelling under a pilot who has been reading it all run.
        self._name_nodes()
        return node.id


def _roman(number: int) -> str:
    """*number* as a roman numeral: the suffix two like sectors are told apart by."""
    value = max(1, int(number))
    out: list[str] = []
    for size, glyph in ROMAN_STEPS:
        while value >= size:
            out.append(glyph)
            value -= size
    return "".join(out)


def _nearest_rows(nodes: dict[str, ChartNode], candidates: list[str], row: int, count: int) -> list[str]:
    """The *count* candidates whose rows sit closest to *row*, nearest first."""
    ordered = sorted(candidates, key=lambda node_id: (abs(nodes[node_id].row - row), nodes[node_id].row))
    return ordered[: max(1, count)]


def _scrap_estimate(act: int, biome: str) -> int:
    """Mid-band scrap for a sector of this act and biome, from the drop table."""
    low, high = balance.ACT_DROPS[act].scrap_per_sector
    return int(round((low + high) * 0.5 * balance.BIOMES[biome].scrap_mult))


def _icons_for(node: ChartNode) -> tuple[str, ...]:
    """The honest read of a node, derived from the tables the sector obeys."""
    if node.is_deep_gate:
        return (ICON_GATE,)
    if node.is_roost:
        return (ICON_ROOST,)
    spec = balance.BIOMES[node.biome]
    icons: list[str] = []
    if spec.scrap_mult > 1.0:
        icons.append(ICON_SCRAP_RICH)
    elif spec.scrap_mult < 1.0:
        icons.append(ICON_SCRAP_POOR)
    if spec.solar_mult > 1.0:
        icons.append(ICON_SOLAR)
    elif spec.solar_mult <= 0.0:
        icons.append(ICON_NO_SOLAR)
    if node.biome in ("ice_field", "vent_field"):
        icons.append(ICON_O2)
    if node.biome == "vent_field":
        icons.append(ICON_FUEL)
    if spec.telegraph_override_s is not None:
        icons.append(ICON_MUFFLED)
    if node.biome == "broker_claim":
        icons.append(ICON_BROKER)
    if balance.ACT_DROPS[node.act].vaults_per_sector[1] >= 1:
        icons.append(ICON_VAULT)
    return tuple(icons)


# ============================================================================
# The screen
# ============================================================================


class StarChart(Control):
    """The full-screen pause chart, and the warp it commits the run to.

    Opening pauses the tree; the chart itself runs on ``UpdateMode.ALWAYS`` so
    it can read its own input while everything else is frozen. Selection is
    keyboard, pad and mouse at once and adds no action to the map: the thrust
    actions and all four ``menu_`` arrows cycle destinations, ``interact`` or
    ``menu_confirm`` commits, and ``star_chart`` toggles the screen. The
    cursor walks the offer sheet in the order the map is drawn,
    column then row, so the lane home sits at the left-hand end of the cycle
    rather than wherever the generator appended it, and it is never where the
    cursor starts. ``fire_primary`` is the pointer's half: a click picks
    the sector it lands on, a second click or the jump button in the footer
    spends the fuel, and a click on a sector the drive cannot reach is answered
    on the status line. The footer names keys rather than actions, because the
    only place a player can read this screen is the screen.

    Swept ground is offered like any other destination and refused by nothing
    but the tank. What it costs is said three times before the fuel goes: the
    node's own price row, the status line the moment the cursor lands on it,
    and the jump button's label. What it actually costs is charged by the run
    scene on arrival, which reads ``ChartNode.consumed`` for itself.

    Committing does not teleport anything. It closes the chart, emits
    ``JUMP_STARTED`` with the honest price and starts the ship's spool; the
    fuel leaves the tank and ``JUMP_COMPLETED`` fires only when the channel
    survives to the end, so a spool broken by fire costs nothing but the
    seconds. The Wake is fed immediately after, and ``WAKE_ADVANCED`` carries
    however many columns it took.
    """

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

    dynamic = True

    chart_opened = Signal()
    jump_started = Signal(str, float)
    jump_completed = Signal(str)
    wake_advanced = Signal(int)

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        # The chart is a pause screen, not a click target for the guns: it
        # reads the pointer itself and never eats a shot while it is closed.
        self.mouse_filter = False
        # It also has to keep running while it holds the tree still, or the
        # screen that owns the pause could never lift it.
        self.ui_scale: float = 1.0

        self.graph: ChartGraph | None = None
        self.run_state = None
        self.current_node_id = ""
        self.jumps_taken = 0

        self._open = False
        self._selected = ""
        self._pending: WarpQuote | None = None
        self._spooling_ship = None
        self._node_rects: dict[str, tuple[float, float, float, float]] = {}
        #: The jump button, as the last draw placed it.
        self._confirm_rect: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)
        self._hovered = ""
        self._status = ""
        self._status_remaining = 0.0
        self._clicking = False
        self._click_armed = False

    def on_ready(self):
        self.set_anchor_preset(AnchorPreset.FULL_RECT)

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

    def open(self, run_state) -> None:
        """Show the chart for *run_state* and pause the run.

        *run_state* supplies ``chart`` (a :class:`ChartGraph`),
        ``current_node_id`` and ``jumps_taken``; the last two are written back
        when a jump completes.
        """
        graph = getattr(run_state, "chart", None)
        if not isinstance(graph, ChartGraph):
            raise TypeError("run_state.chart must be a ChartGraph")
        self.run_state = run_state
        self.graph = graph
        self._open = True
        self._click_armed = False
        self._clicking = Input.is_action_pressed("fire_primary")
        self.arm_default()
        if self.tree is not None:
            self.tree.paused = True
        self.chart_opened()

    def close(self) -> None:
        """Hide the chart and let the run breathe again."""
        if not self._open:
            return
        self._open = False
        if self.tree is not None:
            self.tree.paused = False

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

    @property
    def selected_id(self) -> str:
        """The destination the pilot is about to buy, empty when none is."""
        return self._selected

    # -- destinations ------------------------------------------------------

    @property
    def notoriety(self) -> int:
        """Run notoriety, from the tally node when the run has one."""
        tally = self._service(Services.NOTORIETY)
        if tally is not None:
            return int(getattr(tally, "value", 0))
        return int(getattr(self.run_state, "notoriety", 0) or 0)

    @property
    def fuel(self) -> float:
        """Fuel in the tank, from the power system when the run has one."""
        power = self._service(Services.POWER)
        if power is not None:
            return float(getattr(power, "fuel", 0.0))
        return float(getattr(self.run_state, "fuel", balance.FUEL_MAX))

    @property
    def emergency(self) -> bool:
        """True while the hunter is in the sector, which is what prices 1.5x."""
        tree = self.tree
        return tree is not None and tree.get_first_in_group(Groups.HUNTER) is not None

    def destinations(self) -> list[Destination]:
        """Every visible route out of the current node, priced and gated.

        In cycle order: the ways deeper first, then the ways back, each block
        in the order the screen draws them (column, then row). The order used
        to be whatever order the generator appended edges in, which put the
        mirrored lanes home at the end of a list nothing else was sorted by,
        so pressing a key moved the cursor somewhere the map gave no reason to
        expect and a blind pilot read the lane home as missing entirely.
        """
        graph = self.graph
        if graph is None or self.current_node_id not in graph.nodes:
            return []
        emergency = self.emergency
        fuel = self.fuel
        out: list[Destination] = []
        for edge in sorted(graph.edges_from(self.current_node_id), key=self._cursor_order):
            if not graph.visible(edge.target, self.notoriety):
                continue
            quote = warp_quote(graph, self.current_node_id, edge.target, emergency=emergency)
            out.append(
                Destination(
                    node_id=edge.target,
                    quote=quote,
                    depot=edge.depot,
                    broker_depot=edge.broker,
                    affordable=quote.total <= fuel + 1e-9,
                    consumed=graph.nodes[edge.target].consumed,
                )
            )
        return out

    def _cursor_order(self, edge: ChartEdge) -> tuple[int, int, int, str]:
        """Where an edge sits in the cycle: the ways on, then the ways back.

        Inside each block it is the order the map is drawn in, column then row.
        The ways back sort last for two reasons: the cursor opens on the first
        entry and retreating must never be what an unread ``F`` buys, and a
        single backwards press from there wraps straight onto the lane home,
        which is the shortest walk the keys can offer to the one destination a
        pilot goes looking for.
        """
        node = self.graph.nodes[edge.target] if self.graph is not None else None
        if node is None:
            return (1, 0, 0, edge.target)
        return (0 if self._leads_deeper(edge.target) else 1, node.column, node.row, edge.target)

    def _leads_deeper(self, node_id: str) -> bool:
        """Whether *node_id* sits further out than the sector the hull is in."""
        graph = self.graph
        if graph is None or node_id not in graph.nodes or self.current_node_id not in graph.nodes:
            return False
        return graph.nodes[node_id].column > graph.nodes[self.current_node_id].column

    @property
    def stranded(self) -> bool:
        """True when no destination is affordable: the Last Stand condition."""
        return not any(destination.available for destination in self.destinations())

    def select(self, node_id: str) -> bool:
        """Point the cursor at *node_id*. False when it is not on offer."""
        if any(destination.node_id == node_id for destination in self.destinations()):
            self._selected = node_id
            self._announce_selection()
            return True
        return False

    def cycle_selection(self, step: int) -> None:
        """Move the cursor *step* places through the offered destinations."""
        offered = [destination.node_id for destination in self.destinations()]
        if not offered:
            self._selected = ""
            return
        if self._selected not in offered:
            self._selected = offered[0]
        else:
            self._selected = offered[(offered.index(self._selected) + int(step)) % len(offered)]
        self._announce_selection()

    def _announce_selection(self) -> None:
        """Warn on the status line when the cursor lands on swept ground.

        The pointer gets its warning from :meth:`click_at`; this is the same
        warning for the keys, which are the only way a pad ever reads this
        screen. Nothing is said about an ordinary destination, because the
        footer, the node and the jump button already price it.
        """
        chosen = next((d for d in self.destinations() if d.node_id == self._selected), None)
        if chosen is not None and chosen.consumed:
            self.set_status(STATUS_WAKE_TERRITORY.format(label=self._label_of(chosen.node_id)))

    def _take_position(self) -> None:
        """Read where the hull is off the run before offering it anything.

        The run scene owns the hull's place on the map and this screen is told
        rather than asked, so every arming point reads it again: an arrival
        arms the fan of the sector the ship is actually in, whether the arming
        came from opening the screen or from the run scene's own arrival path.
        """
        run_state = self.run_state
        if run_state is None:
            return
        if self.graph is None and isinstance(getattr(run_state, "chart", None), ChartGraph):
            self.graph = run_state.chart
        node_id = str(getattr(run_state, "current_node_id", "") or "")
        fallback = self.current_node_id or (self.graph.start_id if self.graph is not None else "")
        self.current_node_id = node_id or fallback
        self.jumps_taken = int(getattr(run_state, "jumps_taken", self.jumps_taken))

    def arm_default(self) -> str:
        """Point the drive at a sane destination, and return the node armed.

        The cursor's opening position and the lane a bare press of the drive
        key buys are the same thing, so one rule settles both: the ways deeper
        first, and swept ground never chosen on the pilot's behalf. The cursor
        is where an unread ``F`` lands and the armed lane is where an unread
        ``R`` goes, and neither may put the run in Shrike territory by
        accident. Nor is the way home a default: retreating is a decision, so
        it is a place the cursor is walked onto rather than one it starts on.

        Called on open and after every jump, and by the run scene on every
        arrival, so the drive key is answerable from the first frame in a
        sector rather than only once the chart has been opened. Returns ""
        when the fan offers nothing at all, which is the Deep Gate and the
        Roost, both of which end the run on arrival anyway.
        """
        self._take_position()
        offered = self.destinations()
        deeper = [d for d in offered if self._leads_deeper(d.node_id)]
        for pool in (
            [d for d in deeper if d.available and not d.consumed],
            [d for d in offered if d.available and not d.consumed],
            [d for d in deeper if d.available],
            [d for d in offered if d.available],
            offered,
        ):
            if pool:
                self._selected = pool[0].node_id
                return self._selected
        self._selected = ""
        return self._selected

    # -- the jump ----------------------------------------------------------

    def confirm(self) -> bool:
        """Commit to the selected destination and start the spool.

        Returns False when nothing is selected, when the route is unaffordable
        or already eaten, and when the drive refuses to spool at all, which is
        what the hunter's arrival lockout does. Nothing is committed and no
        signal is emitted on a refusal: a scrambled drive has not jumped.
        """
        graph = self.graph
        if graph is None or not self._selected or self._pending is not None:
            return False
        chosen = next((d for d in self.destinations() if d.node_id == self._selected), None)
        if chosen is None or not chosen.available:
            return False

        ship = self.tree.get_first_in_group(Groups.SHIP) if self.tree is not None else None
        if ship is not None and hasattr(ship, "begin_warp_spool"):
            ship.begin_warp_spool(emergency=chosen.quote.emergency)
            if not getattr(ship, "spooling", False):
                return False
            self._spooling_ship = ship
            ship.warp_completed.connect(self._on_warp_completed)
            # Both endings, not just the happy one. A route held past the
            # channel that bought it is cashed in by the next spool the pilot
            # starts for any reason at all, which is a jump nobody asked for.
            ship.warp_spool_cancelled.connect(self._on_spool_cancelled)

        self.close()
        self._pending = chosen.quote
        self.jump_started(chosen.node_id, chosen.quote.total)
        if self._spooling_ship is None:
            # No hull in the tree (a chart-only harness, or the menu): there is
            # no channel to run, so the jump resolves at once.
            self._complete_jump()
        return True

    def cancel_jump(self) -> None:
        """Abandon a committed jump that has not finished spooling."""
        ship = self._release_ship()
        self._pending = None
        if ship is not None:
            ship.cancel_warp_spool()

    @property
    def pending_target(self) -> str:
        """The node a committed jump is spooling toward, empty when none is."""
        return self._pending.target if self._pending is not None else ""

    def _release_ship(self):
        """Stop listening to the hull this jump was riding, and return it."""
        ship, self._spooling_ship = self._spooling_ship, None
        if ship is not None:
            ship.warp_completed.disconnect(self._on_warp_completed)
            ship.warp_spool_cancelled.disconnect(self._on_spool_cancelled)
        return ship

    def _on_warp_completed(self, emergency: bool) -> None:
        del emergency
        self._release_ship()
        self._complete_jump()

    def _on_spool_cancelled(self) -> None:
        """The channel ended without a jump, so the route goes back on the map."""
        self._release_ship()
        self._pending = None

    def _complete_jump(self) -> None:
        quote, self._pending = self._pending, None
        if quote is None or self.graph is None:
            return
        power = self._service(Services.POWER)
        if power is not None and not power.spend_fuel(quote.total):
            # The channel survived and the tank did not. The route is not
            # taken, nothing is consumed, and the pilot is told the number
            # they were short by rather than arriving somewhere for free.
            self._refuse_jump(quote)
            return

        self.current_node_id = quote.target
        self.jumps_taken += 1
        if self.run_state is not None:
            self.run_state.current_node_id = self.current_node_id
            self.run_state.jumps_taken = self.jumps_taken
        self.jump_completed(quote.target)

        # The front is fed after the arrival, and clamped to where the arrival
        # left the hull: a pilot who has just spent a jump retreating can be
        # caught by it in the sector they are standing in, which is what
        # ``WAKE_ADVANCED`` is listened for.
        here = self.graph.nodes.get(self.current_node_id)
        eaten = self.graph.advance_wake(
            self.jumps_taken, self.notoriety, pilot_column=here.column if here is not None else None
        )
        if eaten > 0:
            self.wake_advanced(eaten)
        self.arm_default()

    def _refuse_jump(self, quote: WarpQuote) -> None:
        """Say why a finished channel bought nothing, and re-offer the map."""
        hud = self._service(Services.HUD)
        have = self.fuel
        if hud is not None and hasattr(hud, "show_toast"):
            hud.show_toast(f"{SPOOL_FAILURE_NO_FUEL}: need {quote.total:.0f}, have {have:.0f}")
        self.arm_default()

    def _service(self, name: str):
        tree = self.tree
        return tree.singletons.get(name) if tree is not None else None

    # -- input -------------------------------------------------------------

    def on_update(self, dt: float):
        if self._status_remaining > 0.0:
            self._status_remaining = max(0.0, self._status_remaining - dt)
        if Input.is_action_just_pressed("star_chart"):
            if self._open:
                self.close()
            elif self.run_state is not None:
                self.open(self.run_state)
            return
        if not self._open:
            self._clicking = Input.is_action_pressed("fire_primary")
            return

        if _any_just_pressed(CYCLE_FORWARD_ACTIONS):
            self.cycle_selection(1)
        elif _any_just_pressed(CYCLE_BACK_ACTIONS):
            self.cycle_selection(-1)

        pointer = Input.mouse_position
        point = (float(pointer.x), float(pointer.y))
        self._hovered = self._node_at(*point)
        if _any_just_pressed(CONFIRM_ACTIONS):
            self.confirm()
            return
        held = Input.is_action_pressed("fire_primary")
        clicked, self._clicking = held and not self._clicking, held
        if clicked:
            self.click_at(*point)

    def click_at(self, x: float, y: float) -> bool:
        """Answer a click at a screen point. True when it committed a jump.

        The chart used to be a keyboard screen with a mouse shortcut nailed to
        the side: hovering a sector selected it and the next click jumped, so
        the map could only be read with the pointer parked off it. A click now
        picks the sector it is on, and it takes a second click, the jump button
        or the key to spend the fuel. A click on somewhere the drive cannot
        reach is answered on the status line rather than ignored.
        """
        if _rect_holds(self._confirm_rect, x, y):
            return self.confirm()
        node_id = self._node_at(x, y)
        if not node_id:
            return False
        if node_id == self._selected and self._click_armed:
            return self.confirm()

        destination = next((d for d in self.destinations() if d.node_id == node_id), None)
        label = self._label_of(node_id)
        if destination is None:
            self.set_status(STATUS_NO_ROUTE)
            return False
        self._selected = node_id
        # The chart opens with a sector already under the cursor for the
        # keyboard's sake. Arming the second click only once a click has chosen
        # something is what stops the first click a player ever makes on this
        # screen from spending their fuel.
        self._click_armed = True
        if destination.consumed:
            self.set_status(STATUS_WAKE_TERRITORY.format(label=label))
        elif not destination.affordable:
            self.set_status(STATUS_UNAFFORDABLE.format(need=destination.quote.total, have=self.fuel))
        else:
            self.set_status(STATUS_SELECTED.format(label=label))
        return False

    def _label_of(self, node_id: str) -> str:
        """What this screen calls *node_id*: the one spelling every line uses."""
        graph = self.graph
        return graph.nodes[node_id].label if graph is not None and node_id in graph.nodes else node_id

    def set_status(self, text: str) -> None:
        """Put one line on the chart's own status slot for :data:`STATUS_HOLD_S`."""
        self._status = str(text)
        self._status_remaining = STATUS_HOLD_S

    @property
    def status(self) -> str:
        """The chart's status line, empty once it has timed out."""
        return self._status if self._status_remaining > 0.0 else ""

    @property
    def hovered_id(self) -> str:
        """The sector the pointer is over, empty when it is over none."""
        return self._hovered

    def node_rects(self) -> dict[str, tuple[float, float, float, float]]:
        """Where each node was last drawn, for hit-testing and for tests."""
        return dict(self._node_rects)

    def confirm_rect(self) -> tuple[float, float, float, float]:
        """Where the jump button was last drawn, for hit-testing and for tests."""
        return self._confirm_rect

    def confirm_label(self) -> str:
        """What the jump button says about the selection standing right now."""
        chosen = next((d for d in self.destinations() if d.node_id == self._selected), None)
        if chosen is None or self.graph is None:
            return CONFIRM_LABEL_EMPTY
        if not chosen.affordable:
            return CONFIRM_LABEL_SHORT.format(fuel=chosen.quote.total)
        label = self._label_of(chosen.node_id)
        template = CONFIRM_LABEL_WAKE if chosen.consumed else CONFIRM_LABEL
        return template.format(label=label, fuel=chosen.quote.total)

    def _node_at(self, x: float, y: float) -> str:
        for node_id, rect in self._node_rects.items():
            if _rect_holds(rect, x, y):
                return node_id
        return ""

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

    def on_draw(self, renderer):
        if not self._open or self.graph is None:
            self._node_rects.clear()
            self._confirm_rect = (0.0, 0.0, 0.0, 0.0)
            return
        rect = self.get_global_rect()
        scale = self.ui_scale
        self._layout(rect, scale)

        x, y, w, h = rect
        renderer.draw_rect((x, y), (w, h), colour=COLOUR_BACKDROP, filled=True)
        margin = PANEL_MARGIN_PX * scale
        renderer.draw_rect(
            (x + margin, y + margin),
            (max(0.0, w - margin * 2), max(0.0, h - margin * 2)),
            colour=COLOUR_PANEL,
            filled=True,
        )
        self._draw_wake(renderer, rect, scale)
        self._draw_edges(renderer, scale)
        self._draw_nodes(renderer, scale)
        self._draw_header(renderer, rect, scale)
        self._draw_footer(renderer, rect, scale)
        self._draw_wake_labels(renderer, rect, scale)

    def _layout(self, rect: tuple[float, float, float, float], scale: float) -> None:
        """Place every node box. Columns run left to right, rows top to bottom."""
        self._node_rects.clear()
        graph = self.graph
        if graph is None:
            return
        x, y, w, h = rect
        margin = PANEL_MARGIN_PX * scale
        top = y + margin + HEADER_HEIGHT_PX * scale
        bottom = y + h - margin - FOOTER_HEIGHT_PX * scale
        node_w = NODE_WIDTH_PX * scale
        node_h = NODE_HEIGHT_PX * scale
        columns = len(graph.columns)
        span = max(1.0, w - margin * 2 - node_w)
        for column, ids in enumerate(graph.columns):
            cx = x + margin + (span * column / max(1, columns - 1))
            usable = max(node_h, bottom - top)
            for index, node_id in enumerate(ids):
                cy = top + (usable - node_h) * (index / max(1, len(ids) - 1) if len(ids) > 1 else 0.5)
                self._node_rects[node_id] = (cx, cy, node_w, node_h)

    def _centre(self, node_id: str) -> tuple[float, float]:
        rx, ry, rw, rh = self._node_rects[node_id]
        return rx + rw * 0.5, ry + rh * 0.5

    def _draw_wake(self, renderer, rect, scale: float) -> None:
        graph = self.graph
        if graph is None:
            return
        x, y, w, h = rect
        margin = PANEL_MARGIN_PX * scale
        top = y + margin
        height = max(0.0, h - margin * 2)
        for column in range(0, graph.wake_column + 1):
            if not graph.columns[column]:
                continue
            rx, _, rw, _ = self._node_rects[graph.columns[column][0]]
            renderer.draw_rect((rx - rw * 0.15, top), (rw * 1.3, height), colour=COLOUR_WAKE, filled=True)

        for advance in graph.wake_preview(self.jumps_taken, self.notoriety):
            ids = graph.columns[advance.column] if advance.column < len(graph.columns) else []
            if not ids:
                continue
            rx, _, rw, _ = self._node_rects[ids[0]]
            line_x = rx - rw * 0.18
            renderer.draw_thick_line(
                line_x, top, line_x, top + height, EDGE_THICKNESS_PX * scale, colour=COLOUR_WAKE_PREVIEW
            )

    def _draw_wake_labels(self, renderer, rect, scale: float) -> None:
        """Name each preview line, on a plate nothing else prints through.

        The labels used to ride the very top of their lines, where the
        header's title printed straight through them and the panel edge
        clipped the first column's. They draw last, on their own plates, at
        the foot of the header band: above every node box and below both
        header texts, and clamped inside the panel.
        """
        graph = self.graph
        if graph is None:
            return
        x, y, w, _ = rect
        margin = PANEL_MARGIN_PX * scale
        label_w = WAKE_LABEL_WIDTH_PX * scale
        label_h = WAKE_LABEL_HEIGHT_PX * scale
        top = y + margin + HEADER_HEIGHT_PX * scale - label_h
        for advance in graph.wake_preview(self.jumps_taken, self.notoriety):
            ids = graph.columns[advance.column] if advance.column < len(graph.columns) else []
            if not ids:
                continue
            rx, _, rw, _ = self._node_rects[ids[0]]
            line_x = rx - rw * 0.18
            left = min(max(x + margin, line_x + 4.0 * scale), x + w - margin - label_w)
            renderer.draw_rect((left, top), (label_w, label_h), colour=COLOUR_BACKDROP, filled=True)
            renderer.draw_text(
                WAKE_PREVIEW_LABEL.format(jumps=advance.jumps_until),
                rect=(left, top, label_w, label_h),
                colour=COLOUR_WAKE_PREVIEW,
                scale=LABEL_FONT_SCALE * scale,
                alignment="centre",
                vertical_alignment="centre",
            )

    def _draw_edges(self, renderer, scale: float) -> None:
        """One line per charted lane, drawn from the pilot's end first.

        Every lane is now two edges, one each way, and both land on the same
        pixels. Drawing the pair twice would let the mirrored edge's plain grey
        paint over the live route's highlight, so a lane is drawn once and the
        sweep starts at the node the ship is standing in, which is the only
        node whose edges are coloured by what they cost.
        """
        graph = self.graph
        if graph is None:
            return
        offered = {destination.node_id: destination for destination in self.destinations()}
        order = [self.current_node_id] + [node_id for node_id in graph.nodes if node_id != self.current_node_id]
        drawn: set[tuple[str, str]] = set()
        for node_id in order:
            node = graph.nodes.get(node_id)
            if node is None or node.id not in self._node_rects or not graph.visible(node.id, self.notoriety):
                continue
            sx, sy = self._centre(node.id)
            for edge in node.edges:
                if edge.target not in self._node_rects or not graph.visible(edge.target, self.notoriety):
                    continue
                lane = (min(node.id, edge.target), max(node.id, edge.target))
                if lane in drawn:
                    continue
                drawn.add(lane)
                tx, ty = self._centre(edge.target)
                colour = COLOUR_EDGE
                thickness = EDGE_THICKNESS_PX * scale
                if node.id == self.current_node_id:
                    destination = offered.get(edge.target)
                    if destination is not None and destination.available:
                        colour = COLOUR_EDGE_REACHABLE
                    else:
                        colour = COLOUR_EDGE_UNAFFORDABLE
                    if edge.target == self._selected:
                        colour = COLOUR_SELECTED
                        thickness = SELECTED_THICKNESS_PX * scale
                renderer.draw_thick_line(sx, sy, tx, ty, thickness, colour=colour)
                if edge.depot:
                    renderer.draw_circle(
                        ((sx + tx) * 0.5, (sy + ty) * 0.5),
                        DEPOT_MARKER_RADIUS_PX * scale,
                        colour=COLOUR_BROKER if edge.broker else COLOUR_DEPOT,
                        filled=True,
                    )

    def _draw_nodes(self, renderer, scale: float) -> None:
        graph = self.graph
        if graph is None:
            return
        offered = {destination.node_id: destination for destination in self.destinations()}
        line = NODE_LINE_HEIGHT_PX * scale
        font = NODE_FONT_SCALE * scale
        for node_id, (rx, ry, rw, rh) in self._node_rects.items():
            node = graph.nodes[node_id]
            if not graph.visible(node_id, self.notoriety):
                continue
            if node.consumed:
                fill = COLOUR_NODE_CONSUMED
            elif node_id == self.current_node_id:
                fill = COLOUR_NODE_CURRENT
            else:
                fill = COLOUR_NODE
            renderer.draw_rect((rx, ry), (rw, rh), colour=fill, filled=True)
            if node_id == self._selected:
                renderer.draw_rect((rx, ry), (rw, rh), colour=COLOUR_SELECTED, filled=False)
            elif node_id == self._hovered:
                # The pointer does not choose anything by resting; it says what
                # it is over, so a click is never a surprise.
                renderer.draw_rect((rx, ry), (rw, rh), colour=COLOUR_EDGE_REACHABLE, filled=False)

            inset = NODE_TEXT_INSET_PX * scale
            renderer.draw_text(
                node.label,
                (rx + inset, ry + 4.0 * scale),
                colour=COLOUR_TEXT,
                scale=fitted_font_scale(node.label, font, rw - inset * 2.0),
            )
            icons = " ".join(node.icons)
            renderer.draw_text(icons, (rx + 6.0 * scale, ry + 4.0 * scale + line), colour=COLOUR_TEXT_DIM, scale=font)
            renderer.draw_text(
                f"~{node.scrap_estimate} SCRAP" if not node.is_deep_gate else f"TOLL {int(balance.DEEP_GATE_TOLL)}",
                (rx + 6.0 * scale, ry + 4.0 * scale + line * 2),
                colour=COLOUR_TEXT_DIM,
                scale=font,
            )
            destination = offered.get(node_id)
            if destination is not None:
                price = f"FUEL {destination.quote.total:.0f}"
                if destination.quote.emergency:
                    price += " EMG"
                if destination.consumed:
                    # Priced, not barred: the row says what the fuel buys and
                    # what is standing in it.
                    price = NODE_PRICE_WAKE.format(fuel=destination.quote.total)
                renderer.draw_text(
                    price,
                    (rx + 6.0 * scale, ry + 4.0 * scale + line * 3),
                    colour=COLOUR_TEXT if destination.available else COLOUR_EDGE_UNAFFORDABLE,
                    scale=font,
                )

    def _draw_header(self, renderer, rect, scale: float) -> None:
        graph = self.graph
        if graph is None:
            return
        x, y, w, _ = rect
        margin = PANEL_MARGIN_PX * scale
        here = graph.nodes.get(self.current_node_id)
        act = here.act if here is not None else 1
        renderer.draw_text(
            f"STAR CHART   {ACT_LABELS.get(act, '')}   JUMP {self.jumps_taken}",
            (x + margin + 8.0 * scale, y + margin + HEADER_TITLE_OFFSET_PX * scale),
            colour=COLOUR_TEXT,
            scale=HEADER_FONT_SCALE * scale,
        )
        renderer.draw_text(
            f"FUEL {self.fuel:.0f} / {balance.FUEL_MAX:.0f}   NOTORIETY {self.notoriety}",
            (x + w - margin - 300.0 * scale, y + margin + 12.0 * scale),
            colour=COLOUR_TEXT_DIM,
            scale=LABEL_FONT_SCALE * scale,
        )
        # The legend. Red and the two orange countdowns are the only marks on
        # this screen with no other place to be explained, and a mark nobody
        # can read is a mark that reads as decoration.
        renderer.draw_text(
            WAKE_LEGEND,
            (x + margin + 8.0 * scale, y + margin + LEGEND_OFFSET_PX * scale),
            colour=COLOUR_WAKE_PREVIEW,
            scale=LABEL_FONT_SCALE * scale,
        )

    def _draw_footer(self, renderer, rect, scale: float) -> None:
        """The key names, the status line and the jump button.

        The button is laid out here rather than in :meth:`_layout` because it
        is the only thing on the screen whose size is its own rather than the
        graph's, and it is hit-tested from the rect this leaves behind.
        """
        x, y, w, h = rect
        margin = PANEL_MARGIN_PX * scale
        footer = FOOTER_HEIGHT_PX * scale
        top = y + h - margin - footer
        confirm_w = CONFIRM_WIDTH_PX * scale
        confirm_h = CONFIRM_HEIGHT_PX * scale
        self._confirm_rect = (
            x + w - margin - confirm_w - 8.0 * scale,
            top + (footer - confirm_h) * 0.5,
            confirm_w,
            confirm_h,
        )

        slot_w = w - margin * 2 - confirm_w
        # A refusal and the Last Stand each own the whole slot: one sentence,
        # centred, with nothing beside it to read first. The standing hint is
        # two rows, because the keys and what the cursor does with them do not
        # fit on one at a width the slot has.
        if self.status:
            rows = ((self.status, COLOUR_SELECTED),)
        elif self.stranded:
            rows = ((FOOTER_STRANDED, COLOUR_TEXT_DIM),)
        else:
            rows = ((FOOTER_HINT, COLOUR_TEXT_DIM), (FOOTER_HINT_SECOND, COLOUR_TEXT_DIM))
        row_h = footer / len(rows)
        for index, (text, colour) in enumerate(rows):
            renderer.draw_text(
                text,
                rect=(x + margin, top + row_h * index, slot_w, row_h),
                colour=colour,
                scale=LABEL_FONT_SCALE * scale,
                alignment="centre",
                vertical_alignment="centre",
            )

        cx, cy, cw, ch = self._confirm_rect
        chosen = next((d for d in self.destinations() if d.node_id == self._selected), None)
        live = chosen is not None and chosen.available
        renderer.draw_rect((cx, cy), (cw, ch), colour=COLOUR_NODE_CURRENT if live else COLOUR_NODE, filled=True)
        renderer.draw_rect((cx, cy), (cw, ch), colour=COLOUR_SELECTED if live else COLOUR_EDGE, filled=False)
        renderer.draw_text(
            self.confirm_label(),
            rect=(cx, cy, cw, ch),
            colour=COLOUR_TEXT if live else COLOUR_TEXT_DIM,
            scale=LABEL_FONT_SCALE * scale,
            alignment="centre",
            vertical_alignment="centre",
        )