Auction House

TRACK = (
    (FORCED_SALE, 350 * K),
    (INHERIT, None),
    (COLLECT, 300 * K),
    (MAY_SELL, None),
    (PRIVATE_AUCTION, None),
    (BUY_BANK, 400 * K),
    (COLLECT, 100 * K),
    (BANK_AUCTION, None),
    (PRIVATE_AUCTION, None),
    (BUY_BANK, 300 * K),
    (MAY_SELL, None),
    (COLLECT, 200 * K),
    (PRIVATE_AUCTION, None),
    (MAY_SELL, None),
    (BANK_AUCTION, None),
    (PRIVATE_AUCTION, None),
    (MAY_SELL, None),
    (BUY_BANK, 350 * K),
    (COLLECT, 400 * K),
    (PRIVATE_AUCTION, None),
    (MAY_SELL, None),
    (BUY_BANK, 250 * K),
    (BANK_AUCTION, None),
    (BUY_BANK, 400 * K),
    (PRIVATE_AUCTION, None),
    (MAY_SELL, None),
    (BUY_PLAYER, 400 * K),
    (COLLECT, 500 * K),
    (BANK_AUCTION, None),
    (PRIVATE_AUCTION, None),
)

def works(gallery: str) -> list[str]:
    """The ids of every work a gallery can hang."""
    return [w["id"] for w in load(gallery)["works"]]

def kind_of(gallery, medium):
    if gallery == "sculpture":
        return "object"
    return "painting" if FLAT.search(medium or "") else "object"

def new(players: int, seed: str, now: float, settings: dict | None = None) -> dict:
    if not min_players <= players <= max_players:
        raise Illegal("Auction House is for three to six players.")
    rules = options(settings)
    gallery = board.load(rules["gallery"])
    pool = [w["id"] for w in gallery["works"]]
    if len(pool) < PAINTINGS:
        raise Illegal("That gallery hasn't enough works to hang.")
    hung = deck.shuffled(pool, f"{seed}:gallery")
    art = hung[:PAINTINGS] if gallery.get("fixed") else deck.shuffled(hung, f"{seed}:pick")[:PAINTINGS]
    values = deck.shuffled([str(v) for v in VALUE_CARDS], f"{seed}:values")
    first = int.from_bytes(seed.encode(), "big") % players
    state = {
        "game": slug, "n": players, "seed": seed, "gallery": gallery["id"],
        "rules": {"gallery": gallery["id"], "clock": rules["clock"]},
        "_pace": moves.BOT_PACE[rules["bot_pace"]], "clock": CLOCKS[rules["clock"]],
        "seq": 0, "logged": 0, "events": [],
        "art": art, "value": [int(v) for v in values],
        # The pile: the painting on top is the last; the value cards are
        # dealt with them, so value[i] is the card painting i draws.
        "pile": list(range(PAINTINGS - 1, -1, -1)),
        "held": [None] * PAINTINGS, "seen": [[] for _ in range(PAINTINGS)], "shown": [False] * PAINTINGS,
        "price": [None] * PAINTINGS,  # what the bank paid for one it bought
        "cash": [START_CASH] * players, "pos": [None] * players,
        "phase": "start", "first": first, "turn": None, "turns": 0, "rolls": 0, "dice": None, "moves": None,
        "pending": None, "auction": None, "auctions": 0, "last": None,
        "final": None, "winners": None, "scores": [], "totals": [0] * players, "ready": [False] * players,
    }
    # Each player in turn, beginning with the first, draws a painting and its value card.
    for k in range(players):
        _draw(state, (first + k) % players)
    log.event(state, "start", first=first, gallery=gallery["id"])
    return state

def destinations(start: int, steps: int) -> list[int]:
    """The spaces a roll can reach: clockwise first, then counterclockwise
    (just the one, should the two ever be the same space)."""
    return list(dict.fromkeys([(start + steps) % SPACES, (start - steps) % SPACES]))

