Add Playlist tab — cold-start non-gamer baseline UX

The Play tab requires a tester to load each pack manually, decode
jargon-heavy briefings, and figure out the command palette. A non-
gamer cold-clicking through that surface produces unreliable
human-baseline data.

The new Playlist tab is a separate top-level Gradio tab built on the
same `InteractiveSession` plumbing the Play tab and the 24-pack study
already use, so a Playlist run is still apples-to-apple with a model
run on the same scenario:

* a curated 20-pack list (`openra_bench.playlist.NOVICE_PLAYLIST`),
hand-picked from the 210 active packs for visual obviousness and
simple tool surface — easy-tier only, drive-and-shoot or drive-to-
ring objectives, no `repair`/`power_down`/`set_primary`/
`infiltrate`/`fire_superweapon`/`set_stance`;
* a 1-2 sentence plain-English objective above the minimap, sourced
from the pack `description` with the structured `WIN WHEN: …` /
`YOU LOSE IF: …` machine block stripped — the long version is
tucked behind a `Details` accordion;
* a render-time jargon dictionary (`JARGON_TO_PLAIN`) — `MCV` →
`base builder`, `harvester` → `miner`, `barracks` → `infantry
factory`, `war factory` → `tank factory`, `construction yard` →
`main base`, plus every short code (e1, 2tnk, pbox, …) — applied
to the briefing AND the unit-table `type` column at render time
ONLY; the YAML, engine, tool API, and playback transcripts stay
on the canonical names;
* an auto-advance state machine — when a game ends, the status line
shows `Game N of 20: WIN — next scenario in 5s. Click Skip wait ▶
to go now`; a `gr.Timer(1s)` polls and auto-advances after the
wait elapses;
* progress bar at the top — `Scenario 7 of 20 · player alex` plus
a 20-cell text bar `▮▮▮▮▮▮▮░░░░░░░░░░░░░ 35%`;
* a session-end summary table (per-pack outcome / turns / max-turns)
with a `Submit baseline` button that posts each game to the bench
raw-games log as `agent_type=Human` so the rows flow through the
existing leaderboard pipeline;
* the build textbox is hidden unless the active pack actually
authored a build verb in `tools:` — keeps the UI sparse for the
move-and-shoot majority;
* engine-wheel-absent path: a friendly `Run maturin develop --
release first` message instead of a stack trace.

`openra_bench/playlist.py` is the pure-Python plumbing — playlist
list, jargon dict, simplify_text / simplify_objective, the auto-
advance predicate, the progress-bar formatter, and the session-row
factory. All non-engine, so the new test module covers the playlist
composition, the substitution dictionary, the auto-advance state
machine (timing-window-based), and the progress bar — 16 cases, all
green.

The `Play` tab is unchanged — it stays the power-user / sandbox
surface. The 24-pack `Study` accordion inside `Play` is also
unchanged — it's still the canonical recruited-tester study.

openra_bench/playlist.py