def move(state, seat, action, now):
    """Move to one of the two spaces the roll reaches, and do what it says."""
    _my_turn(state, seat, "move")
    space = action.get("space")
    if type(space) is not int or space not in state["moves"]:
        raise Illegal("Move to one of the spaces your roll reaches.")
    start = state["pos"][seat]
    way = "cw" if space == state["moves"][0] else "ccw"
    state["pos"][seat] = space
    state["moves"] = None
    kind, amount = TRACK[space]
    log.event(state, "move", seat=seat, start=start, land=space, way=way, space=kind, amount=amount)
    _land(state, seat, space, now)

def _land(state: dict, seat: int, space: int, now: float) -> None:
    """Do what the space says."""
    kind, amount = TRACK[space]
    mine = owned(state, seat)
    if kind == COLLECT:
        state["cash"][seat] += amount
        log.event(state, "collect", seat=seat, amount=amount)
        return _next(state)
    if kind == INHERIT:
        if not state["pile"]:
            return _next(state)
        i = _draw(state, seat)
        log.event(state, "inherit", seat=seat, painting=i, art=state["art"][i])
        return _next(state)
    if kind == BANK_AUCTION:
        if not state["pile"]:
            return _next(state)
        return _open(state, state["pile"][-1], "bank", seat, now)
    if kind == BUY_BANK:
        if not state["pile"]:
            return _next(state)
        if state["cash"][seat] < amount:
            # Not buying, for want of the price: it goes to auction without them.
            log.event(state, "decline", seat=seat, painting=state["pile"][-1], price=amount, short=True)
            return _open(state, state["pile"][-1], "bank", seat, now, barred=[seat])
        return _ask(state, seat, "buy", price=amount, painting=state["pile"][-1])
    if kind == MAY_SELL:
        return _ask(state, seat, "sell") if mine else _next(state)
    if kind == BUY_PLAYER:
        if state["cash"][seat] >= amount and any(h not in (None, "out", seat) for h in state["held"]):
            return _ask(state, seat, "take", price=amount)
        return _next(state)
    if kind == FORCED_SALE:
        if not mine:
            return _next(state)
        if len(mine) == 1:
            return _forced_sale(state, seat, mine[0], amount)
        return _ask(state, seat, "forced", price=amount)
    if kind == PRIVATE_AUCTION:
        if not mine:
            return _next(state)
        if len(mine) == 1:
            return _open(state, mine[0], seat, seat, now)
        # The player on the lander's left chooses which goes on the block.
        return _ask(state, _left(state, seat), "pick", owner=seat)
    raise ValueError(kind)

def bid(state, seat, action, now):
    a = state["auction"]
    if state["phase"] != "auction" or not a:
        raise Illegal("Nothing is on the block.")
    if seat in a["barred"]:
        raise Illegal("You can't bid in this auction." if a["seller"] != seat else "You can't bid on your own painting.")
    if seat in a["out"]:
        raise Illegal("You've dropped out of this auction.")
    if a["high"] and a["high"]["seat"] == seat:
        raise Illegal("You're already the high bidder.")
    amount = action["amount"]
    least = next_bid(state)
    if type(amount) is not int or amount % RAISE:
        raise Illegal("Bid in fifty-thousands.")
    if amount < least:
        raise Illegal(f"The bid is already ${least - RAISE:,}." if a["high"] else f"Bidding opens at ${OPENING_BID:,}.")
    if amount > state["cash"][seat]:
        raise Illegal("You haven't the cash for that bid.")
    a["high"] = {"seat": seat, "amount": amount}
    a["bids"] += 1
    a["closes"] = now + state["clock"]
    log.event(state, "bid", seat=seat, amount=amount)
    _settle(state, now)