@@ -0,0 +1,341 @@
+"""Non-gamer playlist — the 20-pack curated baseline.
+
+The 24-pack `human_study` (`openra_bench/human_study.py`) is built for
+recruited testers who can be expected to read jargon and grind through
+72 games. A non-gamer cold-clicking through the Play tab cannot do that
+— they need a curated, accessible 20-pack run that finishes in
+60-90 minutes WITHOUT requiring RTS knowledge.
+
+This module is the support data for the **Playlist** tab in `app.py`:
+
+* `NOVICE_PLAYLIST` — 20 hand-picked (pack, level) pairs whose
+  objective is visually obvious on the minimap and whose tool surface
+  fits the reduced palette (move / attack / build / end-turn). Each
+  pack chosen because:
+
+  - the objective is "drive your green units to the yellow ring" or
+    "kill the visible red enemies" (no jargon decoding required);
+  - the tool surface is `move_units` + `attack_unit` (and at most
+    `build` for one or two build-tier picks); no `repair`,
+    `power_down`, `set_primary`, `infiltrate`, `fire_superweapon`,
+    `set_stance`;
+  - the timer is generous (≥30 decision turns at easy/medium);
+  - the easy-level WIN bar has been verified by an intended scripted
+    policy in the existing test suite.
+
+* `JARGON_TO_PLAIN` — the render-time substitution dict that converts
+  RTS shorthand ("MCV", "harvester", "barracks") into plain English
+  ("base builder", "miner", "infantry factory") for the simplified
+  briefing. Applied at the UI layer ONLY — the underlying YAML, the
+  engine, the tool API, the playback transcript still use the canonical
+  short codes, so a Playlist-mode run is still apples-to-apple with a
+  model run on the same pack.
+
+* `simplify_briefing` / `simplify_objective` — apply
+  `JARGON_TO_PLAIN` to a string. Used by the Playlist tab to produce
+  the 1-2 sentence plain-English objective shown above the minimap.
+
+* `playlist_progress(idx, total)` — turn (i, n) into a 0..1 fraction
+  for the progress bar.
+
+Auto-advance state-machine:
+* `playlist_should_advance(status, last_done_at, now, wait_seconds)`
+  — True if a game is over AND the wait countdown has elapsed.
+
+Everything here is pure-Python, no engine handles required, so the
+playlist plumbing tests run even when the Rust wheel is absent.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable
+
+# ── The curated 20-pack list ────────────────────────────────────────
+# Hand-picked from the 210 active packs for accessibility:
+# - visually obvious objective (yellow ring or visible red enemies)
+# - reduced tool surface (move + attack only, in most cases)
+# - generous timer (≥30 decision turns)
+# - easy tier — never medium/hard for a non-gamer
+#
+# Stratified across 5 capability buckets so the player sees variety:
+#   * 8 combat (move tanks, kill visible enemies)
+#   * 4 coordination (move multiple groups)
+#   * 4 defense (stay near base, kill incoming)
+#   * 2 reach-region (drive to yellow ring)
+#   * 2 multi-objective (split groups between rings)
+#
+# Why each pack made the cut (one-liner per pack — also doc'd in the
+# tab's preset description):
+NOVICE_PLAYLIST: list[tuple[str, str]] = [
+    # ── Combat — kill the visible red enemies ────────────────────
+    # 4 tanks vs visible static squad; just drive east and shoot.
+    ("combat-focus-fire-priority", "easy"),
+    # Two groups converge, fight at one point — visible attack target.
+    ("combat-pincer-coordination", "easy"),
+    # 4 tanks, single visible enemy line — straight-line attack.
+    ("combat-flanking-attack", "easy"),
+    # 5 tanks east through fire corridor — push through.
+    ("combat-formation-tank-wedge", "easy"),
+    # 4 tanks vs 2 visible clusters — pick one, then the other.
+    ("combat-divide-and-conquer", "easy"),
+    # Hold a chokepoint vs incoming — defensive but visible.
+    ("combat-hold-chokepoint", "easy"),
+    # Skirmish + back off — one engagement, visible enemy.
+    ("combat-skirmish-then-disengage", "easy"),
+    # 4 tanks retreat and re-engage — visible enemy, simple.
+    ("combat-retreat-after-engagement", "easy"),
+
+    # ── Coordination — move multiple groups ──────────────────────
+    # 6 tanks west edge → punch east, converge on objective.
+    ("coord-mutual-support", "easy"),
+    # 3 columns from 3 bearings — pick one ring at a time.
+    ("coord-converge-on-target", "easy"),
+    # 2 squads cross fire zone — staggered move.
+    ("coord-cover-and-move", "easy"),
+    # Multi-region: move 2 units into each of 2 yellow rings.
+    ("action-multiunit-coordination", "easy"),
+
+    # ── Defense — stay near base, kill incoming ──────────────────
+    # Defenders hold base vs probing raiders — wait + shoot.
+    ("proc-only-defend-no-attack", "easy"),
+    # Heavy assault on base — fall back to evac point.
+    ("def-evacuation", "easy"),
+    # Waves from multiple directions — distribute defenders.
+    ("def-multi-direction", "easy"),
+    # Mobile reserve plugs the breach — react to single lane.
+    ("def-reinforce-the-breach", "easy"),
+
+    # ── Reach-region — drive to the yellow ring ──────────────────
+    # Bait-counter — guard line; pull tigers off the mountain.
+    ("artofwar-lure-the-tiger", "easy"),
+    # 4 tanks face cluster behind fog — drive east, kill.
+    ("combat-attack-from-behind-fog", "easy"),
+
+    # ── Multi-objective easier ───────────────────────────────────
+    # Visible counter-attack target — bait then kill.
+    ("combat-bait-counter-attack", "easy"),
+    # 3 fast jeeps kite a heavy tank — visible single target.
+    ("combat-kite-jeep-vs-tank", "easy"),
+]
+
+
+# ── Render-time jargon substitutions ─────────────────────────────────
+# RTS shorthand → plain English. Applied at the UI rendering layer
+# ONLY (briefings, unit-table type column). The engine, tool API, YAML
+# pack files, playback transcripts, and command translator continue to
+# use the canonical short codes — so the underlying run is still
+# apples-to-apple with a model run on the same scenario.
+#
+# Keys are matched as whole words/phrases (case-insensitive). Longer
+# multi-word keys are applied first so "construction yard" wins over
+# "yard". Short-code keys (mcv, harv) are matched as whole words so
+# "harvester" doesn't double-substitute.
+JARGON_TO_PLAIN: dict[str, str] = {
+    # Buildings — full names FIRST so "construction yard" beats "yard".
+    "construction yard": "main base",
+    "ore refinery": "miner depot",
+    "war factory": "tank factory",
+    "tank factory": "tank factory",  # passthrough; keeps display stable
+    "service depot": "repair shop",
+    "advanced power plant": "big power plant",
+    "barracks": "infantry factory",
+    "soviet barracks": "infantry factory",
+    "allied barracks": "infantry factory",
+    "ore silo": "ore storage",
+    "radar dome": "radar",
+    # Units — full names.
+    "harvester": "miner",
+    "rocket soldier": "rocket trooper",
+    "rifle infantry": "rifleman",
+    "rifle soldier": "rifleman",
+    "grenadier": "grenade trooper",
+    "engineer": "engineer",  # passthrough — already plain
+    "medium tank": "medium tank",  # passthrough
+    "heavy tank": "heavy tank",
+    "mammoth tank": "mammoth tank",
+    "light tank": "light tank",
+    "anti-tank": "anti-tank",
+    # Defenses.
+    "pillbox": "guard tower",
+    "tesla coil": "lightning tower",
+    "anti-aircraft": "anti-air",
+    "turret": "guard turret",
+    # Short codes — whole-word match keeps these from clobbering
+    # multi-letter words.
+    "mcv": "base builder",
+    "harv": "miner",
+    "fact": "main base",
+    "proc": "miner depot",
+    "powr": "power plant",
+    "apwr": "big power plant",
+    "barr": "infantry factory",
+    "tent": "infantry factory",
+    "weap": "tank factory",
+    "hpad": "helipad",
+    "afld": "airfield",
+    "fix": "repair shop",
+    "dome": "radar",
+    "silo": "ore storage",
+    "pbox": "guard tower",
+    "hbox": "guard tower",
+    "tsla": "lightning tower",
+    "gun": "guard turret",
+    "sam": "anti-air",
+    # Unit short codes.
+    "1tnk": "light tank",
+    "2tnk": "medium tank",
+    "3tnk": "heavy tank",
+    "4tnk": "mammoth tank",
+    "e1": "rifleman",
+    "e2": "grenade trooper",
+    "e3": "rocket trooper",
+    "e6": "engineer",
+    "arty": "artillery",
+    "apc": "transport",
+    "jeep": "jeep",
+    "lst": "landing craft",
+    "dog": "attack dog",
+}
+
+
+# Pre-compile a single regex: longest keys first, escaped, word-bounded.
+def _compile_jargon_pattern() -> "re.Pattern[str]":
+    keys = sorted(JARGON_TO_PLAIN.keys(), key=len, reverse=True)
+    # Use lookarounds so short codes (e1, mcv) only match as whole
+    # tokens — but multi-word keys like "ore refinery" still match the
+    # full phrase even with internal spaces.
+    parts = []
+    for k in keys:
+        esc = re.escape(k)
+        parts.append(rf"(?<![A-Za-z0-9_-]){esc}(?![A-Za-z0-9_-])")
+    return re.compile("|".join(parts), flags=re.IGNORECASE)
+
+
+_JARGON_RE = _compile_jargon_pattern()
+
+
+def simplify_text(text: str) -> str:
+    """Apply `JARGON_TO_PLAIN` substitutions to a single string. The
+    match is case-insensitive, but each replacement is lowercased so
+    the briefing reads as plain prose — `MCV` and `mcv` both render
+    as `base builder`."""
+    if not text:
+        return text
+
+    def _sub(m: "re.Match[str]") -> str:
+        return JARGON_TO_PLAIN[m.group(0).lower()]
+
+    return _JARGON_RE.sub(_sub, text)
+
+
+def simplify_objective(text: str, max_chars: int = 320) -> str:
+    """One-or-two-sentence plain-English objective for the Playlist
+    panel. Strips the structured `WIN WHEN: …` / `YOU LOSE IF: …`
+    suffix `objective_brief` appends — those are jargon-heavy and
+    we surface them behind the **Details** expand instead."""
+    if not text:
+        return text
+    plain = simplify_text(text)
+    # Drop everything from the structured WIN/LOSE machine block onward.
+    for marker in ("WIN WHEN:", "YOU LOSE IF:", "You have at most"):
+        idx = plain.find(marker)
+        if idx >= 0:
+            plain = plain[:idx]
+    plain = plain.strip()
+    # Keep the first 1-2 sentences; cap at max_chars.
+    sentences = re.split(r"(?<=[.!?])\s+", plain)
+    out = " ".join(sentences[:2]).strip()
+    if len(out) > max_chars:
+        out = out[: max_chars - 1].rstrip() + "…"
+    return out
+
+
+# ── Reduced command palette — what the Playlist tab exposes ────────
+# A non-gamer never needs `repair`, `power_down`, `set_primary`,
+# `infiltrate`, `fire_superweapon`, `set_stance`. The Playlist tab
+# only exposes:
+#   * `move`         — click-and-drag on minimap (already wired)
+#   * `attack`       — click an enemy with units selected
+#   * `build`        — the textbox already there (only when needed)
+#   * `end turn`     — the button at the bottom
+PLAYLIST_TOOLS: tuple[str, ...] = (
+    "move_units", "attack_unit", "attack_move", "stop", "build",
+)
+
+
+def needs_build_tool(pack_tools: Iterable[str] | None) -> bool:
+    """True if the pack's authored `tools:` list contains `build`
+    (or a build-tier verb like `place_building`). For Playlist mode
+    the Build textbox is hidden unless the pack actually requires it
+    — keeps the UI sparse for the (majority) move-and-shoot scenarios.
+    """
+    if not pack_tools:
+        return False
+    s = {str(t).lower() for t in pack_tools}
+    return bool(s & {"build", "place_building", "cancel_production"})
+
+
+# ── Auto-advance state machine ───────────────────────────────────────
+# A 5-second countdown shown after game-over, then auto-load next pack.
+
+AUTO_ADVANCE_WAIT_SECONDS = 5.0
+
+
+def playlist_should_advance(
+    done: bool,
+    done_at: float | None,
+    now: float,
+    wait_seconds: float = AUTO_ADVANCE_WAIT_SECONDS,
+) -> bool:
+    """True if the current scenario is over AND the post-game wait has
+    elapsed — the auto-advance timer should fire NEXT.
+
+    `done_at` is the wall-clock timestamp at which the session first
+    transitioned to `done`. The first poll after game-over passes
+    `done_at = now`; subsequent polls compare the elapsed delta. A
+    `done=False` always returns False (we never advance mid-game)."""
+    if not done or done_at is None:
+        return False
+    return (now - done_at) >= max(0.0, wait_seconds)
+
+
+def playlist_progress(idx: int, total: int) -> float:
+    """0..1 fraction for the progress bar — `idx` games completed out
+    of `total`. Clamped — over-/under-flow is a UI input bug, not a
+    crash."""
+    if total <= 0:
+        return 0.0
+    return max(0.0, min(1.0, float(idx) / float(total)))
+
+
+def playlist_progress_bar(idx: int, total: int, width: int = 20) -> str:
+    """Plain-text progress bar — '▮▮▮▮▮▮▮▮░░░░░░░░░░░░░  35%'. Used
+    when a Markdown pre-formatted block is preferable to a real
+    `gr.Progress` (e.g. inside a Markdown block on tab-load before
+    any state has been set)."""
+    frac = playlist_progress(idx, total)
+    filled = int(round(frac * width))
+    bar = "▮" * filled + "░" * (width - filled)
+    return f"{bar}  {int(round(frac * 100))}%"
+
+
+def session_summary_row(
+    idx: int,
+    pack: str,
+    level: str,
+    outcome: str,
+    turns: int,
+    max_turns: int,
+) -> dict:
+    """One row of the session-end summary table — same shape across
+    Playlist tab and the underlying playback manifest, so the summary
+    is sourced from the same place every time."""
+    return {
+        "Game": idx + 1,
+        "Scenario": pack,
+        "Level": level,
+        "Outcome": (outcome or "draw").upper(),
+        "Turns": int(turns or 0),
+        "Max Turns": int(max_turns or 0),
+    }

tests/test_playlist.py

@@ -0,0 +1,248 @@
+"""Tests for the non-gamer **Playlist** mode plumbing.
+
+The Playlist tab is the cold-start human-baseline UX (`Playlist`
+gradio tab in `app.py`); these tests cover the pure-Python plumbing
+that backs it — playlist composition, the jargon-substitution
+dictionary, the auto-advance state machine, and the progress bar.
+
+Live-engine bits are guarded by the conftest engine-token list (the
+playlist runtime opens an `InteractiveSession` exactly like the
+24-pack `human_study`, so the same skip rule covers it for free)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from openra_bench.playlist import (
+    AUTO_ADVANCE_WAIT_SECONDS,
+    JARGON_TO_PLAIN,
+    NOVICE_PLAYLIST,
+    PLAYLIST_TOOLS,
+    needs_build_tool,
+    playlist_progress,
+    playlist_progress_bar,
+    playlist_should_advance,
+    session_summary_row,
+    simplify_objective,
+    simplify_text,
+)
+
+PACKS = Path(__file__).parent.parent / "openra_bench" / "scenarios" / "packs"
+
+
+# ── 20-pack curated list ─────────────────────────────────────────────
+
+
+def test_curated_playlist_is_exactly_20_easy_packs():
+    """The non-gamer playlist must be EXACTLY 20 (pack, level) pairs —
+    a tester completes it in 60-90 minutes; more is fatigue, less
+    leaves the human-baseline data underpowered."""
+    assert len(NOVICE_PLAYLIST) == 20
+    assert len(set(NOVICE_PLAYLIST)) == 20  # no duplicates
+    for pack, level in NOVICE_PLAYLIST:
+        # Easy tier only — non-gamer accessibility.
+        assert level == "easy", (pack, level)
+
+
+def test_every_curated_pack_exists_on_disk():
+    """A pack id in the playlist must resolve to a real YAML file —
+    catches typos at test time, not at gradio-launch time."""
+    for pack, _level in NOVICE_PLAYLIST:
+        assert (PACKS / f"{pack}.yaml").exists(), pack
+
+
+def test_curated_playlist_capability_spread():
+    """The 20-pack list is stratified — combat / coordination /
+    defense / multi-objective. A monoculture is bad UX (non-gamer
+    sees the same scenario type 20 times)."""
+    prefixes = {pack.split("-", 1)[0] for pack, _ in NOVICE_PLAYLIST}
+    # We expect at least 4 distinct family prefixes (combat, coord,
+    # def, action / artofwar / proc). The exact composition can shift
+    # if a pack is retired; the spread invariant is what we pin.
+    assert len(prefixes) >= 4, sorted(prefixes)
+
+
+# ── Jargon dictionary ────────────────────────────────────────────────
+
+
+def test_jargon_dict_covers_required_substitutions():
+    """The CLAUDE.md / task spec calls out specific jargon every UI
+    string must replace. Pin the must-have substitutions here so a
+    later refactor can't regress them."""
+    required = {
+        "mcv": "base builder",
+        "harvester": "miner",
+        "barracks": "infantry factory",
+        "war factory": "tank factory",
+        "construction yard": "main base",
+    }
+    for k, v in required.items():
+        assert k in JARGON_TO_PLAIN, k
+        assert JARGON_TO_PLAIN[k] == v, (k, JARGON_TO_PLAIN[k], v)
+
+
+def test_simplify_text_replaces_short_codes_and_phrases():
+    """`simplify_text` is the render-time substitution. Both the long
+    name ('barracks') and the short code ('barr') resolve, the result
+    is lowercased, and case-insensitive matching catches `MCV`."""
+    s = "MCV deploys; harvester returns to refinery; build a barracks."
+    out = simplify_text(s)
+    # MCV → base builder; harvester → miner; refinery → miner depot
+    # (via 'ore refinery' is multi-word so partial 'refinery' alone is
+    # not in the dict — keep the assertion to the dict's contents).
+    assert "MCV" not in out
+    assert "base builder" in out
+    assert "miner" in out
+    assert "infantry factory" in out
+    # Short codes match too — pin both axes.
+    assert simplify_text("e1") == "rifleman"
+    assert simplify_text("2tnk") == "medium tank"
+    # Whole-word: 'mcvent' must NOT match `mcv`.
+    assert simplify_text("mcvent") == "mcvent"
+
+
+def test_simplify_objective_strips_machine_block():
+    """The Playlist plain-English objective drops the structured
+    `WIN WHEN: …` / `YOU LOSE IF: …` machine block — those go behind
+    the 'Details' expand."""
+    raw = (
+        "Drive your medium tanks east and kill the rocket soldiers.\n"
+        "WIN WHEN: units_killed_gte:5 AND within_ticks:2700.\n"
+        "YOU LOSE IF: not units_lost_lte:1.\n"
+        "You have at most 30 decision turns; acting decisively..."
+    )
+    out = simplify_objective(raw)
+    assert "WIN WHEN" not in out
+    assert "YOU LOSE IF" not in out
+    assert "decision turns" not in out
+    # Plain-English content survives, with substitutions applied.
+    assert "tank" in out.lower()
+    assert "rocket trooper" in out.lower() or "rocket" in out.lower()
+
+
+def test_simplify_objective_caps_length():
+    """Non-gamer should see ~1-2 sentences. A wall-of-text briefing
+    must be truncated."""
+    long_raw = "First sentence. " * 200
+    out = simplify_objective(long_raw, max_chars=200)
+    assert len(out) <= 200
+
+
+# ── Reduced command palette ─────────────────────────────────────────
+
+
+def test_playlist_tools_excludes_advanced_verbs():
+    """A non-gamer must not see `repair`, `power_down`, `set_primary`,
+    `infiltrate`, `fire_superweapon`, `set_stance` in playlist mode."""
+    forbidden = {
+        "repair", "power_down", "set_primary", "infiltrate",
+        "fire_superweapon", "set_stance",
+    }
+    assert not (set(PLAYLIST_TOOLS) & forbidden)
+
+
+def test_needs_build_tool_only_for_build_packs():
+    """`needs_build_tool` is the gate that hides the build textbox
+    unless the pack authored a `build`/`place_building` tool."""
+    assert needs_build_tool(["move_units", "attack_unit"]) is False
+    assert needs_build_tool(["build", "move_units"]) is True
+    assert needs_build_tool(["place_building"]) is True
+    assert needs_build_tool(None) is False
+    assert needs_build_tool([]) is False
+
+
+# ── Auto-advance state machine ──────────────────────────────────────
+
+
+def test_should_advance_only_when_game_done():
+    """Mid-game polls never advance — the only escape is a finished
+    game whose 5-second wait window has elapsed."""
+    # Mid-game: never advances regardless of wall-clock.
+    assert playlist_should_advance(False, None, now=0.0) is False
+    assert playlist_should_advance(False, 0.0, now=999.0) is False
+
+
+def test_should_advance_after_wait_window_elapses():
+    """After game-over, advance fires only once `wait_seconds` have
+    passed since the `done_at` timestamp. Pin both edges of the
+    window — just-before stays put, just-after advances."""
+    done_at = 100.0
+    wait = AUTO_ADVANCE_WAIT_SECONDS
+    # Just after game ends — wait not yet elapsed.
+    assert playlist_should_advance(True, done_at, now=done_at + 0.1) is False
+    # Half-way through the wait — still pending.
+    assert (
+        playlist_should_advance(True, done_at, now=done_at + wait / 2)
+        is False
+    )
+    # Wait fully elapsed — advance.
+    assert (
+        playlist_should_advance(True, done_at, now=done_at + wait)
+        is True
+    )
+    # Long after — still True (no upper bound).
+    assert (
+        playlist_should_advance(True, done_at, now=done_at + 999)
+        is True
+    )
+
+
+def test_should_advance_handles_none_done_at():
+    """If `done=True` but the timestamp was never recorded
+    (defensive — shouldn't happen, but the state machine must not
+    crash), we DON'T advance — better to leave the user the manual
+    'Skip wait' button than auto-advance from an unknown state."""
+    assert playlist_should_advance(True, None, now=0.0) is False
+
+
+def test_should_advance_custom_wait():
+    """Wait-seconds is a parameter, not a constant — a hypothetical
+    test mode could set it to 0 to skip the countdown."""
+    assert playlist_should_advance(True, 50.0, now=50.0, wait_seconds=0.0) is True
+
+
+# ── Progress bar ────────────────────────────────────────────────────
+
+
+def test_progress_fraction_clamped():
+    """Out-of-range inputs clamp to [0, 1] rather than crashing."""
+    assert playlist_progress(0, 20) == pytest.approx(0.0)
+    assert playlist_progress(10, 20) == pytest.approx(0.5)
+    assert playlist_progress(20, 20) == pytest.approx(1.0)
+    assert playlist_progress(-1, 20) == pytest.approx(0.0)
+    assert playlist_progress(99, 20) == pytest.approx(1.0)
+    # Zero total — defensive default 0, no division-by-zero.
+    assert playlist_progress(5, 0) == pytest.approx(0.0)
+
+
+def test_progress_bar_text_format():
+    """The text bar carries 20 cells + a trailing percent. Empty,
+    half, and full are pinned — the cell glyphs are part of the UX
+    contract, not arbitrary."""
+    assert playlist_progress_bar(0, 20).startswith("░" * 20)
+    assert "0%" in playlist_progress_bar(0, 20)
+    assert "50%" in playlist_progress_bar(10, 20)
+    assert "100%" in playlist_progress_bar(20, 20)
+    full = playlist_progress_bar(20, 20)
+    assert full.startswith("▮" * 20)
+
+
+def test_session_summary_row_shape():
+    """The session-end summary uses the same row schema across the
+    playlist UI and the playback manifest — pin the column names so
+    a downstream consumer (results.csv export) doesn't break silently.
+    """
+    row = session_summary_row(
+        idx=4, pack="combat-focus-fire-priority", level="easy",
+        outcome="win", turns=12, max_turns=30,
+    )
+    assert row == {
+        "Game": 5,
+        "Scenario": "combat-focus-fire-priority",
+        "Level": "easy",
+        "Outcome": "WIN",
+        "Turns": 12,
+        "Max Turns": 30,
+    }