def _settle(state: dict, now: float) -> bool:
    """The gavel falls when time's up, or at once when everyone else is out."""
    a = state["auction"]
    if not a or (now < a["closes"] and bidders(state)):
        return False
    i, high, seller = a["painting"], a["high"], a["seller"]
    state["auction"] = None
    if not high:
        log.event(state, "no_sale", painting=i, art=state["art"][i], seller=seller)
        _next(state)
        return True
    seat, amount = high["seat"], high["amount"]
    state["cash"][seat] -= amount
    if seller == "bank":
        state["pile"].pop()
    else:
        state["cash"][seller] += amount
    _give(state, i, seat)
    log.event(state, "sold", painting=i, art=state["art"][i], seat=seat, price=amount, seller=seller)
    _next(state)
    return True

def bidders(state: dict) -> list[int]:
    """Who is still in the auction: not barred, not dropped out, not already
    the high bidder. Someone short of the next bid is still in until they
    drop out (or the clock runs out): the table never learns another
    player's cash from the gavel."""
    a = state["auction"]
    if not a:
        return []
    high = a["high"]["seat"] if a["high"] else None
    return [s for s in range(state["n"]) if s not in a["barred"] and s not in a["out"] and s != high]

def deciding(state: dict) -> list[tuple[int, str, str]]:
    phase = state["phase"]
    if phase == "start":
        return [(s, "start", "start") for s in range(state["n"]) if state["pos"][s] is None]
    if phase == "roll":
        return [(state["turn"], "roll", f"t{state['turns']}")]
    if phase == "move":
        return [(state["turn"], "move", f"t{state['turns']}-move")]
    if phase == "decide":
        p = state["pending"]
        return [(p["seat"], p["kind"], f"t{state['turns']}-{p['kind']}")]
    if phase == "auction":
        a = state["auction"]
        kinds = RAISE_KINDS if a["bids"] else OPEN_KINDS
        return [(s, kinds[(s + a["bids"]) % len(kinds)], f"a{a['id']}-{a['bids']}") for s in bidders(state)]
    return []

def _finish(state: dict) -> None:
    n = state["n"]
    seats = [{"cash": state["cash"][s], "paintings": [{"painting": i, "art": state["art"][i], "value": state["value"][i]}
                                                      for i in owned(state, s)],
              "worth": worth(state, s)} for s in range(n)]
    totals = [x["cash"] + x["worth"] for x in seats]
    for s, x in enumerate(seats):
        x["total"] = totals[s]
    places = rounds.places(totals, high=True)
    state["final"] = {"seats": seats, "places": places}
    state["winners"] = [s for s in range(n) if places[s] == 1]
    state["turn"] = None
    state["auction"] = None
    log.event(state, "over", totals=totals, winners=state["winners"])
    # Scores are kept in thousands: a table's score columns are whole numbers people read.
    rounds.score(state, [t // 1000 for t in totals])
    rounds.end(state, last=True)

def _card(state: dict, i: int, seat) -> dict:
    """A painting as a seat sees it: its artwork, where it is, and its value
    if this seat knows it."""
    out = {"painting": i, "art": state["art"][i]}
    if _knows(state, seat, i):
        out["value"] = state["value"][i]
    return out

def guess(v: dict) -> float:
    """What a painting this seat doesn't know is worth, on average."""
    left = unseen(v)
    return sum(left) / len(left) if left else 0.0

def space_worth(v: dict, seat: int, i: int) -> float:
    """Roughly what landing on space i gains this seat, by its own view:
    cash collected, a painting's worth over its price, what a private
    auction or the forced sale would fetch over what it gives up."""
    kind, amount = TRACK[i]
    mine = v["hung"][seat]
    cash = v["cash"][seat]
    avg = guess(v)
    pile = v["pile"]["count"] > 0
    if kind == COLLECT:
        return amount
    if kind == INHERIT:
        return avg if pile else 0
    if kind == BUY_BANK:
        return max(0.0, avg - amount) if pile and cash >= amount else 0
    if kind == BANK_AUCTION:
        return avg * 0.1 if pile else 0  # a chance at a bargain, for anyone
    if kind == BUY_PLAYER:
        theirs = [c for s, row in enumerate(v["hung"]) if s != seat for c in row]
        best = max((worth(v, c) for c in theirs), default=0)
        return max(0.0, best - amount) if cash >= amount else 0
    if kind == PRIVATE_AUCTION:
        # The others bid about an unknown painting's worth for one of ours.
        return sum(avg - worth(v, c) for c in mine) / len(mine) if mine else 0
    if kind == FORCED_SALE:
        return amount - min(worth(v, c) for c in mine) if mine else 0
    if kind == MAY_SELL:
        return avg * 0.05 if mine else 0  # a way to bank one, if it's wanted
    return 0

# Bots keep to the table's beats (table.js), so people can follow them: a
# roll waits for the last move to walk round and what its space did to be
# shown, a move for the dice to be seen. Bids come from three think times in
# turn, so no seat's bot always speaks first; the first bid in an auction
# waits for its splash to play out.
bot_think = {"start": 1.4, "roll": 2.8, "move": 1.6, "buy": 2.2, "sell": 2.2, "take": 2.4, "forced": 2.0, "pick": 2.2,
             "open0": 4.2, "open1": 5.0, "open2": 5.8, "bid0": 1.3, "bid1": 1.9, "bid2": 2.6}

def _at_risk(v: dict) -> float:
    """Above this, a painting is safer as cash: kept, it may go to a private
    auction (eight spaces on the board) at about an unknown painting's
    price, or be bought away for $400,000. Near the end the risk is
    small: what it's worth counts in full."""
    left = v["pile"]["count"]
    return guess(v) * (0.9 if left > 6 else 1.0 + (6 - left) * 0.15)

def options(raw: dict | None) -> dict:
    """A table's settings: the gallery that hangs, the auction clock and how
    fast the bots play. The rules leave nothing else to choose."""
    galleries = board.ids() or (board.DEFAULT,)
    return {
        "gallery": moves.choice(raw, "gallery", galleries, board.DEFAULT if board.DEFAULT in galleries else galleries[0]),
        "clock": moves.choice(raw, "clock", tuple(CLOCKS), "steady"),
        "bot_pace": moves.choice(raw, "bot_pace", tuple(moves.BOT_PACE), "brisk"),
    }

/** The gavel's words, by the seconds left: the high bid, then "Going once",
 * "Going twice". */
gavelWords(secs) {
  const a = this.v?.auction;
  if (!a) return '';
  const third = this.v.clock / 3;
  if (secs <= 0) return a.high ? 'Sold!' : 'No sale';
  // (a phone's small block has room for the seconds alone)
  if (!a.high) return this.board.block.clientWidth < 230 ? `${secs}s` : `Bidding open · ${secs}s`;
  if (secs <= third) return 'Going twice…';
  if (secs <= 2 * third) return 'Going once…';
  return `${secs}s`;
}

/** The bank's next painting, beside the board and never off screen (the
 * pile is face up, docs/auction-house.md: its top is everyone's to see):
 * what an Inherit, a Buy from the bank or a bank auction takes next. While
 * it's up for sale or on the block it says so; with the pile empty, that.
 * It changes as the table's beats play (bankHold, bankFor), so a painting
 * going up is still here to fly onto the easel. */
drawBank() {
  const v = this.v;
  if (!v || this.bankHold) return;
  const at = this.bankFor;
  const p = v.pending;
  let mode, card = null;
  if (at) ({ mode, card } = at);
  else if (!v.pile.count || !v.pile.top) mode = 'empty';
  else if (v.auction?.seller === 'bank') mode = 'block';
  else if (p?.kind === 'buy') mode = 'sale';
  else mode = 'next';
  if (mode !== 'empty' && !card) card = v.pile.top;
  if (mode === 'next' && !card) mode = 'empty';
  const key = [this.gal?.id, mode, card?.painting, mode === 'sale' ? p?.price : null, this.one];
  if (!this.changed('bank', key)) return;
  const work = this.work(card);
  const kicker = { next: 'Next from the bank', block: 'Up for auction now', sale: `For sale by the bank · ${short(p?.price || 0)}`, empty: 'Next from the bank' }[mode];
  // (prefixed: a bare "block" is the board's own block)
  this.el.bank.className = `bankstrip bank-${mode}`;
  this.el.bank.replaceChildren(
    mode === 'empty'
      ? h('span.bankart', h('span.frame.empty', { 'aria-hidden': 'true' }))
      : h('span.bankart', framed(this.gal?.id, work, card, {
        size: 0, tag: 'value' in card, cls: 'house-reach', lazy: false,
        label: work ? `${work.title}, ${work.artist}: look closer` : null,
        onclick: () => this.look([card]),
      })),
    h('span.banktext',
      h('span.bankkicker', kicker),
      mode === 'empty'
        ? [h('b.banktitle', `No ${this.many} left`), h('span.banksub', 'The bank’s pile is empty.')]
        : [h('b.banktitle', named(work)), work ? h('span.banksub', byWhom(work)) : null]));
}

/** The board's corners, the game's state at a glance: how many are left
 * in the bank's pile (the game ends when it's empty), and whose turn. */
drawCorners() {
  const v = this.v;
  const n = v.pile.count;
  if (this.changed('pile', [n, v.phase, this.one])) {
    const was = this.board.pileCorner.dataset.n;
    this.board.pileCorner.dataset.n = n;
    // (the countdown is the game's Figure, house rule 4: its number in ink,
    // named in soft ink under it)
    this.board.pileCorner.replaceChildren(
      h('b.cornernum.house-figure', { 'aria-hidden': 'true' }, v.phase === 'over' ? '0' : String(n)),
      h('span.house-figure-noun', { 'aria-hidden': 'true' }, `${n === 1 ? this.one : this.many} left`),
      h('span.sr-only', v.phase === 'over' ? `No ${this.many} left: sold out` : `${plural(n, this.one)} left in the bank’s pile`));
    if (was !== undefined && was !== String(n)) pulse(this.board.pileCorner);
  }
  const turn = v.phase === 'over' || v.phase === 'start' ? null : v.turn;
  // (a turn a bot is playing for you isn't yours to take: it's "Turn · You", in plain ink)
  const yours = turn !== null && this.you(turn) && !this.botted();
  if (this.changed('turncorner', [turn, v.phase, turn !== null && this.who(turn), yours])) {
    this.board.turnCorner.replaceChildren(...(turn === null
      // (before the first turn, no one's: the block says who's still choosing a place)
      ? (v.phase === 'start' ? [] : [h('span.cornerlabel', 'Sold out')])
      : [h('span.cornerlabel', yours ? 'Your turn' : 'Turn'),
        h('span.cornerwho', seatMark(turn, this.marks()[turn], { size: 26 }), h('b', this.who(turn)))]));
    this.board.turnCorner.classList.toggle('mine', yours);
    if (turn !== null && this.turnShown !== undefined && this.turnShown !== turn) pulse(this.board.turnCorner);
    this.turnShown = turn;
  }
}

/** What landing on a space does, in How to play's words (rules.js), for
 * its card: [title, the amount if it has one, what happens]. */
export function spaceRule(i, one = 'painting') {
  const [kind, amount] = TRACK[i];
  const m = amount ? money(amount) : null;
  const many = `${one}s`;
  switch (kind) {
    case 'collect': return ['Collect', m, 'The bank pays you this much.'];
    case 'inherit': return [`Inherit a ${one}`, null, `Take the top ${one} from the bank’s pile, free, with its value card.`];
    case 'bank': return ['Bank auction', null, `The top ${one} of the bank’s pile is auctioned. Everyone may bid, you too. The winner pays the bank.`];
    case 'buy': return ['Buy from the bank', m, `You may buy the top ${one} of the bank’s pile at this price. Pass (or be short of it), and it’s auctioned without you.`];
    case 'private': return ['Private auction', null, `One of your ${many} is auctioned to the others, and the winner pays you. If you have more than one, the player on your left chooses which. With none, nothing happens.`];
    case 'sell': return ['May sell to the bank', null, `You may sell one of your ${many} to the bank at its value, shown to everyone. Or keep them all.`];
    case 'take': return ['Buy from a player', m, `You may buy any one ${one} another player owns at this price, or none. They must sell.`];
    default: return ['Sell to the bank', m, `You must sell one of your ${many} to the bank at this price, whatever it’s worth; its value card stays hidden. With none, nothing happens.`];
  }
}

/** Where the k-th of n pieces on a space stands (the top one last): along
 * the ring's inner edge, fanned no wider than the space. */
spot(space, k, n) {
  const step = n > 1 ? Math.min(3.2, 4.4 / (n - 1)) : 0;
  return at(R_PIECE, angleOf(space) + (k - (n - 1) / 2) * step);
}

// The table's beats, so everyone can follow someone else's turn (the bots
// keep to them: rules.py bot_think): the dice held a moment, a piece's
// walk a space at a time, what its space did held on the block, Sold! held
// over the painting, a new auction's splash.
const BEAT = { dice: 700, step: 170, news: 1500, sold: 2400, splash: 3000 };

/** Something done to you on anyone's turn (your painting bought, your
 * private auction sold, an auction won): the house's announcement over
 * the board (docs/design-language.md, "Done to you"), the painting
 * slammed down beside the words, whatever you were doing and whatever
 * Banners says; then your collection lights up. The log says it to a
 * screen reader, so the announcement isn't read out too. */
tellYou({ kicker, title, sub }, e) {
  if (this.room.spectating || this.t.you === null) return;
  if (document.hidden) chime();
  const work = this.work(e);
  announce({ kicker, title, sub, art: work ? framed(this.gal?.id, work, null, { size: 84, tag: false }) : null }, {
    over: this.board.el, read: false, className: 'ah-announce',
    onend: () => { if (!this.closed) pulse(this.el.mine); },
  });
}

/** The gallery view: a painting as large as the window allows, in its gilt
 * frame on the salon wall, with its museum label, its value card when you
 * know it, and a way to the museum's own page. `items` is the set it was
 * opened from ({ work, card, note }), `at` which one; ← and → (or the
 * arrows) walk through the set. The card's picture shows at once, the
 * large one (galleries/<id>/large/) takes its place as it arrives. */
export function look(g, items, at = 0) {
  let i = at;
  const stage = h('div.viewstage');
  const label = h('div.viewlabel');
  const prev = h('button.viewnav.prev', { type: 'button', 'aria-label': 'The one before', onclick: () => go(-1) }, '‹');
  const next = h('button.viewnav.next', { type: 'button', 'aria-label': 'The next one', onclick: () => go(1) }, '›');
  const count = h('p.viewcount', { 'aria-live': 'polite' });
  const draw = () => {
    const { work, card, note } = items[i];
    const big = framed(g, work, card, { size: 0, tag: false, cls: 'viewframe', lazy: false });
    const img = big.querySelector('img');
    if (work) {
      const hi = new Image();
      hi.decoding = 'async';
      hi.onload = () => { if (img.isConnected) img.src = hi.src; };
      hi.src = new URL(`${g}/large/${work.id}.webp`, BASE).href;
      if (work.lw && work.lh) big.style.setProperty('--ratio', String(work.lw / work.lh));
    }
    const object = work?.kind === 'object';
    room.classList.toggle('objects', object);
    stage.replaceChildren(object
      // (an object stands in a glass vitrine on a plinth, under a spotlight
      // from the ceiling)
      ? h('div.shown',
        h('span.spot', { 'aria-hidden': 'true' }),
        h('div.vitrine', big, h('span.glass', { 'aria-hidden': 'true' })),
        h('span.plinth', { 'aria-hidden': 'true' }, h('span.plinthcap')))
      // (a painting hangs from the picture rail on two cords, under a brass
      // picture light that washes the wall above it)
      : h('div.hung',
        h('span.wash', { 'aria-hidden': 'true' }),
        h('span.cord.l', { 'aria-hidden': 'true' }), h('span.cord.r', { 'aria-hidden': 'true' }),
        h('span.lamp', { 'aria-hidden': 'true' }, h('span.lamparm'), h('span.lampbar')),
        big));
    const known = card && 'value' in card;
    label.replaceChildren(...[
      work ? h('h2.viewtitle', work.title) : null,
      work ? h('p.viewby', byWhom(work)) : null,
      work?.medium ? h('p.viewmedium', work.medium) : null,
      work ? h('p.viewmuseum', work.museum) : null,
      work?.source ? h('p.viewlink', h('a', { href: work.source, target: '_blank', rel: 'noopener' }, 'See it at the museum')) : null,
      known ? h(`p.viewvalue${card.value === 0 ? '.forgery' : ''}`, h('span', 'Value card'), h('b', valueWords(card.value))) : null,
      note ? h('p.viewnote', note) : null].filter(Boolean));
    count.textContent = items.length > 1 ? `${i + 1} of ${items.length}` : '';
    prev.hidden = next.hidden = items.length < 2;
  };
  const go = d => { i = (i + d + items.length) % items.length; draw(); };
  const room = h('div.viewroom',
    h('div.viewwall', h('span.rail', { 'aria-hidden': 'true' }),
      h('div.viewrow', prev, stage, label, next)),
    h('div.viewfloor', { 'aria-hidden': 'true' }, h('span.skirting')),
    count);
  const s = sheet(null, room, { wide: true, className: 'ah-view', label: 'Up close' });
  s.box.addEventListener('keydown', e => {
    if (items.length < 2 || e.altKey || e.metaKey || e.ctrlKey) return;
    if (e.key === 'ArrowLeft') { e.preventDefault(); go(-1); }
    if (e.key === 'ArrowRight') { e.preventDefault(); go(1); }
  });
  draw();
  return s;
}

/** What's yours to do now, and where: its kind, the moment it's for (a
 * new moment rings afresh), what to ring, and what a prompt says the
 * first time it falls to you in a game. `promptOnly`: no ring on a
 * routine turn (an auction you may sit out). */
cueFor() {
  const { v, t } = this;
  if (!v || t.you === null || t.seats[t.you]?.bot || v.phase === 'over' || this.room.spectating) return null;
  const c = v.can || {};
  const at = `t${v.turns}`;
  if (c.place) {
    return {
      kind: 'place', at: 'start', targets: () => this.board.halosOf(TRACK.keys()), into: () => this.board.block.querySelector('.blocknote') || this.board.block,
      say: { title: 'Place your piece', sub: 'Choose any space to start on. You don’t do what it says yet.' },
    };
  }
  if (c.move) {
    return {
      kind: 'move', at, into: () => this.board.pieceOf(t.you) || this.board.svg,
      targets: () => [...this.board.halosOf(c.move), ...(c.move.length > 1 ? [this.slots[0].el] : []), this.slots[3].el],
      say: { title: 'Choose which way', sub: `${this.rolled()}. You can go either way round: press one of the two spaces that light up.` },
    };
  }
  if (c.roll) return { kind: 'roll', at, targets: () => [this.slots[3].el] };
  // (your collection's panel, which stays as its paintings are drawn again)
  if (c.decide === 'sell' || c.decide === 'forced') return { kind: c.decide, at, targets: () => [this.el.mine] };
  if (v.auction && c.bid) {
    return {
      kind: 'bid', at: `a${v.auction.id}`, promptOnly: true, into: () => this.slots[3].el, targets: () => [this.slots[3].el],
      say: { title: 'Bid, or drop out', sub: 'Anyone may bid at any moment. The gavel falls a few seconds after the last bid.' },
    };
  }
  return null;
}