Build Tabras card duel prototype

.gitignore

@@ -51,6 +51,10 @@ coverage.xml
 .pytest_cache/
 cover/
 
+# Local artifacts
+.DS_Store
+models/
+
 # Translations
 *.mo
 *.pot

README.md

@@ -21,7 +21,7 @@ The model NEVER sets final power values. This is what makes generated cards bala
 - **20 HP** per player.
 - **Energy** ramps each turn (1 → up to 5). Regenerating pool, no lands.
 - **Paired-round turns:** each round both players act; a flip decides order within the round. Knowing/manipulating order is a mechanic (Ice's Initiative).
-- **15-card deck:** 8 standardized backbone cards (same for all schools) + 7 LLM-generated synergy picks (drafted, deck-aware).
+- **15-card deck:** 6 standardized backbone cards (same for all schools) + 9 LLM-generated synergy picks (drafted, deck-aware).
 - **Deck-out:** no reshuffle. Drawing from an empty deck deals escalating fatigue damage (1, 2, 3, …) — a finishing clock, not a managed resource. Decks are damage-dense; you're expected to win before decking out.
 - **Win:** reduce the opponent to 0 across a three-phase duel.
 
@@ -40,9 +40,9 @@ The LLM composes cards by selecting from these and writing flavor; the engine as
 3. **Bomb** — big delayed burst: deal X in N turns, telegraphed. High-variance. TUNE. *Deferred-timer effect.* (Fire signature pick: 4 energy → 9 damage in 3 turns.)
 
 ### Defense / survival (a first-class, flexible axis — defense enables real strategic options, not just a tax)
-4. **Block** — temporary shield, this turn only. **Stacks.** `1 pt ≈ 3 block` (defense priced slightly cheaper than damage).
+4. **Block** — temporary shield until your next turn. **Stacks.** `1 pt ≈ 3 block` (defense priced slightly cheaper than damage).
 5. **Ward** — persistent shield. **Stacks. Expensive: `1 pt = 1 block`.** All-or-nothing: a ward can only be removed early by a *single hit meeting its threshold* — chip/multi-hit damage bounces off. The breaking hit is **fully absorbed** (a bubble that eats one decisive blow, then vanishes — excess does NOT carry to HP). [DEFAULT — override if you want break-through.] *Deferred/persistent-timer effect.*
-6. **Weak** — enemy deals Y less damage next turn. Defensive (damage-prevention). Prices like Block (linear). Mirror of Vulnerable.
+6. **Weak** — opponent deals Y less damage until your next turn. Defensive (damage-prevention). Prices like Block (linear). Mirror of Vulnerable.
 
 > Heal is intentionally NOT a primitive (cut for pace — healing prolongs fights against the short-aggressive goal). Defensive flexibility comes from Block + Ward + Weak instead. Revisit only if playtest shows fights ending too fast.
 
@@ -55,7 +55,7 @@ The LLM composes cards by selecting from these and writing flavor; the engine as
 10. **Multi-hit** — apply an effect N times. *Multiplies* the cost of what it hits. The single most dangerous primitive (multi-hit × Deal or × Burn). Overcost hard. Note: multi-hit chip CANNOT break a Ward (each hit is below threshold) — built-in school counterplay.
 11. **Vulnerable** — enemy takes X more damage for N turns. Offensive *multiplier* — combos with Deal/Multi-hit. Prices as a multiplier, not flat. TUNE.
 12. **Conditional** — "if [state], then bonus" (e.g., if enemy below half HP, +damage). Depth via sequencing; prices by how often the condition is live. TUNE.
-13. **Scaling** — effect grows with a counter (cards played this turn, damage taken, turns elapsed). Snowball primitive — overcost, runaway games start here. TUNE.
+13. **Scaling** — effect grows with a counter (cards played this turn, banked shield charge, turns elapsed). Snowball primitive — overcost, runaway games start here. TUNE. Earth scaling spends banked shield charge.
 
 ### Vulnerable / Weak pair
 Vulnerable (enemy *takes* X more — affects damage you deal) and Weak (enemy *deals* Y less — affects damage you take) are mirrored levers. Despite the symmetry they price differently: Vulnerable is a multiplier (TUNE), Weak is flat damage-prevention (linear, like Block).
@@ -65,7 +65,7 @@ Burn, Bomb, and Ward all run on ONE shared deferred/persistent-effect timer syst
 
 ---
 
-## The 8-card standardized backbone (same for every school)
+## The 6-card standardized backbone (same for every school)
 
 | Card | Cost | Effect |
 |------|------|--------|
@@ -74,9 +74,7 @@ Burn, Bomb, and Ward all run on ONE shared deferred/persistent-effect timer syst
 | Attack (strong) | 5 | deal 6 |
 | Block (weak) | 2 | block 3 |
 | Block (medium) | 3 | block 4 |
-| Block (strong) | 4 | block 5 |
 | Draw (small) | 2 | draw 1 |
-| Draw (large) | 3 | draw 2 |
 
 Identical across all schools. Only art/flavor reskins per run's theme. School identity lives entirely in the **draft pool**, not the backbone.
 
@@ -84,7 +82,7 @@ Identical across all schools. Only art/flavor reskins per run's theme. School id
 
 ## Schools (v1: three)
 
-School biases which primitives your 7 synergy picks draw from (a synergizable archetype), not your backbone. Theme = aesthetics only.
+School biases which primitives your 9 synergy picks draw from (a synergizable archetype), not your backbone. Theme = aesthetics only.
 
 Schools map to **player temperaments**, not just primitive bundles — the choice signals how you want to play:
 
@@ -93,7 +91,7 @@ Schools map to **player temperaments**, not just primitive bundles — the choic
   Signature pick (bomb): `4 energy: 9 damage, detonates in 3 turns`.
 - **Ice — speed (fast tempo).** For players who race: strike first, amplify, burst. NOT defensive — Ice outruns rather than turtles, so it carries no Block. Primitives: Initiative, Vulnerable, Multi-hit, Conditional.
   Anchor: `3 energy: deal 2, opponent goes second next round`.
-- **Earth — slow (durable control).** For players who outlast: grind, stack defense, win late. Defense concentrates HERE deliberately — this is the school's identity, not a tax. Primitives: Ward, Block, Scaling, Conditional.
+- **Earth — slow (durable control).** For players who outlast: grind, stack defense, win late. Half of damage absorbed by Block, rounded down, banks as shield charge; Ward does not bank charge. Earth Scaling releases that banked charge as burst damage, then empties it. Defense concentrates HERE deliberately — this is the school's identity, not a tax. Primitives: Ward, Block, Scaling, Conditional.
   Anchor (refreshing ward): `4 energy: block 3 per turn for the next 2 turns`.
 
 Defense is deliberately NOT spread evenly: it concentrates in Earth (the slow school), is absent from Ice (speed doesn't block, it races), and is incidental in Fire (burn just out-damages). This makes the three schools feel different to *play*, not just to read.
@@ -112,6 +110,33 @@ Three models; two satisfy the Nemotron + MiniCPM sponsor requirement:
 
 **Real constraint is VRAM on the Space GPU, not the 32B rule.** A 30B-A3B boss needs full weights resident even though MoE keeps active params ~3B. Picker and boss can share one base model in two isolated contexts if VRAM is tight; the boss context must NOT see card-authoring history.
 
+Local model wiring supports three modes:
+
+```bash
+# MiniCPM through an OpenAI-compatible local chat server.
+TABRAS_CARD_ENDPOINT=http://localhost:8080/v1/chat/completions
+TABRAS_CARD_MODEL=minicpm-v-4.6
+
+# MiniCPM direct Transformers model.chat path.
+TABRAS_CARD_BACKEND=transformers
+TABRAS_CARD_MODEL=openbmb/MiniCPM-V-4
+
+# Nemotron through an OpenAI-compatible chat server.
+TABRAS_AI_BOSS=1
+TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/chat/completions
+TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
+
+# Nemotron through a completion server with the documented <extra_id_*> prompt markers.
+TABRAS_AI_BOSS=1
+TABRAS_BOSS_BACKEND=completion
+TABRAS_BOSS_ENDPOINT=http://localhost:8081/v1/completions
+
+# Nemotron direct Transformers path using tokenizer.apply_chat_template.
+TABRAS_AI_BOSS=1
+TABRAS_BOSS_BACKEND=transformers
+TABRAS_BOSS_MODEL=nvidia/Nemotron-Mini-4B-Instruct
+```
+
 ---
 
 ## Components
@@ -132,7 +157,7 @@ Deterministic. Paired-round turn loop, energy ramp, initiative flip, card resolu
 Boss drafts its own deck from `generator.py` (synergy-biased) and the boss LLM plays it — picks pre-costed cards reactively. Boss cards capped at generation → play is inherently damage-bounded. 3 phases = 3 escalating drafted wizards (rising budget/energy). Phase N+1's deck generates during phase N combat.
 
 ### `draft.py`
-8 backbone + 7 deck-aware synergy picks = 15. Draft UI structure is a thin swappable layer — finalize after core playtests.
+6 backbone + 9 deck-aware synergy picks = 15. Draft UI structure is a thin swappable layer — finalize after core playtests.
 
 ### `app.py`
 Gradio Space. Cards = styled containers in rows. No engine, no animations. Core state (both HP, enemy intent, energy, card costs/effects) ALWAYS visible — never behind hover. Effect text TEMPLATED from the primitive schema (fixed per-primitive format), never free prose — parses in ~1s. Custom themed frames (Custom UI badge). Landing/menu loads model-free; generation fires on "Start," not page load (protects compute + cold-start UX).
@@ -165,7 +190,7 @@ Art, fine-tuning, polish come LAST. A playable, fun, text-only core is submittab
 - The model never sets numbers (except the engine-bounded, hard-capped miracle roll).
 - No board-state entities. Burn/Bomb/Ward/summons are deferred *effects*, never targetable units.
 - v1 scope is fixed: spell-only, 3 schools (Fire/Ice/Earth) × 3 themes, one art style. "If time permits" features stay deferred until the core ships and is tuned.
-- The 7 synergy picks must be generated **deck-aware** — picks that ignore the current deck reduce the generator to a random table.
+- The 9 synergy picks must be generated **deck-aware** — picks that ignore the current deck reduce the generator to a random table.
 
 ---
 

agents.md

@@ -0,0 +1,48 @@
+# AGENTS.md — Tabras
+
+Engineering conventions for any agent or contributor working in this repo. Read alongside `README.md` (the design spec). README says *what* to build; this says *how* to write it.
+
+## Non-negotiables
+
+### Tests accompany all code
+- No code lands without tests. A feature and its tests are one unit of work, written together — not "tests later."
+- The deterministic core (`primitives.py`, `budget.py`, `game.py`) is pure logic with no model calls — it is fully testable and MUST be fully tested. This is where bugs hide and where balance lives.
+- Model-dependent code (`generator.py`, `boss.py`) is tested by mocking the model: assert the tool-call schema, the deck-context wiring, and that engine numbers (not model output) set magnitudes. Never test against live model output.
+
+### Coverage is the bloat metric
+- Track code coverage on every change. Treat uncovered lines as **bloat**: if coverage is 50%, half the code is untested weight that should either be tested or deleted.
+- Target high coverage on the deterministic core specifically — it's pure and has no excuse to be uncovered.
+- Coverage is a deletion signal, not just a test signal: uncovered code is a prompt to ask "is this needed at all?"
+
+### Functions do one thing
+- One function, one responsibility. If a function does two things, it's two functions.
+- As simple as possible, complex only where the problem genuinely requires it. Reach for complexity reluctantly and only when the domain demands it.
+- A function you can't describe in one line (see comments) is doing too much — split it.
+
+### Terse, readable code
+- Terseness in service of readability, never against it. Shorter is better *only* when it reads more clearly.
+- No cleverness that costs a reader a second look. Obvious beats impressive.
+- Delete aggressively. The best code is no code; the second best is code that's plainly necessary.
+
+### Comments: one line, at the function line
+- One-line comment at the function definition stating what it does. That's the default.
+- No block comments narrating internals, no inline play-by-play. If the body needs explaining, the function is too complex — simplify it instead of annotating it.
+- Comments state *what/why* at the boundary, never *how* line-by-line (the code is the how).
+
+## In practice
+- The one-line function comment and the "describe in one line" rule are the same rule: if you can't write the comment, the function isn't doing one thing.
+- Coverage + terseness + one-thing functions reinforce each other: small single-purpose functions are trivial to test, which drives coverage, which exposes bloat to delete.
+- When in doubt: smaller function, clearer name, a test, delete the rest.
+
+## What this looks like
+```python
+# Convert a card's energy cost into its point budget.
+def budget_for(cost: int) -> int:
+    return cost
+```
+Single purpose, one-line comment at the definition, terse, testable. A companion test asserts the mapping. No internal commentary.
+
+## Order of work (per the README build order)
+Each step ships with its tests before the next begins:
+`primitives.py` → `budget.py` → `generator.py` + `game.py` → **playtest** → `boss.py` → `draft.py` → art → fine-tune.
+Do not move to the next file until the current one is tested and covered.

ai_runtime.py

@@ -0,0 +1,61 @@
+import os
+import subprocess
+from pathlib import Path
+
+
+DEFAULT_MINICPM_MODEL_PATH = Path("models/minicpm-v-4.6-gguf/MiniCPM-V-4.6-Q4_K_M.gguf")
+DEFAULT_CARD_PORT = 8090
+DEFAULT_APP_PORT = 7860
+DEFAULT_BOSS_MODEL = "mlx-community/Nemotron-Mini-4B-Instruct-4bit-mlx"
+
+
+# Return the OpenAI-compatible chat endpoint for a local port.
+def chat_endpoint(port: int) -> str:
+    return f"http://127.0.0.1:{port}/v1/chat/completions"
+
+
+# Return the llama.cpp server command for the local MiniCPM GGUF.
+def minicpm_server_command(model_path: Path = DEFAULT_MINICPM_MODEL_PATH, port: int = DEFAULT_CARD_PORT) -> tuple[str, ...]:
+    return (
+        "llama-server",
+        "--model",
+        str(model_path),
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(port),
+        "--ctx-size",
+        "4096",
+        "--n-gpu-layers",
+        "99",
+    )
+
+
+# Return the environment that forces MiniCPM card authoring and Nemotron boss play.
+def local_ai_env(card_port: int = DEFAULT_CARD_PORT) -> dict[str, str]:
+    env = dict(os.environ)
+    env.update(
+        {
+            "TABRAS_CARD_BACKEND": "llamacpp",
+            "TABRAS_CARD_ENDPOINT": chat_endpoint(card_port),
+            "TABRAS_CARD_MODEL": "minicpm-v-4.6-q4",
+            "TABRAS_CARD_TEMPERATURE": "0.0",
+            "TABRAS_CARD_MAX_TOKENS": "220",
+            "TABRAS_AI_BOSS": "1",
+            "TABRAS_BOSS_BACKEND": "mlx",
+            "TABRAS_BOSS_MODEL": DEFAULT_BOSS_MODEL,
+            "TABRAS_BOSS_TEMPERATURE": "0.2",
+            "TABRAS_BOSS_MAX_TOKENS": "96",
+        }
+    )
+    return env
+
+
+# Start the MiniCPM llama.cpp server process.
+def start_minicpm_server(
+    model_path: Path = DEFAULT_MINICPM_MODEL_PATH,
+    port: int = DEFAULT_CARD_PORT,
+) -> subprocess.Popen[str]:
+    if not model_path.exists():
+        raise FileNotFoundError(f"MiniCPM model not found: {model_path}")
+    return subprocess.Popen(minicpm_server_command(model_path, port), text=True)

app.py

@@ -0,0 +1,656 @@
+import time
+
+import gradio as gr
+
+from clients import card_client_from_env
+from primitives import School
+from ui import (
+    CARD_PANEL_COUNT,
+    HAND_PANEL_COUNT,
+    RunState,
+    board_html,
+    choose_draft_card_steps,
+    draft_screen_html,
+    log_html,
+    new_run,
+    pass_turn_steps,
+    play_hand_card_steps,
+)
+
+HEAD = """
+<script>
+function tabrasClick(id) {
+  const el = document.getElementById(id);
+  if (!el) return;
+  (el.tagName === 'BUTTON' ? el : el.querySelector('button')).click();
+}
+function tabrasPlay(id, card) {
+  if (card.classList.contains('launching')) return;
+  card.classList.add('launching');
+  tabrasClick(id);
+}
+</script>
+"""
+
+CSS = """
+.gradio-container {
+  background: radial-gradient(ellipse at 50% 20%, #3a2615 0%, #241608 55%, #140b04 100%) fixed;
+  color: #f4ead9;
+  max-width: 100% !important;
+}
+footer { display: none !important; }
+.hidden-controls { display: none !important; }
+gradio-app, body {
+  background: radial-gradient(ellipse at 50% 20%, #3a2615 0%, #241608 55%, #140b04 100%) fixed !important;
+}
+.gradio-container .block, .gradio-container .form, .gradio-container .gr-group, .gradio-container .styler {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+button.primary {
+  background: linear-gradient(180deg, #f2c24d, #a96f17) !important;
+  color: #3a2403 !important;
+  border: 2px solid #f6dd9a !important;
+  font-weight: 800 !important;
+}
+
+.tabras-title {
+  min-height: 70vh;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+}
+.tabras-title h1 {
+  font-size: 76px;
+  margin: 0 0 12px;
+  color: #f8e7c4;
+  text-shadow: 0 3px 18px rgba(0, 0, 0, 0.65);
+}
+.gradio-container .setup-panel {
+  background: rgba(36, 22, 13, 0.78) !important;
+  border: 2px solid rgba(255, 225, 172, 0.25) !important;
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.35) !important;
+  padding: 18px !important;
+  border-radius: 14px !important;
+  max-width: 560px;
+  margin: 8vh auto 0 !important;
+}
+
+/* ---- card faces ---- */
+.tabras-card {
+  position: relative;
+  border-radius: 10px;
+  padding: 26px 10px 8px;
+  background: linear-gradient(180deg, #2b2119, #17100b);
+  border: 2px solid #bb8c4d;
+  color: #f8ead2;
+  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.35);
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.tabras-card.empty { opacity: 0.35; }
+.card-cost {
+  position: absolute;
+  top: -9px;
+  left: -9px;
+  width: 34px;
+  height: 34px;
+  border-radius: 50%;
+  background: radial-gradient(circle at 35% 30%, #7fd4ff, #1668c9);
+  border: 2px solid #d8f1ff;
+  color: #fff;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 900;
+  font-size: 17px;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.6);
+  z-index: 2;
+}
+.card-name { font-size: 13px; font-weight: 800; line-height: 1.15; min-height: 30px; }
+.school-fire .card-name { color: #ffb199; }
+.school-ice .card-name { color: #aadcff; }
+.school-earth .card-name { color: #c9e29a; }
+.card-art {
+  height: 64px;
+  border-radius: 6px;
+  border: 1px dashed rgba(255, 232, 188, 0.25);
+  background: linear-gradient(135deg, rgba(77, 52, 35, 0.55), rgba(23, 32, 42, 0.55));
+}
+.card-rules { font-size: 11.5px; line-height: 1.3; min-height: 44px; color: #f3e6cb; }
+.card-flavor {
+  color: #cdb997;
+  font-size: 10px;
+  font-style: italic;
+  border-top: 1px solid rgba(255, 232, 188, 0.18);
+  padding-top: 4px;
+}
+
+/* ---- draft screen ---- */
+.draft-board { display: flex; flex-direction: column; align-items: center; gap: 20px; padding: 18px; }
+.draft-banner { text-align: center; }
+.draft-banner h2 { margin: 0; color: #f2c24d; letter-spacing: 0.08em; text-transform: uppercase; }
+.draft-banner p { margin: 4px 0 0; color: #cdb997; }
+.draft-pack { display: flex; gap: 28px; }
+.draft-card { width: 215px; cursor: pointer; transition: transform 0.15s ease, box-shadow 0.15s ease; animation: pack-in 0.5s ease backwards; }
+.draft-pack .draft-card:nth-child(2) { animation-delay: 0.1s; }
+.draft-pack .draft-card:nth-child(3) { animation-delay: 0.2s; }
+.draft-card:hover { transform: translateY(-14px) scale(1.06); box-shadow: 0 0 26px rgba(240, 200, 110, 0.5); }
+@keyframes pack-in {
+  from { opacity: 0; transform: translateY(28px) scale(0.92); }
+  to { opacity: 1; transform: none; }
+}
+.draft-pack .draft-card.fading { animation: pack-out 0.7s ease forwards; animation-delay: 0s; pointer-events: none; cursor: default; }
+.draft-pack .draft-card.picked { animation: picked-out 0.7s ease forwards; animation-delay: 0s; pointer-events: none; cursor: default; }
+@keyframes pack-out {
+  from { opacity: 1; }
+  to { opacity: 0; transform: translateY(-14px) scale(0.94); filter: grayscale(0.7); }
+}
+@keyframes picked-out {
+  30% { opacity: 1; transform: scale(1.08); box-shadow: 0 0 44px rgba(242, 194, 77, 0.95); }
+  to { opacity: 0; transform: translateY(-34px) scale(1.02); box-shadow: 0 0 30px rgba(242, 194, 77, 0.6); }
+}
+.draft-card .card-name { font-size: 17px; min-height: 42px; }
+.draft-card .card-art { height: 112px; }
+.draft-card .card-rules { font-size: 13.5px; min-height: 62px; }
+.draft-card .card-flavor { font-size: 12px; }
+.deck-strip { display: flex; flex-wrap: wrap; gap: 6px; justify-content: center; max-width: 920px; align-items: center; }
+.deck-strip-label { font-weight: 800; color: #f2c24d; margin-right: 6px; }
+.deck-chip { background: rgba(0, 0, 0, 0.35); border: 1px solid #7c5a33; border-radius: 12px; padding: 2px 10px; font-size: 11px; }
+.deck-chip b { color: #7fd4ff; }
+.deck-chip.anchor { border-color: #f2c24d; box-shadow: 0 0 8px rgba(242, 194, 77, 0.35); }
+
+/* ---- battle board ---- */
+.board {
+  position: relative;
+  border: 4px solid #6e4f2a;
+  border-radius: 22px;
+  padding: 8px 14px;
+  background: radial-gradient(ellipse at center, #5d3b1e 0%, #4a2e15 60%, #38220e 100%);
+  box-shadow: inset 0 0 60px rgba(0, 0, 0, 0.55), 0 24px 60px rgba(0, 0, 0, 0.5);
+  overflow: hidden;
+}
+.zone { position: relative; display: flex; align-items: center; justify-content: center; }
+.zone-center { display: flex; flex-direction: column; align-items: center; gap: 6px; flex: 1; }
+.piles { position: absolute; right: 8px; top: 50%; transform: translateY(-50%); display: flex; flex-direction: column; gap: 8px; }
+.pile {
+  width: 64px;
+  text-align: center;
+  border: 2px solid #8a6536;
+  border-radius: 8px;
+  padding: 6px 0 3px;
+  background: repeating-linear-gradient(45deg, #241509 0, #241509 6px, #2f1c0d 6px, #2f1c0d 12px);
+}
+.pile span { font-weight: 900; font-size: 18px; color: #f4d69b; }
+.pile label { display: block; font-size: 9px; letter-spacing: 0.12em; text-transform: uppercase; color: #b09a72; }
+.fatigue-warn { color: #ff8d7a; font-size: 10px; font-weight: 800; }
+
+.hero { display: flex; flex-direction: column; align-items: center; gap: 3px; }
+.hero-frame { position: relative; width: 124px; height: 124px; }
+.hero-face {
+  width: 100%;
+  height: 100%;
+  border-radius: 50% 50% 46% 46%;
+  border: 4px solid #b08a4f;
+  background: radial-gradient(circle at 50% 30%, #7a5836, #2a1a0e 75%);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 900;
+  font-size: 22px;
+  color: #f4d69b;
+  box-shadow: 0 10px 26px rgba(0, 0, 0, 0.5);
+}
+.hp-gem, .block-gem, .ward-gem {
+  position: absolute;
+  width: 42px;
+  height: 42px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 900;
+  font-size: 19px;
+  color: #fff;
+  text-shadow: 0 1px 2px #000;
+  border: 3px solid #f3d492;
+}
+.hp-gem { right: -10px; bottom: -6px; background: radial-gradient(circle at 35% 30%, #e0524d, #8f1612); }
+.block-gem { left: -10px; bottom: -6px; background: radial-gradient(circle at 35% 30%, #c9cdd4, #5a626e); border-color: #eef2f7; }
+.ward-gem { left: -10px; top: -6px; background: radial-gradient(circle at 35% 30%, #8fd0ff, #1d4d8f); border-color: #d8f1ff; }
+.hero-name { font-weight: 800; color: #f4d69b; text-shadow: 0 2px 6px #000; }
+.hero-frame.hit { animation: hero-shake 0.45s ease; }
+.hero-frame.hit .hp-gem { animation: gem-flash 0.7s ease; }
+@keyframes hero-shake {
+  0%, 100% { transform: translateX(0); }
+  20% { transform: translateX(-7px) rotate(-2deg); }
+  40% { transform: translateX(6px) rotate(2deg); }
+  60% { transform: translateX(-4px); }
+  80% { transform: translateX(3px); }
+}
+@keyframes gem-flash {
+  0%, 100% { filter: none; }
+  30% { filter: brightness(2.2) saturate(1.6); transform: scale(1.25); }
+}
+.dmg-pop {
+  position: absolute;
+  left: 50%;
+  top: 22%;
+  transform: translateX(-50%);
+  font-size: 34px;
+  font-weight: 900;
+  color: #ff5340;
+  text-shadow: 0 0 12px rgba(255, 60, 30, 0.9), 0 2px 3px #000;
+  pointer-events: none;
+  z-index: 50;
+  animation: dmg-float 1.4s ease-out forwards;
+}
+@keyframes dmg-float {
+  from { opacity: 0; transform: translateX(-50%) translateY(16px) scale(0.5); }
+  25% { opacity: 1; transform: translateX(-50%) translateY(-8px) scale(1.3); }
+  to { opacity: 0; transform: translateX(-50%) translateY(-54px) scale(1); }
+}
+.chips { display: flex; gap: 6px; min-height: 18px; }
+.chip { font-size: 10px; font-weight: 700; border-radius: 10px; padding: 1px 8px; border: 1px solid; }
+.chip.charge { color: #ffd98c; border-color: #c9982f; background: rgba(120, 85, 10, 0.35); }
+.chip.weak { color: #a8c6ff; border-color: #4a6fb5; background: rgba(30, 55, 110, 0.35); }
+.chip.vuln { color: #ffb3c2; border-color: #b54a64; background: rgba(110, 25, 45, 0.35); }
+
+.enemy-hand { display: flex; justify-content: center; margin-bottom: -10px; }
+.enemy-card-back {
+  width: 52px;
+  height: 72px;
+  border-radius: 6px;
+  border: 2px solid #a77c43;
+  margin: 0 -10px;
+  background: repeating-linear-gradient(45deg, #2c1b12 0, #2c1b12 7px, #3a2417 7px, #3a2417 14px);
+  box-shadow: 0 6px 14px rgba(0, 0, 0, 0.4);
+  transform: rotate(3deg);
+}
+.enemy-card-back:nth-child(odd) { transform: rotate(-3deg); }
+
+.battlefield {
+  position: relative;
+  min-height: 118px;
+  margin: 8px 36px;
+  border-radius: 14px;
+  background: rgba(0, 0, 0, 0.18);
+  box-shadow: inset 0 0 30px rgba(0, 0, 0, 0.35);
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  padding: 6px 150px 6px 16px;
+}
+.round-banner {
+  position: absolute;
+  left: 16px;
+  top: 50%;
+  transform: translateY(-50%);
+  font-weight: 800;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: #e9cf9b;
+  font-size: 13px;
+}
+.end-turn {
+  position: absolute;
+  right: 14px;
+  top: 50%;
+  transform: translateY(-50%);
+  padding: 13px 24px;
+  border-radius: 26px;
+  border: 3px solid #f6dd9a;
+  background: linear-gradient(180deg, #f2c24d, #a96f17);
+  color: #3a2403;
+  font-weight: 900;
+  letter-spacing: 0.06em;
+  cursor: pointer;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.45);
+}
+.end-turn:hover { filter: brightness(1.12); }
+.end-turn.pulse { animation: end-pulse 1.2s ease-in-out infinite; }
+@keyframes end-pulse {
+  0%, 100% { box-shadow: 0 6px 18px rgba(0, 0, 0, 0.45); }
+  50% { box-shadow: 0 0 26px rgba(246, 221, 154, 0.9), 0 6px 18px rgba(0, 0, 0, 0.45); }
+}
+.board.quake { animation: board-quake 0.5s ease; }
+@keyframes board-quake {
+  0%, 100% { transform: translate(0, 0); }
+  20% { transform: translate(-6px, 3px); }
+  40% { transform: translate(5px, -4px); }
+  60% { transform: translate(-4px, 2px); }
+  80% { transform: translate(3px, -2px); }
+}
+.pending-row { display: flex; gap: 8px; min-height: 34px; justify-content: center; }
+.showcase { display: flex; gap: 18px; justify-content: center; align-items: flex-start; min-height: 0; perspective: 900px; }
+.play-slot {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+.play-slot.fresh { animation: play-in 0.5s cubic-bezier(0.2, 1.4, 0.4, 1) backwards; }
+.play-label {
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  padding: 1px 10px;
+  border-radius: 10px;
+}
+.play-label.you { color: #9fe7ff; background: rgba(30, 90, 140, 0.45); border: 1px solid #4fa3d4; }
+.play-label.boss { color: #ffb9a8; background: rgba(140, 40, 20, 0.45); border: 1px solid #c95a3a; }
+.played-card { width: 132px; }
+.played-card.player-play { box-shadow: 0 0 22px rgba(120, 220, 255, 0.55); }
+.played-card.enemy-play { box-shadow: 0 0 22px rgba(255, 90, 60, 0.6); border-color: #c95a3a; }
+@keyframes play-in {
+  from { transform: translateY(120px) rotateY(90deg) scale(0.4); opacity: 0; }
+  60% { transform: translateY(-6px) rotateY(0deg) scale(1.12); opacity: 1; }
+  to { transform: none; opacity: 1; }
+}
+.token { display: flex; flex-direction: column; align-items: center; padding: 2px 10px; border-radius: 10px; font-size: 11px; border: 2px solid; line-height: 1.1; }
+.token b { font-size: 16px; }
+.token.bomb { border-color: #e0524d; background: rgba(120, 20, 10, 0.5); color: #ffb9a8; }
+.token.burn { border-color: #f2913d; background: rgba(140, 70, 10, 0.45); color: #ffd9a8; }
+
+.mana-bar { display: flex; align-items: center; gap: 6px; }
+.mana { width: 19px; height: 19px; transform: rotate(45deg); border-radius: 5px; background: #1d2c3c; border: 2px solid #2f4a66; }
+.mana.filled {
+  background: radial-gradient(circle at 35% 30%, #7fd4ff, #1668c9);
+  border-color: #bfe9ff;
+  box-shadow: 0 0 8px rgba(80, 170, 255, 0.8);
+}
+.mana-count { margin-left: 8px; font-weight: 800; color: #bfe9ff; }
+
+.hand-fan { display: flex; justify-content: center; align-items: flex-end; padding: 26px 0 6px; min-height: 240px; }
+.hand-card {
+  width: 150px;
+  margin: 0 -16px;
+  transform: rotate(var(--rot)) translateY(var(--ty));
+  transform-origin: 50% 130%;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+  cursor: pointer;
+  box-shadow: 0 0 14px rgba(110, 230, 120, 0.5);
+  border-color: #7fdf8a;
+}
+.hand-card:hover {
+  transform: rotate(0deg) translateY(-48px) scale(1.45);
+  z-index: 99 !important;
+  box-shadow: 0 0 24px rgba(120, 255, 140, 0.45), 0 24px 50px rgba(0, 0, 0, 0.6);
+}
+.hand-card.unplayable { filter: grayscale(0.8) brightness(0.7); cursor: default; box-shadow: 0 10px 28px rgba(0, 0, 0, 0.35); border-color: #6b5634; }
+.hand-card.unplayable:hover { box-shadow: 0 24px 50px rgba(0, 0, 0, 0.6); }
+.hand-card.launching {
+  transform: translateY(-170px) scale(1.08) rotate(0deg) !important;
+  opacity: 0;
+  transition: transform 0.3s ease-in, opacity 0.3s ease-in;
+  pointer-events: none;
+}
+.round-splash {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  align-items: center;
+  justify-content: center;
+  z-index: 150;
+  pointer-events: none;
+  border-radius: 18px;
+  animation: splash-bg 1.9s ease forwards;
+}
+@keyframes splash-bg {
+  0% { background: rgba(8, 4, 2, 0); }
+  18% { background: rgba(8, 4, 2, 0.74); }
+  72% { background: rgba(8, 4, 2, 0.74); }
+  100% { background: rgba(8, 4, 2, 0); }
+}
+.splash-round {
+  font-size: 50px;
+  font-weight: 900;
+  letter-spacing: 0.3em;
+  color: #f6dd9a;
+  text-shadow: 0 0 34px rgba(246, 221, 154, 0.85), 0 4px 8px #000;
+  animation: splash 1.9s ease forwards;
+}
+.splash-initiative {
+  font-size: 24px;
+  font-weight: 900;
+  letter-spacing: 0.26em;
+  animation: splash 1.65s ease 0.25s both;
+}
+.splash-initiative.you { color: #9fe7ff; text-shadow: 0 0 24px rgba(110, 200, 255, 0.8); }
+.splash-initiative.boss { color: #ff8d7a; text-shadow: 0 0 24px rgba(255, 80, 50, 0.8); }
+@keyframes splash {
+  0% { opacity: 0; transform: scale(2.2); }
+  25% { opacity: 1; transform: scale(1); }
+  70% { opacity: 1; }
+  100% { opacity: 0; transform: scale(0.92); }
+}
+.boss-thinking {
+  position: absolute;
+  left: 50%;
+  bottom: -6px;
+  transform: translateX(-50%);
+  z-index: 60;
+  padding: 5px 16px;
+  border-radius: 14px;
+  background: rgba(20, 10, 6, 0.92);
+  border: 1px solid #c95a3a;
+  color: #ffb9a8;
+  font-weight: 700;
+  font-size: 12px;
+  letter-spacing: 0.08em;
+  white-space: nowrap;
+  animation: think-pulse 1.1s ease-in-out infinite;
+}
+@keyframes think-pulse {
+  0%, 100% { opacity: 0.55; transform: translateX(-50%) scale(1); }
+  50% { opacity: 1; transform: translateX(-50%) scale(1.06); }
+}
+.board.thinking .hero.enemy .hero-face { box-shadow: 0 0 28px rgba(255, 90, 50, 0.6); }
+
+.winner-banner {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  align-items: center;
+  justify-content: center;
+  background: rgba(10, 5, 2, 0.74);
+  z-index: 200;
+  border-radius: 18px;
+}
+.winner-banner h1 { font-size: 64px; letter-spacing: 0.2em; margin: 0; animation: banner-in 0.7s cubic-bezier(0.2, 1.6, 0.4, 1) backwards; }
+@keyframes banner-in {
+  from { transform: scale(2.6); opacity: 0; letter-spacing: 0.6em; }
+  to { transform: scale(1); opacity: 1; letter-spacing: 0.2em; }
+}
+.winner-banner.victory h1 { color: #ffd98c; text-shadow: 0 0 30px rgba(255, 200, 90, 0.7); }
+.winner-banner.defeat h1 { color: #ff7a6a; text-shadow: 0 0 30px rgba(255, 70, 40, 0.6); }
+.winner-banner.draw h1 { color: #cdb997; }
+.new-run {
+  padding: 12px 30px;
+  border-radius: 24px;
+  border: 3px solid #f6dd9a;
+  background: linear-gradient(180deg, #f2c24d, #a96f17);
+  font-weight: 900;
+  cursor: pointer;
+  color: #3a2403;
+}
+.game-over .hand-fan, .game-over .end-turn { pointer-events: none; }
+
+.log-panel { background: rgba(20, 12, 7, 0.8) !important; border: 2px solid #6e4f2a; border-radius: 14px; padding: 8px; }
+.log-scroll {
+  display: flex;
+  flex-direction: column-reverse;
+  gap: 4px;
+  max-height: 600px;
+  overflow-y: auto;
+  font-size: 11.5px;
+  color: #e7d5af;
+}
+.log-line { padding: 4px 8px; border-left: 3px solid transparent; border-radius: 4px; line-height: 1.35; }
+.log-line b { color: #ffd98c; font-size: 12.5px; }
+.log-owner { display: block; font-size: 9px; letter-spacing: 0.12em; text-transform: uppercase; opacity: 0.7; }
+.log-rules { display: block; font-size: 10.5px; opacity: 0.85; }
+.log-play.log-you { border-left-color: #4fa3d4; background: rgba(40, 90, 130, 0.2); }
+.log-play.log-boss { border-left-color: #c95a3a; background: rgba(140, 50, 25, 0.2); }
+.log-round {
+  text-align: center;
+  color: #f2c24d;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  margin-top: 8px;
+  border-top: 1px solid rgba(242, 194, 77, 0.3);
+  padding-top: 6px;
+}
+.log-winner { text-align: center; color: #ffd98c; font-weight: 900; font-size: 13px; border: 1px solid #f2c24d; background: rgba(120, 85, 10, 0.3); }
+.log-muted { opacity: 0.55; font-style: italic; }
+.log-draft { color: #c9e29a; }
+.log-scroll > .log-line:first-child { box-shadow: inset 0 0 0 1px rgba(255, 217, 140, 0.3); }
+"""
+
+
+# Build all Gradio components for the Tabras app.
+def build_app() -> gr.Blocks:
+    with gr.Blocks(title="Tabras") as app:
+        state = gr.State(None)
+
+        with gr.Group(visible=True, elem_id="title-screen") as title_group:
+            gr.HTML("<div class='tabras-title'><h1>Tabras</h1><p>A small-model card duel on an old wooden desk.</p></div>")
+            play_now = gr.Button("Play Now", variant="primary")
+
+        with gr.Group(visible=False, elem_id="setup-screen") as setup_group:
+            with gr.Column(elem_classes=["setup-panel"]):
+                gr.Markdown("## Set the table")
+                name = gr.Textbox(label="Name", value="Vishnu")
+                world = gr.Textbox(label="What's your world?", value="dark fantasy")
+                school = gr.Radio(["fire", "ice", "earth"], label="What's your favorite school of magic?", value="fire")
+                begin = gr.Button("Begin Draft", variant="primary")
+
+        with gr.Group(visible=False, elem_id="draft-screen") as draft_group:
+            draft_view = gr.HTML()
+
+        with gr.Group(visible=False, elem_id="battle-screen") as battle_group:
+            with gr.Row():
+                with gr.Column(scale=4):
+                    board_view = gr.HTML()
+                with gr.Column(scale=1, min_width=240, elem_classes=["log-panel"]):
+                    gr.Markdown("### Battle log")
+                    log_view = gr.HTML()
+
+        with gr.Row(elem_classes=["hidden-controls"]):
+            hand_buttons = [gr.Button("", elem_id=f"hand-btn-{index}") for index in range(HAND_PANEL_COUNT)]
+            draft_buttons = [gr.Button("", elem_id=f"draft-btn-{index}") for index in range(CARD_PANEL_COUNT)]
+            end_turn = gr.Button("", elem_id="end-turn-btn")
+            restart = gr.Button("", elem_id="restart-btn")
+
+        outputs = [state, title_group, setup_group, draft_group, battle_group, draft_view, board_view, log_view]
+
+        play_now.click(show_setup, outputs=outputs)
+        begin.click(begin_run, inputs=[name, world, school], outputs=outputs)
+        for index, button in enumerate(draft_buttons):
+            button.click(indexed_handler(draft_pick, index), inputs=[state], outputs=outputs)
+        for index, button in enumerate(hand_buttons):
+            button.click(indexed_handler(play_card, index), inputs=[state], outputs=outputs)
+        end_turn.click(end_player_turn, inputs=[state], outputs=outputs)
+        restart.click(show_setup, outputs=outputs)
+
+    return app
+
+
+# Bind one index into a streaming handler as a true generator function.
+def indexed_handler(handler, index: int):
+    def stream(run_state):
+        yield from handler(run_state, index)
+
+    return stream
+
+
+# Show the setup screen.
+def show_setup() -> list[object]:
+    return render(None, "setup")
+
+
+# Start a run from setup inputs.
+def begin_run(name: str, world: str, school: str) -> list[object]:
+    client = card_client_from_env()
+    run_state = new_run(name, world, school_as_literal(school), client)
+    return render(run_state, "draft")
+
+
+# Choose one draft card, streaming the paced battle opening on the final pick.
+def draft_pick(run_state: RunState | None, index: int):
+    if run_state is None:
+        yield render(None, "setup")
+        return
+    client = card_client_from_env()
+    yield from paced_frames(choose_draft_card_steps(run_state, index, client))
+
+
+# Play one hand card by index, streaming the paced boss response.
+def play_card(run_state: RunState | None, index: int):
+    if run_state is None:
+        yield render(None, "setup")
+        return
+    yield from paced_frames(play_hand_card_steps(run_state, index))
+
+
+# End the player turn, streaming the paced boss response.
+def end_player_turn(run_state: RunState | None):
+    if run_state is None:
+        yield render(None, "setup")
+        return
+    yield from paced_frames(pass_turn_steps(run_state))
+
+
+# Yield rendered frames, letting each dramatic beat linger on screen.
+def paced_frames(steps):
+    previous = None
+    for state in steps:
+        if previous is not None:
+            time.sleep(frame_delay(previous))
+        yield render(state, "battle" if state.duel else "draft")
+        previous = state
+
+
+# Return how long one frame should stay on screen before the next.
+def frame_delay(state: RunState) -> float:
+    if state.round_flash:
+        return 2.2
+    if state.boss_thinking:
+        return 1.4
+    if state.pack_fading >= 0:
+        return 0.75
+    return 0.9
+
+
+# Render all app outputs.
+def render(run_state: RunState | None, screen: str) -> list[object]:
+    return [
+        run_state,
+        gr.update(visible=screen == "title"),
+        gr.update(visible=screen == "setup"),
+        gr.update(visible=screen == "draft"),
+        gr.update(visible=screen == "battle"),
+        draft_screen_html(run_state),
+        board_html(run_state),
+        log_html(run_state),
+    ]
+
+
+# Return a typed school value.
+def school_as_literal(value: str) -> School:
+    if value in {"fire", "ice", "earth"}:
+        return value  # type: ignore[return-value]
+    return "fire"
+
+
+if __name__ == "__main__":
+    build_app().launch(server_name="127.0.0.1", server_port=7860, css=CSS, head=HEAD)

boss.py

@@ -0,0 +1,138 @@
+from dataclasses import dataclass
+import json
+from typing import Any, Protocol
+
+from game import DuelState, PlayerState, opponent
+from generator import extract_json_object
+from local_llm import LocalChatClient
+from play import Chooser, choose_enemy_card, playable_indexes
+
+
+class BossClient(Protocol):
+    # Return one raw boss decision payload.
+    def choose_cards(self, payload: dict[str, Any]) -> dict[str, Any]:  # pragma: no cover
+        ...
+
+
+@dataclass(frozen=True)
+class HeuristicBossClient:
+    # Return a deterministic fallback boss decision.
+    def choose_cards(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return {"card_indexes": []}
+
+
+@dataclass(frozen=True)
+class NemotronBossClient:
+    chat: LocalChatClient
+
+    # Return one boss decision from a local Nemotron endpoint.
+    def choose_cards(self, payload: dict[str, Any]) -> dict[str, Any]:
+        text = self.chat.complete(boss_system_prompt(), boss_prompt(payload))
+        return json.loads(extract_json_object(text))
+
+
+# Build visible state for a boss decision.
+def boss_payload(state: DuelState, actor: PlayerState) -> dict[str, Any]:
+    target = opponent(state, actor)
+    return {
+        "round": state.round_number,
+        "actor": player_payload(actor),
+        "opponent": player_payload(target),
+        "hand": hand_payload(actor),
+        "pending": [effect.__dict__ for effect in state.pending],
+        "playable_indexes": playable_indexes(actor),
+        "instruction": "Choose playable hand indexes to play in order. Do not invent cards or numbers.",
+    }
+
+
+# Return the system prompt for boss decisions.
+def boss_system_prompt() -> str:
+    return "You are the Tabras boss AI. Return strict JSON only."
+
+
+# Return the user prompt for one boss decision.
+def boss_prompt(payload: dict[str, Any]) -> str:
+    return "\n".join(
+        (
+            "Choose the boss card indexes for this turn.",
+            "Return exactly this JSON shape: {\"card_indexes\": [int], \"reason\": str}",
+            "Only choose indexes from playable_indexes. Choose an ordered sequence the current energy can pay for.",
+            "Priorities: lethal, avoid dying, exploit shield charge, efficient damage, draw/setup.",
+            json.dumps(payload),
+        )
+    )
+
+
+# Return visible player state for boss reasoning.
+def player_payload(player: PlayerState) -> dict[str, Any]:
+    return {
+        "name": player.name,
+        "hp": player.hp,
+        "energy": player.energy,
+        "block": player.block,
+        "ward": player.ward,
+        "shield_charge": player.shield_charge,
+        "hand_count": len(player.hand),
+        "deck_count": len(player.deck),
+        "discard_count": len(player.discard),
+    }
+
+
+# Return visible hand cards for boss reasoning.
+def hand_payload(player: PlayerState) -> list[dict[str, Any]]:
+    return [
+        {"index": index, "name": card.name, "cost": card.cost, "rules_text": card.rules_text()}
+        for index, card in enumerate(player.hand)
+    ]
+
+
+# Choose one boss action using model output with heuristic fallback.
+def boss_chooser(client: BossClient | None = None, fallback: Chooser = choose_enemy_card) -> Chooser:
+    # Choose one validated model card, then fall back when empty.
+    def choose(state: DuelState, actor: PlayerState) -> int | None:
+        indexes = safe_boss_indexes(client, state, actor) if client else ()
+        if indexes:
+            return indexes[0]
+        return fallback(state, actor)
+
+    return choose
+
+
+# Return model-selected indexes, treating model failures as no choice.
+def safe_boss_indexes(client: BossClient, state: DuelState, actor: PlayerState) -> tuple[int, ...]:
+    try:
+        return boss_indexes(client, state, actor)
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+        return ()
+
+
+# Return validated model-selected card indexes.
+def boss_indexes(client: BossClient, state: DuelState, actor: PlayerState) -> tuple[int, ...]:
+    raw = client.choose_cards(boss_payload(state, actor))
+    indexes = parse_card_indexes(raw)
+    return affordable_indexes(actor, indexes)
+
+
+# Parse model-selected hand indexes.
+def parse_card_indexes(raw: dict[str, Any]) -> tuple[int, ...]:
+    values = raw.get("card_indexes", [])
+    if not isinstance(values, list):
+        return ()
+    return tuple(value for value in values if isinstance(value, int))
+
+
+# Return legal, affordable indexes in sequence.
+def affordable_indexes(actor: PlayerState, indexes: tuple[int, ...]) -> tuple[int, ...]:
+    energy = actor.energy
+    accepted: list[int] = []
+    used: set[int] = set()
+    for index in indexes:
+        if index in used or index not in playable_indexes(actor):
+            continue
+        card = actor.hand[index]
+        if card.cost > energy:
+            continue
+        energy -= card.cost
+        used.add(index)
+        accepted.append(index)
+    return tuple(accepted)

budget.py

@@ -0,0 +1,146 @@
+from dataclasses import dataclass
+from random import Random
+from typing import Sequence
+
+from primitives import Effect, PrimitiveId, School, primitive_allowed_for_school, render_effect
+
+MAX_ENERGY_COST = 5
+MIRACLE_BUDGET_CAP = 8
+
+
+@dataclass(frozen=True)
+class EffectPlan:
+    primitive_id: PrimitiveId
+    weight: int = 1
+
+
+@dataclass(frozen=True)
+class CardSpec:
+    name: str
+    cost: int
+    school: School
+    theme: str
+    effect_plans: tuple[EffectPlan, ...]
+    flavor: str = ""
+    art_prompt: str = ""
+    miracle: bool = False
+
+
+@dataclass(frozen=True)
+class Card:
+    name: str
+    cost: int
+    school: School
+    theme: str
+    effects: tuple[Effect, ...]
+    flavor: str = ""
+    art_prompt: str = ""
+
+    # Return fixed, parseable rules text for the card.
+    def rules_text(self) -> str:
+        return " ".join(render_effect(effect) for effect in self.effects)
+
+
+# Convert energy cost into point budget.
+def budget_for_energy(cost: int) -> int:
+    if cost < 1 or cost > MAX_ENERGY_COST:
+        raise ValueError(f"card cost must be 1..{MAX_ENERGY_COST}")
+    return cost
+
+
+# Roll the bounded high-variance miracle budget.
+def miracle_budget(cost: int, rng: Random) -> int:
+    return min(MIRACLE_BUDGET_CAP, budget_for_energy(cost) * rng.randint(1, 3))
+
+
+# Build a fully costed card from model-chosen effect shapes.
+def cost_card(spec: CardSpec, rng: Random | None = None) -> Card:
+    validate_card_spec(spec)
+    point_budget = miracle_budget(spec.cost, rng or Random()) if spec.miracle else budget_for_energy(spec.cost)
+    effects = cost_effects(point_budget, spec.effect_plans, spec.school)
+    return Card(spec.name, spec.cost, spec.school, spec.theme, effects, spec.flavor, spec.art_prompt)
+
+
+# Build fully costed effects from weighted primitive plans.
+def cost_effects(point_budget: int, plans: Sequence[EffectPlan], school: School | None = None) -> tuple[Effect, ...]:
+    usable_plans = tuple(plans[:point_budget])
+    total_weight = sum(plan.weight for plan in usable_plans)
+    taxed = len(usable_plans) > 1
+    effects: list[Effect] = []
+    spent = 0
+    for index, plan in enumerate(usable_plans):
+        remaining = point_budget - spent
+        points = remaining if index == len(usable_plans) - 1 else max(1, point_budget * plan.weight // total_weight)
+        spent += points
+        effects.append(cost_effect(plan.primitive_id, points, taxed, school))
+    return tuple(effects)
+
+
+# Build one fully costed effect from an allocated point budget.
+def cost_effect(primitive_id: PrimitiveId, points: int, taxed: bool = False, school: School | None = None) -> Effect:
+    if points < 1:
+        raise ValueError("effect points must be positive")
+    match primitive_id:
+        case "deal":
+            return Effect("deal", amount=damage_amount(points, taxed))
+        case "burn":
+            return Effect("burn", amount=burn_amount(points, taxed), duration=2)
+        case "bomb":
+            return Effect("bomb", amount=damage_amount(points, taxed), delay=3)
+        case "block":
+            return Effect("block", amount=points * (2 if taxed else 3))
+        case "ward":
+            return Effect("ward", amount=points)
+        case "weak":
+            return Effect("weak", amount=damage_amount(points, taxed), duration=1)
+        case "draw":
+            return Effect("draw", amount=max(1, points * 2 // 3))
+        case "energy":
+            return Effect("energy", amount=max(1, points // 2))
+        case "initiative":
+            return Effect("initiative", duration=1)
+        case "multi_hit":
+            return Effect("multi_hit", amount=max(1, points), hits=2 if points < 4 else 3)
+        case "vulnerable":
+            return Effect("vulnerable", amount=max(1, points), duration=1 if points < 4 else 2)
+        case "conditional":
+            return Effect("conditional", amount=conditional_amount(points, taxed), condition="opponent_below_half")
+        case "scaling":
+            return Effect("scaling", amount=points, condition=scaling_condition(school))
+
+
+# Return direct damage for a point allocation.
+def damage_amount(points: int, taxed: bool) -> int:
+    return max(1, points * 2 - (1 if taxed else 0))
+
+
+# Return burn damage per tick for a point allocation.
+def burn_amount(points: int, taxed: bool) -> int:
+    return max(1, points - (1 if taxed and points > 1 else 0))
+
+
+# Return maximum scaled conditional damage for a point allocation.
+def conditional_amount(points: int, taxed: bool) -> int:
+    return max(1, points - (1 if taxed and points > 1 else 0))
+
+
+# Return the scaling counter used by a school.
+def scaling_condition(school: School | None) -> str:
+    return "shield_charge" if school == "earth" else "cards_played"
+
+
+# Validate a model-authored card spec before costing it.
+def validate_card_spec(spec: CardSpec) -> None:
+    budget_for_energy(spec.cost)
+    if not spec.effect_plans:
+        raise ValueError("card must have at least one effect")
+    for plan in spec.effect_plans:
+        validate_effect_plan(plan, spec.school)
+
+
+# Validate one model-chosen effect plan.
+def validate_effect_plan(plan: EffectPlan, school: School) -> None:
+    if plan.weight < 1:
+        raise ValueError("effect weight must be positive")
+    if not primitive_allowed_for_school(plan.primitive_id, school):
+        raise ValueError(f"{plan.primitive_id} is not allowed for {school}")

clients.py

@@ -0,0 +1,88 @@
+import os
+
+from boss import BossClient, NemotronBossClient
+from generator import CardPackClient, LlamaCppCardClient, MiniCPMCardClient
+from local_llm import (
+    LocalChatClient,
+    LocalCompletionClient,
+    LocalJsonChatClient,
+    MLXChatClient,
+    MiniCPMTransformersChatClient,
+    NemotronTransformersChatClient,
+    nemotron_prompt,
+)
+
+DEFAULT_CARD_ENDPOINT = "http://localhost:8080/v1/chat/completions"
+DEFAULT_LLAMA_CARD_ENDPOINT = "http://127.0.0.1:8090/v1/chat/completions"
+DEFAULT_BOSS_ENDPOINT = "http://localhost:8081/v1/chat/completions"
+DEFAULT_BOSS_COMPLETION_ENDPOINT = "http://localhost:8081/v1/completions"
+DEFAULT_CARD_MODEL = "minicpm-v-4.6"
+DEFAULT_BOSS_MODEL = "nvidia/Nemotron-Mini-4B-Instruct"
+DEFAULT_MINICPM_MODEL = "openbmb/MiniCPM-V-4"
+DEFAULT_MLX_BOSS_MODEL = "mlx-community/Nemotron-Mini-4B-Instruct-4bit-mlx"
+
+
+# Build a card-generation client from environment variables.
+def card_client_from_env() -> CardPackClient | None:
+    if os.environ.get("TABRAS_CARD_BACKEND") == "llamacpp":
+        return LlamaCppCardClient(
+            LocalChatClient(
+                endpoint=os.environ.get("TABRAS_CARD_ENDPOINT", DEFAULT_LLAMA_CARD_ENDPOINT),
+                model=os.environ.get("TABRAS_CARD_MODEL", DEFAULT_CARD_MODEL),
+                timeout_seconds=int(os.environ.get("TABRAS_CARD_TIMEOUT", "60")),
+                temperature=float(os.environ.get("TABRAS_CARD_TEMPERATURE", "0.0")),
+                max_tokens=int(os.environ.get("TABRAS_CARD_MAX_TOKENS", "220")),
+            )
+        )
+    if os.environ.get("TABRAS_CARD_BACKEND") == "transformers":
+        model_path = os.environ.get("TABRAS_CARD_MODEL", DEFAULT_MINICPM_MODEL)
+        return MiniCPMCardClient(MiniCPMTransformersChatClient.load(model_path))
+    if os.environ.get("TABRAS_CARD_ENDPOINT") is None:
+        return None
+    return MiniCPMCardClient(
+        LocalChatClient(
+            endpoint=os.environ.get("TABRAS_CARD_ENDPOINT", DEFAULT_CARD_ENDPOINT),
+            model=os.environ.get("TABRAS_CARD_MODEL", DEFAULT_CARD_MODEL),
+            timeout_seconds=int(os.environ.get("TABRAS_CARD_TIMEOUT", "60")),
+            temperature=float(os.environ.get("TABRAS_CARD_TEMPERATURE", "0.8")),
+        )
+    )
+
+
+# Build a boss client from environment variables.
+def boss_client_from_env() -> BossClient | None:
+    if os.environ.get("TABRAS_AI_BOSS") != "1":
+        return None
+    if os.environ.get("TABRAS_BOSS_BACKEND") == "completion":
+        return NemotronBossClient(
+            LocalCompletionClient(
+                endpoint=os.environ.get("TABRAS_BOSS_ENDPOINT", DEFAULT_BOSS_COMPLETION_ENDPOINT),
+                model=os.environ.get("TABRAS_BOSS_MODEL", DEFAULT_BOSS_MODEL),
+                prompt_template=nemotron_prompt,
+                timeout_seconds=int(os.environ.get("TABRAS_BOSS_TIMEOUT", "20")),
+                temperature=float(os.environ.get("TABRAS_BOSS_TEMPERATURE", "0.2")),
+                max_tokens=int(os.environ.get("TABRAS_BOSS_MAX_TOKENS", "256")),
+            )
+        )
+    if os.environ.get("TABRAS_BOSS_BACKEND") == "transformers":
+        chat = NemotronTransformersChatClient.load(
+            os.environ.get("TABRAS_BOSS_MODEL", DEFAULT_BOSS_MODEL),
+            max_new_tokens=int(os.environ.get("TABRAS_BOSS_MAX_TOKENS", "256")),
+            temperature=float(os.environ.get("TABRAS_BOSS_TEMPERATURE", "0.2")),
+        )
+        return NemotronBossClient(chat)
+    if os.environ.get("TABRAS_BOSS_BACKEND") == "mlx":
+        chat = MLXChatClient.load(
+            os.environ.get("TABRAS_BOSS_MODEL", DEFAULT_MLX_BOSS_MODEL),
+            nemotron_prompt,
+            max_tokens=int(os.environ.get("TABRAS_BOSS_MAX_TOKENS", "96")),
+        )
+        return NemotronBossClient(chat)
+    return NemotronBossClient(
+        LocalChatClient(
+            endpoint=os.environ.get("TABRAS_BOSS_ENDPOINT", DEFAULT_BOSS_ENDPOINT),
+            model=os.environ.get("TABRAS_BOSS_MODEL", DEFAULT_BOSS_MODEL),
+            timeout_seconds=int(os.environ.get("TABRAS_BOSS_TIMEOUT", "20")),
+            temperature=float(os.environ.get("TABRAS_BOSS_TEMPERATURE", "0.2")),
+        )
+    )

draft.py

@@ -0,0 +1,82 @@
+from random import Random
+from typing import Callable
+
+from budget import Card
+from generator import CardModelClient, CardPackClient, generate_card, generate_pack
+from primitives import Effect
+from primitives import School
+
+PackChooser = Callable[[tuple[Card, ...], tuple[Card, ...]], int]
+
+BACKBONE_CARDS: tuple[tuple[str, int, Effect], ...] = (
+    ("Attack (weak)", 1, Effect("deal", amount=2)),
+    ("Attack (medium)", 3, Effect("deal", amount=4)),
+    ("Attack (strong)", 5, Effect("deal", amount=6)),
+    ("Block (weak)", 2, Effect("block", amount=3)),
+    ("Block (medium)", 3, Effect("block", amount=4)),
+    ("Draw (small)", 2, Effect("draw", amount=1)),
+)
+
+
+# Build the six standardized backbone cards for a run.
+def backbone_deck(school: School, theme: str) -> tuple[Card, ...]:
+    return tuple(backbone_card(name, cost, effect, school, theme) for name, cost, effect in BACKBONE_CARDS)
+
+
+# Build one standardized backbone card.
+def backbone_card(name: str, cost: int, effect: Effect, school: School, theme: str) -> Card:
+    return Card(name, cost, school, theme, (effect,), flavor=f"Standard {name.lower()}.")
+
+
+# Build a full 15-card text deck with nine generated synergy cards.
+def draft_deck(client: CardModelClient, school: School, theme: str, costs: tuple[int, ...]) -> tuple[Card, ...]:
+    if len(costs) != 9:
+        raise ValueError("draft needs exactly nine synergy costs")
+    deck = list(backbone_deck(school, theme))
+    for cost in costs:
+        deck.append(generate_card(client, school, theme, deck, cost))
+    return tuple(deck)
+
+
+# Build a full deck by drafting one card from each generated pack.
+def draft_deck_from_packs(
+    client: CardPackClient,
+    school: School,
+    theme: str,
+    costs: tuple[int, ...],
+    choose_index: PackChooser,
+    rng: Random | None = None,
+) -> tuple[Card, ...]:
+    if len(costs) != 9:
+        raise ValueError("draft needs exactly nine synergy costs")
+    deck = list(backbone_deck(school, theme))
+    anchors: list[Card] = []
+    anchor_indexes = draft_anchor_indexes(len(costs), rng or Random())
+    for index in draft_order(len(costs), anchor_indexes):
+        pack = generate_pack(client, school, theme, deck, costs[index], draft_anchors=anchors)
+        selected = pack[validated_pack_choice(choose_index(tuple(deck), pack), pack)]
+        deck.append(selected)
+        if index in anchor_indexes:
+            anchors.append(selected)
+    return tuple(deck)
+
+
+# Return random synergy-card indexes that anchor the rest of the draft.
+def draft_anchor_indexes(count: int, rng: Random) -> frozenset[int]:
+    if count < 2:
+        raise ValueError("draft needs at least two anchor candidates")
+    return frozenset(rng.sample(range(count), 2))
+
+
+# Return anchor picks first, then the remaining picks in cost order.
+def draft_order(count: int, anchor_indexes: frozenset[int]) -> tuple[int, ...]:
+    anchors = tuple(sorted(anchor_indexes))
+    remaining = tuple(index for index in range(count) if index not in anchor_indexes)
+    return anchors + remaining
+
+
+# Return a valid draft pack index or reject it.
+def validated_pack_choice(index: int, pack: tuple[Card, ...]) -> int:
+    if index < 0 or index >= len(pack):
+        raise ValueError("draft choice is outside the pack")
+    return index

game.py

@@ -0,0 +1,235 @@
+from dataclasses import dataclass, field
+from random import Random
+
+from budget import Card
+from primitives import Effect
+
+STARTING_HP = 20
+MAX_ENERGY = 5
+HALF_HP = STARTING_HP // 2
+
+
+@dataclass
+class PlayerState:
+    name: str
+    deck: list[Card]
+    hand: list[Card] = field(default_factory=list)
+    discard: list[Card] = field(default_factory=list)
+    hp: int = STARTING_HP
+    energy: int = 0
+    block: int = 0
+    ward: int = 0
+    shield_charge: int = 0
+    fatigue: int = 1
+    vulnerable: int = 0
+    vulnerable_turns: int = 0
+    weak: int = 0
+    weak_turns: int = 0
+    cards_played_this_turn: int = 0
+
+
+@dataclass
+class PendingEffect:
+    primitive_id: str
+    owner: str
+    target: str
+    amount: int
+    delay: int = 0
+    duration: int = 0
+
+
+@dataclass
+class DuelState:
+    player: PlayerState
+    enemy: PlayerState
+    pending: list[PendingEffect] = field(default_factory=list)
+    round_number: int = 0
+    forced_second: str | None = None
+
+
+# Create a player state from an ordered deck.
+def create_player(name: str, deck: list[Card] | tuple[Card, ...]) -> PlayerState:
+    return PlayerState(name=name, deck=list(deck))
+
+
+# Return the opposing player state.
+def opponent(state: DuelState, actor: PlayerState) -> PlayerState:
+    return state.enemy if actor is state.player else state.player
+
+
+# Draw cards, applying escalating fatigue on deck-out.
+def draw_cards(player: PlayerState, count: int) -> None:
+    for _ in range(count):
+        if player.deck:
+            player.hand.append(player.deck.pop(0))
+        else:
+            player.hp -= player.fatigue
+            player.fatigue += 1
+
+
+# Start a paired round with energy refill and one draw each.
+def start_round(state: DuelState, rng: Random | None = None) -> tuple[str, str]:
+    state.round_number += 1
+    for player in (state.player, state.enemy):
+        begin_turn(player, state.round_number)
+        draw_cards(player, 1)
+    advance_pending(state)
+    return round_order(state, rng or Random())
+
+
+# Prepare one player for the current round.
+def begin_turn(player: PlayerState, round_number: int) -> None:
+    player.energy = min(MAX_ENERGY, round_number)
+    player.block = 0
+    player.cards_played_this_turn = 0
+    tick_statuses(player)
+
+
+# Tick one-turn status durations.
+def tick_statuses(player: PlayerState) -> None:
+    if player.vulnerable_turns > 0:
+        player.vulnerable_turns -= 1
+        if player.vulnerable_turns == 0:
+            player.vulnerable = 0
+    if player.weak_turns > 0:
+        player.weak_turns -= 1
+        if player.weak_turns == 0:
+            player.weak = 0
+
+
+# Choose action order for the current paired round.
+def round_order(state: DuelState, rng: Random) -> tuple[str, str]:
+    if state.forced_second == state.player.name:
+        state.forced_second = None
+        return (state.enemy.name, state.player.name)
+    if state.forced_second == state.enemy.name:
+        state.forced_second = None
+        return (state.player.name, state.enemy.name)
+    names = (state.player.name, state.enemy.name)
+    return names if rng.randint(0, 1) == 0 else (names[1], names[0])
+
+
+# Play a card from hand by index.
+def play_card_from_hand(state: DuelState, actor: PlayerState, hand_index: int) -> Card:
+    card = actor.hand.pop(hand_index)
+    play_card(state, actor, card)
+    actor.discard.append(card)
+    return card
+
+
+# Resolve a card if the actor can pay its energy cost.
+def play_card(state: DuelState, actor: PlayerState, card: Card) -> None:
+    if card.cost > actor.energy:
+        raise ValueError("not enough energy")
+    actor.energy -= card.cost
+    actor.cards_played_this_turn += 1
+    target = opponent(state, actor)
+    for effect in card.effects:
+        apply_effect(state, actor, target, effect)
+
+
+# Apply one deterministic effect.
+def apply_effect(state: DuelState, actor: PlayerState, target: PlayerState, effect: Effect) -> None:
+    match effect.primitive_id:
+        case "deal":
+            deal_damage(actor, target, effect.amount)
+        case "burn":
+            state.pending.append(PendingEffect("burn", actor.name, target.name, effect.amount, delay=1, duration=effect.duration))
+        case "bomb":
+            state.pending.append(PendingEffect("bomb", actor.name, target.name, effect.amount, delay=effect.delay))
+        case "block":
+            actor.block += effect.amount
+        case "ward":
+            actor.ward += effect.amount
+        case "weak":
+            target.weak += effect.amount
+            target.weak_turns = max(target.weak_turns, effect.duration)
+        case "draw":
+            draw_cards(actor, effect.amount)
+        case "energy":
+            actor.energy += effect.amount
+        case "initiative":
+            state.forced_second = target.name
+        case "multi_hit":
+            for _ in range(effect.hits):
+                deal_damage(actor, target, effect.amount)
+        case "vulnerable":
+            target.vulnerable += effect.amount
+            target.vulnerable_turns = max(target.vulnerable_turns, effect.duration)
+        case "conditional":
+            damage = conditional_damage(target, effect.amount)
+            if damage > 0:
+                deal_damage(actor, target, damage)
+        case "scaling":
+            deal_damage(actor, target, scaling_damage(actor, effect))
+
+
+# Deal damage through weak, vulnerable, ward, and block.
+def deal_damage(actor: PlayerState, target: PlayerState, amount: int) -> int:
+    damage = max(0, amount - actor.weak)
+    if damage == 0:
+        return 0
+    damage += target.vulnerable
+    if target.ward > 0:
+        if damage >= target.ward:
+            target.ward = 0
+        return 0
+    blocked = min(target.block, damage)
+    target.shield_charge += blocked // 2
+    target.block -= blocked
+    target.hp -= damage - blocked
+    return damage - blocked
+
+
+# Return scaling damage and spend shield charge when used.
+def scaling_damage(actor: PlayerState, effect: Effect) -> int:
+    if effect.condition == "shield_charge":
+        damage = effect.amount + actor.shield_charge
+        actor.shield_charge = 0
+        return damage
+    return effect.amount + actor.cards_played_this_turn
+
+
+# Return missing-HP-scaled conditional damage.
+def conditional_damage(target: PlayerState, amount: int) -> int:
+    missing_hp = max(0, STARTING_HP - target.hp)
+    return amount * missing_hp // STARTING_HP
+
+
+# Advance all deferred effects by one schedule tick.
+def advance_pending(state: DuelState) -> None:
+    remaining: list[PendingEffect] = []
+    for effect in state.pending:
+        if effect.delay > 0:
+            effect.delay -= 1
+            remaining.append(effect)
+        elif effect.primitive_id == "burn":
+            deal_damage(named_player(state, effect.owner), named_player(state, effect.target), effect.amount)
+            effect.duration -= 1
+            if effect.duration > 0:
+                remaining.append(effect)
+        elif effect.primitive_id == "bomb":
+            deal_damage(named_player(state, effect.owner), named_player(state, effect.target), effect.amount)
+    state.pending = remaining
+
+
+# Return a player by name.
+def named_player(state: DuelState, name: str) -> PlayerState:
+    if state.player.name == name:
+        return state.player
+    if state.enemy.name == name:
+        return state.enemy
+    raise KeyError(name)
+
+
+# Return whether either side has won.
+def winner(state: DuelState) -> str | None:
+    player_dead = state.player.hp <= 0
+    enemy_dead = state.enemy.hp <= 0
+    if player_dead and enemy_dead:
+        return "draw"
+    if enemy_dead:
+        return state.player.name
+    if player_dead:
+        return state.enemy.name
+    return None

generator.py

@@ -0,0 +1,633 @@
+from dataclasses import dataclass
+import json
+import subprocess
+import tempfile
+from collections import Counter
+from pathlib import Path
+from typing import Any, Protocol, Sequence
+
+from budget import Card, CardSpec, EffectPlan, cost_card
+from local_llm import LocalChatClient
+from primitives import PrimitiveId, School, school_bias, school_primitives
+
+
+class CardModelClient(Protocol):
+    # Return one raw model-authored card payload.
+    def create_card(self, payload: dict[str, Any]) -> dict[str, Any]:  # pragma: no cover
+        ...
+
+
+class CardPackClient(Protocol):
+    # Return one raw model-authored pack payload.
+    def create_pack(self, payload: dict[str, Any]) -> dict[str, Any]:  # pragma: no cover
+        ...
+
+
+@dataclass(frozen=True)
+class DeckCardContext:
+    name: str
+    cost: int
+    rules_text: str
+
+
+@dataclass(frozen=True)
+class CodexCardClient:
+    command: tuple[str, ...] = ("codex", "exec", "--ephemeral", "--skip-git-repo-check", "-")
+    timeout_seconds: int = 120
+    cwd: str = "."
+
+    # Return one raw card payload from a Codex invocation.
+    def create_card(self, payload: dict[str, Any]) -> dict[str, Any]:
+        pack_payload = dict(payload)
+        pack_payload.setdefault("cost", 1)
+        pack_payload["pack_size"] = 1
+        return self.create_pack(pack_payload)["cards"][0]
+
+    # Return one raw card pack payload from a Codex invocation.
+    def create_pack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_path = Path(tmpdir) / "codex-card-pack.json"
+            command = self.command[:-1] + ("--output-last-message", str(output_path), self.command[-1])
+            result = run_codex_command(command, codex_pack_prompt(payload), self.cwd, self.timeout_seconds)
+            if result.returncode != 0:
+                raise RuntimeError(result.stderr.strip() or "Codex card generation failed")
+            return json.loads(extract_json_object(output_path.read_text()))
+
+
+@dataclass(frozen=True)
+class MiniCPMCardClient:
+    chat: LocalChatClient
+
+    # Return one raw card payload from a local MiniCPM endpoint.
+    def create_card(self, payload: dict[str, Any]) -> dict[str, Any]:
+        pack_payload = dict(payload)
+        pack_payload.setdefault("cost", 1)
+        pack_payload["pack_size"] = 1
+        return self.create_pack(pack_payload)["cards"][0]
+
+    # Return one raw card pack payload from a local MiniCPM endpoint.
+    def create_pack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        text = self.chat.complete(card_system_prompt(), codex_pack_prompt(payload))
+        return json.loads(extract_json_object(text))
+
+
+@dataclass(frozen=True)
+class LlamaCppCardClient:
+    chat: LocalChatClient
+
+    # Return one raw card payload from a llama.cpp MiniCPM endpoint.
+    def create_card(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return generate_llamacpp_card(self.chat, payload, ())
+
+    # Return one raw card pack by generating single-card outputs.
+    def create_pack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        cards: list[dict[str, Any]] = []
+        for _ in range(int(payload.get("pack_size", 3))):
+            cards.append(generate_llamacpp_card(self.chat, payload, cards))
+        return {"cards": cards}
+
+
+TOOL_SCHEMA: dict[str, Any] = {
+    "name": "create_card",
+    "parameters": {
+        "type": "object",
+        "required": ["name", "flavor", "art_prompt", "effects"],
+        "properties": {
+            "name": {"type": "string"},
+            "flavor": {"type": "string"},
+            "art_prompt": {"type": "string"},
+            "effects": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "required": ["primitive_id"],
+                    "properties": {
+                        "primitive_id": {"type": "string"},
+                        "weight": {"type": "integer", "minimum": 1},
+                    },
+                },
+            },
+        },
+    },
+}
+
+PACK_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["cards"],
+    "properties": {
+        "cards": {
+            "type": "array",
+            "minItems": 3,
+            "maxItems": 3,
+            "items": TOOL_SCHEMA["parameters"],
+        }
+    },
+}
+
+
+# Generate one engine-costed card through a mockable model boundary.
+def generate_card(
+    client: CardModelClient,
+    school: School,
+    theme: str,
+    current_deck: Sequence[Card],
+    cost: int,
+    draft_anchors: Sequence[Card] = (),
+) -> Card:
+    raw = client.create_card(generator_payload(school, theme, current_deck, draft_anchors))
+    spec = parse_card_payload(raw, school, theme, cost)
+    return cost_card(spec)
+
+
+# Generate one engine-costed draft pack through a mockable model boundary.
+def generate_pack(
+    client: CardPackClient,
+    school: School,
+    theme: str,
+    current_deck: Sequence[Card],
+    cost: int,
+    pack_size: int = 3,
+    draft_anchors: Sequence[Card] = (),
+) -> tuple[Card, ...]:
+    raw = client.create_pack(pack_payload(school, theme, current_deck, cost, pack_size, draft_anchors))
+    pack = parse_pack_payload(raw, school, theme, cost)
+    if len(pack) < pack_size:
+        raise ValueError("generated pack had the wrong size")
+    return pack[:pack_size]
+
+
+# Generate several engine-costed cards through one model call.
+def generate_cards(
+    client: CardPackClient,
+    school: School,
+    theme: str,
+    current_deck: Sequence[Card],
+    costs: Sequence[int],
+    draft_anchors: Sequence[Card] = (),
+) -> tuple[Card, ...]:
+    raw = client.create_pack(cards_payload(school, theme, current_deck, costs, draft_anchors))
+    if len(raw["cards"]) != len(costs):
+        raise ValueError("generated card batch had the wrong size")
+    return tuple(cost_card(parse_card_payload(card, school, theme, cost)) for card, cost in zip(raw["cards"], costs))
+
+
+# Build the deck-aware model payload for card generation.
+def generator_payload(school: School, theme: str, current_deck: Sequence[Card], draft_anchors: Sequence[Card] = ()) -> dict[str, Any]:
+    return {
+        "school": school,
+        "theme": theme,
+        "school_identity": school_identity(school),
+        "school_bias": school_bias(school),
+        "primitive_guidance": primitive_guidance(school),
+        "allowed_primitives": school_primitives(school),
+        "current_deck": [card_context(card) for card in current_deck],
+        "current_deck_summary": deck_summary(current_deck),
+        "draft_anchors": [card_context(card) for card in draft_anchors],
+        "draft_anchor_summary": deck_summary(draft_anchors),
+        "draft_direction": draft_direction(school, draft_anchors),
+        "draft_need": draft_need(school, current_deck),
+        "tool_schema": TOOL_SCHEMA,
+        "instruction": "Choose effect shapes only; numeric magnitudes are assigned by the engine.",
+    }
+
+
+# Build the deck-aware model payload for draft pack generation.
+def pack_payload(
+    school: School,
+    theme: str,
+    current_deck: Sequence[Card],
+    cost: int,
+    pack_size: int,
+    draft_anchors: Sequence[Card] = (),
+) -> dict[str, Any]:
+    payload = generator_payload(school, theme, current_deck, draft_anchors)
+    payload["cost"] = cost
+    payload["pack_size"] = pack_size
+    payload["pack_schema"] = PACK_SCHEMA
+    return payload
+
+
+# Build the deck-aware model payload for multi-card generation.
+def cards_payload(
+    school: School,
+    theme: str,
+    current_deck: Sequence[Card],
+    costs: Sequence[int],
+    draft_anchors: Sequence[Card] = (),
+) -> dict[str, Any]:
+    payload = generator_payload(school, theme, current_deck, draft_anchors)
+    payload["costs"] = tuple(costs)
+    payload["pack_size"] = len(costs)
+    payload["pack_schema"] = PACK_SCHEMA
+    return payload
+
+
+# Build the prompt sent to Codex for one draft pack.
+def codex_pack_prompt(payload: dict[str, Any]) -> str:
+    cost_line = cost_instruction(payload)
+    return "\n".join(
+        (
+            "Generate a Tabras draft pack as strict JSON only.",
+            "Return exactly this shape: {\"cards\": [{\"name\": str, \"flavor\": str, \"art_prompt\": str, \"effects\": [{\"primitive_id\": str, \"weight\": int}]}]}",
+            "Do not include markdown, comments, or numeric magnitudes like damage/block/heal values.",
+            "The engine owns all final numbers. You only choose primitive ids and weights.",
+            "Make cards in the same response meaningfully different: vary primitive mixes, names, and tactical roles.",
+            f"School: {payload['school']}",
+            f"Theme: {payload['theme']}",
+            f"Class identity: {payload['school_identity']}",
+            f"School bias: {payload['school_bias']}",
+            f"Primitive guidance: {payload['primitive_guidance']}",
+            f"Deck primitive counts: {json.dumps(payload['current_deck_summary'])}",
+            f"Draft anchor cards: {json.dumps(payload['draft_anchors'])}",
+            f"Draft anchor primitive counts: {json.dumps(payload['draft_anchor_summary'])}",
+            f"Draft direction: {payload['draft_direction']}",
+            f"Draft need: {payload['draft_need']}",
+            cost_line,
+            f"Pack size: {payload['pack_size']}",
+            f"Return exactly {payload['pack_size']} cards: no fewer and no extras.",
+            f"Allowed primitives: {json.dumps(payload['allowed_primitives'])}",
+            f"Current deck context: {json.dumps(payload['current_deck'])}",
+        )
+    )
+
+
+# Return the system prompt for card generation.
+def card_system_prompt() -> str:
+    return "You are Tabras card authoring logic. Output strict JSON only. No thinking. No markdown."
+
+
+# Build a compact one-card prompt for llama.cpp MiniCPM.
+def llamacpp_card_prompt(payload: dict[str, Any], pack_cards: Sequence[dict[str, Any]]) -> str:
+    used_names = [card.get("name", "") for card in pack_cards]
+    pack_counts = pack_summary(pack_cards)
+    candidate_need = llama_candidate_need(payload, pack_counts)
+    return "\n".join(
+        (
+            "Create exactly one Tabras card as JSON.",
+            "Shape: {\"name\": string, \"flavor\": string, \"art_prompt\": string, \"effects\": [{\"primitive_id\": string, \"weight\": 1}]}",
+            "Use one or two effects. Do not write numeric damage, block, heal, or rules numbers.",
+            "Fit the school identity, but invent the card's fantasy and tactical purpose freely.",
+            "Prefer a new tactical purpose over repeating the current deck or pack.",
+            f"School: {payload['school']}",
+            f"Theme: {payload['theme']}",
+            f"Class identity: {payload['school_identity']}",
+            f"Bias: {payload['school_bias']}",
+            f"Primitive guidance: {payload['primitive_guidance']}",
+            f"Deck primitive counts: {json.dumps(payload['current_deck_summary'])}",
+            f"Draft anchor cards: {json.dumps(payload['draft_anchors'])}",
+            f"Draft anchor primitive counts: {json.dumps(payload['draft_anchor_summary'])}",
+            f"Draft direction: {payload['draft_direction']}",
+            f"Current draft need: {payload['draft_need']}",
+            f"This candidate should: {candidate_need}",
+            f"Allowed primitive_id values: {json.dumps(payload['allowed_primitives'])}",
+            f"Existing deck: {json.dumps(payload['current_deck'])}",
+            f"Already in this pack: {json.dumps(used_names)}",
+            f"Pack primitive counts so far: {json.dumps(pack_counts)}",
+        )
+    )
+
+
+# Generate one llama.cpp card with one corrective retry.
+def generate_llamacpp_card(chat: LocalChatClient, payload: dict[str, Any], pack_cards: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    prompt = llamacpp_card_prompt(payload, pack_cards)
+    card = parse_llamacpp_card_text(chat.complete(card_system_prompt(), prompt), payload, pack_cards)
+    need = llama_candidate_need(payload, pack_summary(pack_cards))
+    if card_satisfies_candidate_need(card, need):
+        return card
+    retry = parse_llamacpp_card_text(chat.complete(card_system_prompt(), llamacpp_retry_prompt(payload, need)), payload, pack_cards)
+    return retry if card_satisfies_candidate_need(retry, need) else card
+
+
+# Build a corrective prompt for a missed candidate need.
+def llamacpp_retry_prompt(payload: dict[str, Any], need: str) -> str:
+    return "\n".join(
+        (
+            "Create exactly one corrected Tabras card as JSON.",
+            "Shape: {\"name\": string, \"flavor\": string, \"art_prompt\": string, \"effects\": [{\"primitive_id\": string, \"weight\": 1}]}",
+            f"School: {payload['school']}",
+            f"Theme: {payload['theme']}",
+            f"Allowed primitive_id values: {json.dumps(payload['allowed_primitives'])}",
+            f"Correction requirement: {need}",
+            "If the requirement mentions primitive_id block, include an effect with primitive_id exactly \"block\".",
+            "If the requirement mentions primitive_id scaling, include an effect with primitive_id exactly \"scaling\".",
+            "If the requirement mentions primitive_id multi_hit, include an effect with primitive_id exactly \"multi_hit\".",
+            "If the requirement mentions primitive_id initiative, include an effect with primitive_id exactly \"initiative\".",
+            "JSON only.",
+        )
+    )
+
+
+# Return the cost instruction for a Codex generation payload.
+def cost_instruction(payload: dict[str, Any]) -> str:
+    if "costs" in payload:
+        return f"Card costs by index: {json.dumps(payload['costs'])}"
+    return f"Card cost for every candidate: {payload['cost']}"
+
+
+# Run Codex for one card-generation prompt.
+def run_codex_command(command: tuple[str, ...], prompt: str, cwd: str, timeout_seconds: int) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        input=prompt,
+        text=True,
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        timeout=timeout_seconds,
+    )
+
+
+# Convert a costed card into compact generator context.
+def card_context(card: Card) -> dict[str, Any]:
+    return DeckCardContext(card.name, card.cost, card.rules_text()).__dict__
+
+
+# Return the design identity for one school.
+def school_identity(school: School) -> str:
+    identities = {
+        "fire": "Fire races with direct pressure, burn clocks, delayed bombs, and occasional scaling finishers.",
+        "ice": "Ice wins through tempo, forced sequencing, vulnerability windows, and precise multi-hit pressure.",
+        "earth": "Earth absorbs pressure with block, banks blocked damage as shield charge, then uses scaling to convert charge into burst; plain deal is secondary.",
+    }
+    return identities[school]
+
+
+# Return school-specific primitive design guidance.
+def primitive_guidance(school: School) -> str:
+    guidance = {
+        "fire": "Use deal for immediate pressure, burn for damage over turns, bomb for delayed burst, and scaling for finishers.",
+        "ice": "Use initiative for turn order, vulnerable before multi_hit or deal, and conditional for precise finishers.",
+        "earth": "Use block to create shield charge, scaling to spend shield charge as burst, ward for rare protection, and weak/draw as support.",
+    }
+    return guidance[school]
+
+
+# Return a concise direction inferred from anchor cards.
+def draft_direction(school: School, draft_anchors: Sequence[Card]) -> str:
+    counts = deck_summary(draft_anchors)
+    if not counts:
+        return "No anchor cards yet; generate a strong candidate that could define the deck's direction."
+    if school == "fire":
+        return fire_anchor_direction(counts)
+    if school == "ice":
+        return ice_anchor_direction(counts)
+    return earth_anchor_direction(counts)
+
+
+# Return Fire direction from anchor primitives.
+def fire_anchor_direction(counts: dict[str, int]) -> str:
+    if counts.get("bomb", 0) or counts.get("burn", 0):
+        return "Lean into a pressure clock: pair delayed damage with immediate deal, draw, or scaling finishers."
+    return "Lean into fast pressure: add burn, bomb, draw, or finishers that support the anchor cards."
+
+
+# Return Ice direction from anchor primitives.
+def ice_anchor_direction(counts: dict[str, int]) -> str:
+    if counts.get("vulnerable", 0) and not counts.get("multi_hit", 0):
+        return "Exploit vulnerability windows with multi_hit, initiative, and precise finishers."
+    if counts.get("multi_hit", 0) and not counts.get("vulnerable", 0):
+        return "Support multi-hit pressure with vulnerable, initiative, draw, or conditional finishers."
+    return "Build a tempo chain around initiative, vulnerable, multi_hit, and conditional payoff."
+
+
+# Return Earth direction from anchor primitives.
+def earth_anchor_direction(counts: dict[str, int]) -> str:
+    if counts.get("block", 0) and not counts.get("scaling", 0):
+        return "Use block as the shield-charge engine and add scaling payoff, weak, draw, or conversion."
+    if counts.get("scaling", 0):
+        return "Support shield-charge burst with block, survival, draw, weak, and occasional ward."
+    return "Build the absorb-then-retaliate loop with block and shield-charge payoff."
+
+
+# Return a per-candidate need for one-card llama.cpp generation.
+def llama_candidate_need(payload: dict[str, Any], pack_counts: dict[str, int]) -> str:
+    draft_need_text = str(payload["draft_need"]).lower()
+    if "add block" in draft_need_text and pack_counts.get("block", 0) == 0:
+        return "explore primitive_id block as the shield-charge engine while inventing the card fantasy freely."
+    if "scaling" in draft_need_text and pack_counts.get("scaling", 0) == 0:
+        return "explore primitive_id scaling as the shield-charge payoff while inventing the card fantasy freely."
+    if "multi_hit" in draft_need_text and pack_counts.get("multi_hit", 0) == 0:
+        return "explore primitive_id multi_hit as the payoff for vulnerability while inventing the card fantasy freely."
+    if "initiative" in draft_need_text and pack_counts.get("initiative", 0) == 0:
+        return "explore primitive_id initiative to control turn order while inventing the card fantasy freely."
+    if "plain damage is covered" in draft_need_text and pack_counts.get("deal", 0) > 0:
+        return "avoid another primary deal card; explore block, scaling, weak, draw, or support."
+    return "fit the draft need with a distinct name, fantasy, and tactical purpose."
+
+
+# Return whether a card satisfies a per-candidate need.
+def card_satisfies_candidate_need(card: dict[str, Any], need: str) -> bool:
+    effects = card.get("effects", [])
+    primitives = [effect.get("primitive_id") for effect in effects if isinstance(effect, dict)] if isinstance(effects, list) else []
+    if "primitive_id scaling" in need:
+        return "scaling" in primitives
+    if "primitive_id block" in need:
+        return "block" in primitives
+    if "primitive_id multi_hit" in need:
+        return "multi_hit" in primitives
+    if "primitive_id initiative" in need:
+        return "initiative" in primitives
+    if "avoid another primary deal" in need:
+        return not primitives or primitives[0] != "deal"
+    return True
+
+
+# Count primitive ids represented in a costed deck.
+def deck_summary(deck: Sequence[Card]) -> dict[str, int]:
+    counts: Counter[str] = Counter()
+    for card in deck:
+        counts.update(effect.primitive_id for effect in card.effects)
+    return ordered_counts(counts)
+
+
+# Count primitive ids represented in raw generated pack cards.
+def pack_summary(cards: Sequence[dict[str, Any]]) -> dict[str, int]:
+    counts: Counter[str] = Counter()
+    for card in cards:
+        effects = card.get("effects", [])
+        if isinstance(effects, list):
+            counts.update(effect.get("primitive_id") for effect in effects if isinstance(effect, dict))
+    return ordered_counts(counts)
+
+
+# Return a compact deck-aware drafting need.
+def draft_need(school: School, deck: Sequence[Card]) -> str:
+    counts = deck_summary(deck)
+    if school == "earth":
+        return earth_draft_need(counts)
+    if school == "fire":
+        return fire_draft_need(counts)
+    return ice_draft_need(counts)
+
+
+# Return an Earth-specific drafting need.
+def earth_draft_need(counts: dict[str, int]) -> str:
+    protection = counts.get("block", 0) + counts.get("ward", 0)
+    payoff = counts.get("scaling", 0) + counts.get("deal", 0) + counts.get("conditional", 0)
+    if counts.get("scaling", 0) > 0 and counts.get("block", 0) <= counts.get("scaling", 0):
+        return "Scaling payoff exists; add block to bank shield charge before adding more plain deal."
+    if counts.get("block", 0) > 0 and counts.get("scaling", 0) == 0:
+        return "Add a shield-charge payoff using scaling; avoid making plain deal the main Earth payoff."
+    if counts.get("deal", 0) >= protection + 2:
+        return "Plain damage is covered; prefer block, scaling shield-charge payoff, weak, draw, or conversion."
+    if protection >= payoff + 2:
+        return "Protection is covered; prefer shield-charge payoff, pressure, weak, draw, or conversion instead of more ward."
+    if counts.get("block", 0) == 0:
+        return "Add block so Earth can bank shield charge before spending it."
+    return "Improve the absorb-then-retaliate loop with a distinct support or payoff card."
+
+
+# Return a Fire-specific drafting need.
+def fire_draft_need(counts: dict[str, int]) -> str:
+    delayed = counts.get("burn", 0) + counts.get("bomb", 0)
+    pressure = counts.get("deal", 0) + counts.get("scaling", 0)
+    if delayed >= pressure + 2:
+        return "Delayed damage is covered; prefer immediate deal, scaling finishers, draw, or energy."
+    if counts.get("deal", 0) == 0:
+        return "Add immediate deal so Fire can race before delayed damage resolves."
+    return "Add a distinct pressure card that advances Fire's race plan."
+
+
+# Return an Ice-specific drafting need.
+def ice_draft_need(counts: dict[str, int]) -> str:
+    setup = counts.get("initiative", 0) + counts.get("vulnerable", 0)
+    payoff = counts.get("multi_hit", 0) + counts.get("conditional", 0) + counts.get("deal", 0)
+    if counts.get("vulnerable", 0) > 0 and counts.get("multi_hit", 0) == 0:
+        return "Vulnerability setup exists; add a multi_hit payoff instead of more plain deal."
+    if counts.get("initiative", 0) == 0 and counts.get("vulnerable", 0) >= 2:
+        return "Add initiative to control turn order around the vulnerability window."
+    if counts.get("deal", 0) >= setup + 3:
+        return "Plain damage is covered; prefer initiative, vulnerable, multi_hit, conditional, draw, or tempo."
+    if setup >= payoff + 2:
+        return "Tempo setup is covered; prefer payoff damage or multi-hit pressure."
+    return "Add a tempo card that creates or exploits a vulnerability window."
+
+
+# Return counts with empty keys removed.
+def ordered_counts(counts: Counter[str]) -> dict[str, int]:
+    return {key: counts[key] for key in sorted(counts) if key}
+
+
+# Parse model payload into a card spec without trusting model-authored numbers.
+def parse_card_payload(raw: dict[str, Any], school: School, theme: str, cost: int) -> CardSpec:
+    effects = tuple(parse_effect_plan(effect) for effect in raw["effects"])
+    return CardSpec(
+        name=str(raw["name"]),
+        cost=cost,
+        school=school,
+        theme=theme,
+        effect_plans=effects,
+        flavor=str(raw.get("flavor", "")),
+        art_prompt=str(raw.get("art_prompt", "")),
+    )
+
+
+# Parse model payload into costed draft cards.
+def parse_pack_payload(raw: dict[str, Any], school: School, theme: str, cost: int) -> tuple[Card, ...]:
+    return tuple(cost_card(parse_card_payload(card, school, theme, cost)) for card in raw["cards"])
+
+
+# Parse one model-authored effect plan.
+def parse_effect_plan(raw: dict[str, Any]) -> EffectPlan:
+    primitive_id = raw["primitive_id"]
+    weight = max(1, int(raw.get("weight", 1)))
+    return EffectPlan(primitive_id=primitive_id, weight=weight)  # type: ignore[arg-type]
+
+
+# Normalize one-card or pack-shaped model JSON into one card object.
+def normalize_card_response(raw: dict[str, Any]) -> dict[str, Any]:
+    if "cards" in raw and isinstance(raw["cards"], list) and raw["cards"]:
+        return normalize_card_response(raw["cards"][0])
+    if "shape" in raw and isinstance(raw["shape"], dict):
+        return normalize_card_response(raw["shape"])
+    if "effects" not in raw and len(raw) == 1:
+        value = next(iter(raw.values()))
+        if isinstance(value, dict):
+            return normalize_card_response(value)
+    return raw
+
+
+# Parse one llama.cpp card response, falling back on malformed JSON.
+def parse_llamacpp_card_text(text: str, payload: dict[str, Any], pack_cards: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    try:
+        raw = normalize_card_response(json.loads(extract_json_object(text)))
+    except (TypeError, ValueError, json.JSONDecodeError):
+        raw = {}
+    return repair_llamacpp_card(raw, payload, pack_cards)
+
+
+# Repair cheap llama.cpp JSON into the strict card schema.
+def repair_llamacpp_card(raw: dict[str, Any], payload: dict[str, Any], pack_cards: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    allowed = tuple(payload["allowed_primitives"])
+    effects = repair_effects(raw.get("effects"), allowed)
+    name = str(raw.get("name") or fallback_card_name(payload["school"], effects, pack_cards))
+    return {
+        "name": name,
+        "flavor": str(raw.get("flavor", "")),
+        "art_prompt": str(raw.get("art_prompt") or fallback_art_prompt(payload)),
+        "effects": effects,
+    }
+
+
+# Repair a model-authored effect list to allowed primitive ids.
+def repair_effects(raw: Any, allowed: Sequence[str]) -> list[dict[str, Any]]:
+    effects = [effect for effect in raw if isinstance(effect, dict)] if isinstance(raw, list) else []
+    repaired = [repair_effect(effect, allowed) for effect in effects if effect.get("primitive_id") in allowed]
+    return repaired[:2] or [{"primitive_id": allowed[0], "weight": 1}]
+
+
+# Repair one model-authored effect to a minimal engine-owned plan.
+def repair_effect(raw: dict[str, Any], allowed: Sequence[str]) -> dict[str, Any]:
+    primitive_id = raw["primitive_id"] if raw.get("primitive_id") in allowed else allowed[0]
+    return {"primitive_id": primitive_id, "weight": max(1, int(raw.get("weight", 1)))}
+
+
+# Build a deterministic fallback card name.
+def fallback_card_name(school: str, effects: Sequence[dict[str, Any]], pack_cards: Sequence[dict[str, Any]]) -> str:
+    used = {str(card.get("name", "")) for card in pack_cards}
+    base = f"{school.title()} {' '.join(str(effect['primitive_id']).title() for effect in effects)}".strip()
+    if base not in used:
+        return base
+    return f"{base} {len(used) + 1}"
+
+
+# Build fallback art text when the model omits it.
+def fallback_art_prompt(payload: dict[str, Any]) -> str:
+    return f"{payload['theme']} {payload['school']} card art"
+
+
+# Extract the first JSON object from model text.
+def extract_json_object(text: str) -> str:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end < start:
+        raise ValueError("Codex response did not contain a JSON object")
+    candidate = balance_json_closers(text[start : end + 1])
+    json.loads(candidate)
+    return candidate
+
+
+# Append missing JSON object or array closers.
+def balance_json_closers(text: str) -> str:
+    stack: list[str] = []
+    in_string = False
+    escaped = False
+    for char in text:
+        if escaped:
+            escaped = False
+            continue
+        if char == "\\" and in_string:
+            escaped = True
+            continue
+        if char == "\"":
+            in_string = not in_string
+            continue
+        if in_string:
+            continue
+        if char == "{":
+            stack.append("}")
+        elif char == "[":
+            stack.append("]")
+        elif stack and char == stack[-1]:
+            stack.pop()
+    return text + "".join(reversed(stack))

launch_ai.py

@@ -0,0 +1,19 @@
+from ai_runtime import DEFAULT_APP_PORT, DEFAULT_CARD_PORT, local_ai_env, start_minicpm_server
+from app import CSS, HEAD, build_app
+
+
+# Launch Tabras with MiniCPM card authoring and Nemotron boss play.
+def main() -> None:
+    server = start_minicpm_server(port=DEFAULT_CARD_PORT)
+    try:
+        env = local_ai_env(DEFAULT_CARD_PORT)
+        import os
+
+        os.environ.update(env)
+        build_app().launch(server_name="127.0.0.1", server_port=DEFAULT_APP_PORT, css=CSS, head=HEAD)
+    finally:
+        server.terminate()
+
+
+if __name__ == "__main__":
+    main()

local_llm.py

@@ -0,0 +1,277 @@
+import json
+import os
+from dataclasses import dataclass
+from importlib.util import find_spec
+from typing import Any, Callable
+from urllib import request
+
+
+@dataclass(frozen=True)
+class LocalChatClient:
+    endpoint: str
+    model: str
+    timeout_seconds: int = 60
+    temperature: float = 0.2
+    max_tokens: int = 256
+
+    # Complete one chat prompt through an OpenAI-compatible local endpoint.
+    def complete(self, system: str, user: str) -> str:
+        payload = chat_payload(self.model, system, user, self.temperature, self.max_tokens)
+        req = request.Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with request.urlopen(req, timeout=self.timeout_seconds) as response:
+            return parse_chat_response(json.loads(response.read().decode("utf-8")))
+
+
+@dataclass(frozen=True)
+class LocalJsonChatClient:
+    endpoint: str
+    model: str
+    timeout_seconds: int = 60
+    temperature: float = 0.0
+    max_tokens: int = 256
+
+    # Complete one chat prompt through a JSON-constrained local endpoint.
+    def complete(self, system: str, user: str) -> str:
+        payload = json_chat_payload(self.model, system, user, self.temperature, self.max_tokens)
+        req = request.Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with request.urlopen(req, timeout=self.timeout_seconds) as response:
+            return parse_chat_response(json.loads(response.read().decode("utf-8")))
+
+
+@dataclass(frozen=True)
+class LocalCompletionClient:
+    endpoint: str
+    model: str
+    prompt_template: Callable[[str, str], str]
+    timeout_seconds: int = 60
+    temperature: float = 0.2
+    max_tokens: int = 256
+
+    # Complete one prompt through an OpenAI-compatible local completion endpoint.
+    def complete(self, system: str, user: str) -> str:
+        prompt = self.prompt_template(system, user)
+        payload = completion_payload(self.model, prompt, self.temperature, self.max_tokens)
+        req = request.Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with request.urlopen(req, timeout=self.timeout_seconds) as response:
+            return parse_completion_response(json.loads(response.read().decode("utf-8")))
+
+
+@dataclass(frozen=True)
+class NemotronTransformersChatClient:
+    model: Any
+    tokenizer: Any
+    max_new_tokens: int = 256
+    temperature: float = 0.2
+
+    # Complete one prompt through a local Nemotron Transformers model.
+    def complete(self, system: str, user: str) -> str:
+        messages = chat_messages(system, user)
+        inputs = self.tokenizer.apply_chat_template(
+            messages,
+            tokenize=True,
+            add_generation_prompt=True,
+            return_tensors="pt",
+        )
+        outputs = self.model.generate(
+            tensor_to_model_device(inputs, self.model),
+            max_new_tokens=self.max_new_tokens,
+            do_sample=self.temperature > 0,
+            temperature=self.temperature,
+        )
+        return decode_generated_text(self.tokenizer, inputs, outputs)
+
+    # Load Nemotron with its required tokenizer chat template.
+    @classmethod
+    def load(
+        cls,
+        model_path: str,
+        max_new_tokens: int = 256,
+        temperature: float = 0.2,
+    ) -> "NemotronTransformersChatClient":  # pragma: no cover
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        tokenizer = AutoTokenizer.from_pretrained(model_path)
+        model = AutoModelForCausalLM.from_pretrained(model_path, **transformers_model_kwargs())
+        return cls(model.eval(), tokenizer, max_new_tokens=max_new_tokens, temperature=temperature)
+
+
+@dataclass(frozen=True)
+class MLXChatClient:
+    model: Any
+    tokenizer: Any
+    prompt_template: Callable[[str, str], str]
+    generate_func: Callable[..., str]
+    max_tokens: int = 128
+
+    # Complete one prompt through a local MLX model.
+    def complete(self, system: str, user: str) -> str:
+        prompt = self.prompt_template(system, user)
+        return self.generate_func(self.model, self.tokenizer, prompt, verbose=False, max_tokens=self.max_tokens)
+
+    # Load one MLX model for Apple Silicon inference.
+    @classmethod
+    def load(
+        cls,
+        model_path: str,
+        prompt_template: Callable[[str, str], str],
+        max_tokens: int = 128,
+    ) -> "MLXChatClient":  # pragma: no cover
+        from mlx_lm import generate, load
+
+        model, tokenizer = load(model_path)
+        return cls(model, tokenizer, prompt_template, generate, max_tokens=max_tokens)
+
+
+@dataclass(frozen=True)
+class MiniCPMTransformersChatClient:
+    model: Any
+    tokenizer: Any
+    max_new_tokens: int = 512
+
+    # Complete one text prompt through a local MiniCPM model.chat call.
+    def complete(self, system: str, user: str) -> str:
+        return str(
+            self.model.chat(
+                msgs=[{"role": "user", "content": user}],
+                image=None,
+                tokenizer=self.tokenizer,
+                system_prompt=system,
+                sampling=False,
+                max_new_tokens=self.max_new_tokens,
+            )
+        )
+
+    # Load MiniCPM with trust_remote_code for its custom chat method.
+    @classmethod
+    def load(cls, model_path: str, max_new_tokens: int = 512) -> "MiniCPMTransformersChatClient":  # pragma: no cover
+        import torch
+        from transformers import AutoModel, AutoTokenizer
+
+        model = AutoModel.from_pretrained(
+            model_path,
+            trust_remote_code=True,
+            attn_implementation="sdpa",
+            torch_dtype=local_torch_dtype(torch),
+        )
+        if torch.cuda.is_available():
+            model = model.cuda()
+        tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
+        return cls(model.eval(), tokenizer, max_new_tokens=max_new_tokens)
+
+
+# Build an OpenAI-compatible chat completion payload.
+def chat_payload(model: str, system: str, user: str, temperature: float, max_tokens: int | None = None) -> dict[str, Any]:
+    payload = {
+        "model": model,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        "temperature": temperature,
+    }
+    if max_tokens is not None:
+        payload["max_tokens"] = max_tokens
+    return payload
+
+
+# Build an OpenAI-compatible JSON-constrained chat payload.
+def json_chat_payload(model: str, system: str, user: str, temperature: float, max_tokens: int) -> dict[str, Any]:
+    payload = chat_payload(model, system, user, temperature, max_tokens)
+    payload["response_format"] = {"type": "json_object"}
+    return payload
+
+
+# Build an OpenAI-compatible text completion payload.
+def completion_payload(model: str, prompt: str, temperature: float, max_tokens: int) -> dict[str, Any]:
+    return {
+        "model": model,
+        "prompt": prompt,
+        "temperature": temperature,
+        "max_tokens": max_tokens,
+    }
+
+
+# Build standard system/user chat messages.
+def chat_messages(system: str, user: str) -> list[dict[str, str]]:
+    return [{"role": "system", "content": system}, {"role": "user", "content": user}]
+
+
+# Render Nemotron's documented single-turn prompt markers.
+def nemotron_prompt(system: str, user: str) -> str:
+    return f"<extra_id_0>System\n{system}\n\n<extra_id_1>User\n{user}\n<extra_id_1>Assistant\n"
+
+
+# Render a text-only MiniCPM prompt for its model.chat API.
+def minicpm_text_prompt(system: str, user: str) -> str:
+    return f"System:\n{system}\n\nUser:\n{user}"
+
+
+# Parse text content from an OpenAI-compatible chat response.
+def parse_chat_response(raw: dict[str, Any]) -> str:
+    return str(raw["choices"][0]["message"]["content"])
+
+
+# Parse text content from an OpenAI-compatible completion response.
+def parse_completion_response(raw: dict[str, Any]) -> str:
+    if "content" in raw:
+        return str(raw["content"])
+    choice = raw["choices"][0]
+    if "text" in choice:
+        return str(choice["text"])
+    return str(choice["message"]["content"])
+
+
+# Move generated inputs onto the model device when tensors support it.
+def tensor_to_model_device(inputs: Any, model: Any) -> Any:
+    device = getattr(model, "device", None)
+    if device is not None and hasattr(inputs, "to"):
+        return inputs.to(device)
+    return inputs
+
+
+# Decode only tokens generated after the input prompt.
+def decode_generated_text(tokenizer: Any, inputs: Any, outputs: Any) -> str:
+    output = outputs[0]
+    prompt_length = token_length(inputs)
+    generated = output[prompt_length:]
+    return str(tokenizer.decode(generated, skip_special_tokens=True)).strip()
+
+
+# Return the final token dimension for tensor-like input ids.
+def token_length(inputs: Any) -> int:
+    if hasattr(inputs, "shape"):
+        return int(inputs.shape[-1])
+    if inputs and isinstance(inputs[0], list):
+        return len(inputs[0])
+    return len(inputs)
+
+
+# Return practical local loading kwargs for causal Transformers models.
+def transformers_model_kwargs() -> dict[str, Any]:
+    kwargs: dict[str, Any] = {"torch_dtype": "auto"}
+    if find_spec("accelerate") is not None:
+        kwargs["device_map"] = "auto"
+        kwargs["offload_folder"] = os.environ.get("TABRAS_MODEL_OFFLOAD", "/tmp/tabras-model-offload")
+    return kwargs
+
+
+# Return the best dtype available for MiniCPM local inference.
+def local_torch_dtype(torch: Any) -> Any:
+    if torch.cuda.is_available():
+        return torch.bfloat16
+    return "auto"

play.py

@@ -0,0 +1,388 @@
+from random import Random
+from typing import Callable, Protocol
+
+from budget import Card
+from draft import backbone_deck, draft_deck_from_packs
+from generator import CardPackClient, CodexCardClient, deck_summary
+from game import DuelState, PlayerState, conditional_damage, create_player, draw_cards, named_player, opponent, play_card_from_hand, start_round, winner
+from primitives import School
+
+Prompt = Callable[[str], str]
+Printer = Callable[[str], None]
+Chooser = Callable[[DuelState, PlayerState], int | None]
+
+
+class BossClientLike(Protocol):
+    # Return one raw boss decision payload.
+    def choose_cards(self, payload: dict[str, object]) -> dict[str, object]:  # pragma: no cover
+        ...
+
+OPENING_HAND_SIZE = 3
+MAX_ROUNDS = 20
+SYNERGY_COSTS = (2, 2, 3, 3, 4, 4, 4, 5, 5)
+
+
+# Return a compact line for one card in hand.
+def card_line(index: int, card: Card) -> str:
+    return f"{index}: {card.name} [{card.cost}] - {card.rules_text()}"
+
+
+# Return a compact line for one draft candidate.
+def pack_line(index: int, card: Card) -> str:
+    return f"{index}: {card.name} [{card.cost}] - {card.rules_text()} | {card.flavor}"
+
+
+# Return the visible combat state for one player.
+def player_line(player: PlayerState) -> str:
+    zones = f"hand {len(player.hand)}, deck {len(player.deck)}, discard {len(player.discard)}"
+    return f"{player.name}: {player.hp} HP, {player.energy} energy, {player.block} block, {player.ward} ward, {player.shield_charge} charge ({zones})"
+
+
+# Return a focused prompt-state line before a player chooses.
+def choice_state_line(state: DuelState, actor: PlayerState) -> str:
+    target = opponent(state, actor)
+    return f"{actor.name} energy {actor.energy}. {target.name}: {target.hp} HP, {target.block} block, {target.ward} ward."
+
+
+# Return currently playable hand indexes for a player.
+def playable_indexes(player: PlayerState) -> tuple[int, ...]:
+    return tuple(index for index, card in enumerate(player.hand) if card.cost <= player.energy)
+
+
+# Return a simple legal demo deck without model generation.
+def demo_deck(school: School, theme: str) -> tuple[Card, ...]:
+    backbone = backbone_deck(school, theme)
+    return (backbone * 3)[:15]
+
+
+# Print a player's hand.
+def print_hand(player: PlayerState, print_fn: Printer) -> None:
+    for index, card in enumerate(player.hand):
+        print_fn(card_line(index, card))
+
+
+# Print one generated draft pack.
+def print_pack(pack: tuple[Card, ...], print_fn: Printer) -> None:
+    for index, card in enumerate(pack):
+        print_fn(pack_line(index, card))
+
+
+# Prompt the human for one draft pack choice.
+def prompt_pack_choice(prompt: Prompt, print_fn: Printer) -> Callable[[tuple[Card, ...], tuple[Card, ...]], int]:
+    # Choose one card from a generated pack.
+    def choose(current_deck: tuple[Card, ...], pack: tuple[Card, ...]) -> int:
+        del current_deck
+        while True:
+            print_pack(pack, print_fn)
+            answer = prompt("Draft card number: ").strip()
+            if answer.isdigit() and int(answer) < len(pack):
+                return int(answer)
+            print_fn("Choose one of the shown draft cards.")
+
+    return choose
+
+
+# Draft a player deck from nine generated packs.
+def draft_player_deck(
+    client: CardPackClient,
+    school: School,
+    theme: str,
+    prompt: Prompt = input,
+    print_fn: Printer = print,
+    rng: Random | None = None,
+) -> tuple[Card, ...]:
+    pick_number = 0
+    choose_pack = prompt_pack_choice(prompt, print_fn)
+
+    # Choose one pack card while printing draft progress.
+    def choose(current_deck: tuple[Card, ...], pack: tuple[Card, ...]) -> int:
+        nonlocal pick_number
+        pick_number += 1
+        print_fn(f"Draft pick {pick_number}/9. Current deck: {len(current_deck)} cards.")
+        return choose_pack(current_deck, pack)
+
+    return draft_deck_from_packs(client, school, theme, SYNERGY_COSTS, choose, rng=rng)
+
+
+# Draft an enemy deck by taking the strongest card from each generated pack.
+def draft_enemy_deck(
+    client: CardPackClient,
+    school: School,
+    theme: str,
+    print_fn: Printer = print,
+    rng: Random | None = None,
+) -> tuple[Card, ...]:
+    pick_number = 0
+
+    # Choose a deck-aware card from each generated pack.
+    def choose(current_deck: tuple[Card, ...], pack: tuple[Card, ...]) -> int:
+        nonlocal pick_number
+        pick_number += 1
+        choice = best_draft_index(current_deck, pack)
+        print_fn(f"Enemy generated pick {pick_number}/9: {pack[choice].name}")
+        return choice
+
+    return draft_deck_from_packs(client, school, theme, SYNERGY_COSTS, choose, rng=rng)
+
+
+# Return the strongest candidate index in a generated pack.
+def best_pack_index(pack: tuple[Card, ...]) -> int:
+    return max(range(len(pack)), key=lambda index: (card_score(pack[index]), -index))
+
+
+# Return the strongest draft pick for the current deck's school plan.
+def best_draft_index(current_deck: tuple[Card, ...], pack: tuple[Card, ...]) -> int:
+    return max(range(len(pack)), key=lambda index: (draft_card_score(current_deck, pack[index]), -index))
+
+
+# Return a deck-aware draft score for one card.
+def draft_card_score(current_deck: tuple[Card, ...], card: Card) -> int:
+    counts = deck_summary(current_deck)
+    return card_score(card) + school_need_bonus(card, counts) - repetition_penalty(card, counts)
+
+
+# Return class-specific bonus for cards that fill missing deck needs.
+def school_need_bonus(card: Card, counts: dict[str, int]) -> int:
+    primitives = card_primitives(card)
+    if card.school == "ice":
+        return ice_need_bonus(primitives, counts)
+    if card.school == "earth":
+        return earth_need_bonus(primitives, counts)
+    return fire_need_bonus(primitives, counts)
+
+
+# Return Fire's draft need bonus.
+def fire_need_bonus(primitives: tuple[str, ...], counts: dict[str, int]) -> int:
+    delayed = counts.get("burn", 0) + counts.get("bomb", 0)
+    pressure = counts.get("deal", 0) + counts.get("scaling", 0)
+    if delayed >= pressure and ("deal" in primitives or "burn" in primitives or "scaling" in primitives):
+        return 18
+    return 8 if "deal" in primitives and counts.get("deal", 0) < 5 else 0
+
+
+# Return Ice's draft need bonus.
+def ice_need_bonus(primitives: tuple[str, ...], counts: dict[str, int]) -> int:
+    if counts.get("vulnerable", 0) > 0 and counts.get("multi_hit", 0) == 0 and "multi_hit" in primitives:
+        return 35
+    if counts.get("multi_hit", 0) > 0 and counts.get("initiative", 0) == 0 and "initiative" in primitives:
+        return 35
+    if counts.get("multi_hit", 0) > counts.get("vulnerable", 0) + 1 and "vulnerable" in primitives:
+        return 30
+    if counts.get("multi_hit", 0) > counts.get("initiative", 0) + 2 and "initiative" in primitives:
+        return 30
+    return 0
+
+
+# Return Earth's draft need bonus.
+def earth_need_bonus(primitives: tuple[str, ...], counts: dict[str, int]) -> int:
+    if counts.get("scaling", 0) > 0 and counts.get("block", 0) <= counts.get("scaling", 0) and "block" in primitives:
+        return 45
+    if counts.get("deal", 0) >= counts.get("block", 0) + 2 and ("block" in primitives or "draw" in primitives or "weak" in primitives):
+        return 35
+    if counts.get("block", 0) > 0 and counts.get("scaling", 0) == 0 and "scaling" in primitives:
+        return 35
+    protection = counts.get("block", 0) + counts.get("ward", 0)
+    payoff = counts.get("scaling", 0) + counts.get("conditional", 0)
+    if protection > payoff and ("scaling" in primitives or "weak" in primitives or "draw" in primitives):
+        return 20
+    return 0
+
+
+# Return a penalty for repeating already represented primitives.
+def repetition_penalty(card: Card, counts: dict[str, int]) -> int:
+    return sum(counts.get(primitive, 0) * repeat_weight(primitive) for primitive in card_primitives(card))
+
+
+# Return how strongly repeated primitives are penalized.
+def repeat_weight(primitive_id: str) -> int:
+    if primitive_id in {"multi_hit", "bomb", "ward", "block"}:
+        return 5
+    return 3
+
+
+# Return primitive ids on one card.
+def card_primitives(card: Card) -> tuple[str, ...]:
+    return tuple(effect.primitive_id for effect in card.effects)
+
+
+# Prompt the human for one card choice.
+def prompt_human_choice(prompt: Prompt, print_fn: Printer) -> Chooser:
+    # Choose one playable card from prompted input.
+    def choose(state: DuelState, actor: PlayerState) -> int | None:
+        while True:
+            print_fn(choice_state_line(state, actor))
+            print_hand(actor, print_fn)
+            answer = prompt("Choose card number, or pass: ").strip().lower()
+            if answer in {"", "p", "pass"}:
+                return None
+            if answer.isdigit() and int(answer) in playable_indexes(actor):
+                return int(answer)
+            print_fn("That card is not playable.")
+
+    return choose
+
+
+# Choose the best playable card for the enemy heuristic.
+def choose_enemy_card(state: DuelState, actor: PlayerState) -> int | None:
+    playable = playable_indexes(actor)
+    if not playable:
+        return None
+    target = opponent(state, actor)
+    lethal = tuple(index for index in playable if immediate_hp_damage(actor, target, actor.hand[index]) >= target.hp)
+    if lethal:
+        return max(lethal, key=lambda index: (immediate_hp_damage(actor, target, actor.hand[index]), -index))
+    return max(playable, key=lambda index: (combat_card_score(state, actor, actor.hand[index]), -index))
+
+
+# Choose the best playable card for the assistant.
+def choose_assistant_card(state: DuelState, actor: PlayerState) -> int | None:
+    return choose_enemy_card(state, actor)
+
+
+# Return a static draft score for one card.
+def card_score(card: Card) -> int:
+    return sum(effect_score(effect.primitive_id, effect.amount, effect.hits) for effect in card.effects) - card.cost
+
+
+# Return a combat-aware score for one card.
+def combat_card_score(state: DuelState, actor: PlayerState, card: Card) -> int:
+    target = opponent(state, actor)
+    defense_bonus = 4 if actor.hp <= target.hp else 0
+    return immediate_hp_damage(actor, target, card) * 3 + card_score(card) + defense_bonus * defensive_amount(card)
+
+
+# Return the defensive amount on a card.
+def defensive_amount(card: Card) -> int:
+    return sum(effect.amount for effect in card.effects if effect.primitive_id in {"block", "ward", "weak"})
+
+
+# Return approximate immediate HP damage from a card.
+def immediate_hp_damage(actor: PlayerState, target: PlayerState, card: Card) -> int:
+    return sum(effect_hp_damage(actor, target, card, index) for index, _ in enumerate(card.effects))
+
+
+# Return approximate immediate HP damage from one effect.
+def effect_hp_damage(actor: PlayerState, target: PlayerState, card: Card, effect_index: int) -> int:
+    effect = card.effects[effect_index]
+    if effect.primitive_id == "deal":
+        return hp_damage_after_defense(actor, target, effect.amount)
+    if effect.primitive_id == "multi_hit":
+        return sum(hp_damage_after_defense(actor, target, effect.amount) for _ in range(effect.hits))
+    if effect.primitive_id == "conditional":
+        return hp_damage_after_defense(actor, target, conditional_damage(target, effect.amount))
+    if effect.primitive_id == "scaling":
+        if effect.condition == "shield_charge":
+            return hp_damage_after_defense(actor, target, effect.amount + actor.shield_charge)
+        return hp_damage_after_defense(actor, target, effect.amount + actor.cards_played_this_turn + 1)
+    return 0
+
+
+# Return HP damage after current weak, vulnerable, ward, and block.
+def hp_damage_after_defense(actor: PlayerState, target: PlayerState, amount: int) -> int:
+    damage = max(0, amount - actor.weak)
+    if damage == 0 or target.ward > 0:
+        return 0
+    damage += target.vulnerable
+    return max(0, damage - target.block)
+
+
+# Return a primitive's rough tactical score.
+def effect_score(primitive_id: str, amount: int, hits: int) -> int:
+    if primitive_id in {"deal", "conditional", "scaling"}:
+        return amount * 2
+    if primitive_id == "multi_hit":
+        return amount * hits * 2
+    if primitive_id in {"block", "ward", "weak"}:
+        return amount
+    if primitive_id in {"burn", "bomb", "vulnerable"}:
+        return amount * 2
+    if primitive_id in {"draw", "energy", "initiative"}:
+        return amount + 2
+    return 0
+
+
+# Play cards for one actor until they pass or cannot act.
+def play_turn(state: DuelState, actor: PlayerState, choose: Chooser, print_fn: Printer) -> None:
+    while playable_indexes(actor):
+        choice = choose(state, actor)
+        if choice is None:
+            expire_energy(actor)
+            print_fn(f"{actor.name} passes.")
+            return
+        card = play_card_from_hand(state, actor, choice)
+        print_fn(f"{actor.name} plays {card.name}: {card.rules_text()}")
+        if winner(state):
+            expire_energy(actor)
+            return
+    expire_energy(actor)
+    print_fn(f"{actor.name} has no playable cards.")
+
+
+# Expire unused turn energy.
+def expire_energy(player: PlayerState) -> None:
+    player.energy = 0
+
+
+# Print both sides of the duel state.
+def print_state(state: DuelState, print_fn: Printer) -> None:
+    print_fn(player_line(state.player))
+    print_fn(player_line(state.enemy))
+
+
+# Run a tiny terminal duel between a human and the assistant policy.
+def run_text_duel(
+    player_deck: tuple[Card, ...] | None = None,
+    enemy_deck: tuple[Card, ...] | None = None,
+    prompt: Prompt = input,
+    print_fn: Printer = print,
+    rng: Random | None = None,
+    max_rounds: int = MAX_ROUNDS,
+    boss_client: BossClientLike | None = None,
+) -> str:
+    from boss import boss_chooser
+
+    randomizer = rng or Random()
+    state = DuelState(
+        create_player("You", shuffled_deck(player_deck or demo_deck("fire", "dark fantasy"), randomizer)),
+        create_player("Enemy", shuffled_deck(enemy_deck or demo_deck("earth", "dark fantasy"), randomizer)),
+    )
+    draw_cards(state.player, OPENING_HAND_SIZE)
+    draw_cards(state.enemy, OPENING_HAND_SIZE)
+    human_choice = prompt_human_choice(prompt, print_fn)
+    enemy_choice = boss_chooser(boss_client, choose_enemy_card)
+    print_state(state, print_fn)
+    while not winner(state) and state.round_number < max_rounds:
+        order = start_round(state, randomizer)
+        print_fn(f"Round {state.round_number}: {' then '.join(order)}")
+        for name in order:
+            if winner(state):
+                break
+            actor = named_player(state, name)
+            chooser = human_choice if actor is state.player else enemy_choice
+            play_turn(state, actor, chooser, print_fn)
+        print_state(state, print_fn)
+    result = winner(state) or "no winner"
+    print_fn(f"Winner: {result}")
+    return result
+
+
+# Return a shuffled copy of a deck.
+def shuffled_deck(deck: tuple[Card, ...], rng: Random) -> tuple[Card, ...]:
+    cards = list(deck)
+    rng.shuffle(cards)
+    return tuple(cards)
+
+
+# Start an interactive terminal duel.
+def main() -> None:  # pragma: no cover
+    from clients import boss_client_from_env, card_client_from_env
+
+    rng = Random()
+    client = card_client_from_env() or CodexCardClient(cwd=".")
+    player_deck = draft_player_deck(client, "fire", "dark fantasy", rng=rng)
+    enemy_deck = draft_enemy_deck(client, "earth", "dark fantasy", rng=rng)
+    run_text_duel(player_deck=player_deck, enemy_deck=enemy_deck, rng=rng, boss_client=boss_client_from_env())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

primitives.py

@@ -0,0 +1,124 @@
+from dataclasses import dataclass
+from typing import Literal
+
+PrimitiveId = Literal[
+    "deal",
+    "burn",
+    "bomb",
+    "block",
+    "ward",
+    "weak",
+    "draw",
+    "energy",
+    "initiative",
+    "multi_hit",
+    "vulnerable",
+    "conditional",
+    "scaling",
+]
+School = Literal["fire", "ice", "earth"]
+
+
+@dataclass(frozen=True)
+class PrimitiveSpec:
+    id: PrimitiveId
+    name: str
+    category: str
+    schools: frozenset[School]
+
+
+@dataclass(frozen=True)
+class Effect:
+    primitive_id: PrimitiveId
+    amount: int = 0
+    duration: int = 0
+    delay: int = 0
+    hits: int = 1
+    condition: str = ""
+
+
+PRIMITIVES: dict[PrimitiveId, PrimitiveSpec] = {
+    "deal": PrimitiveSpec("deal", "Deal", "damage", frozenset(("fire",))),
+    "burn": PrimitiveSpec("burn", "Burn", "damage", frozenset(("fire",))),
+    "bomb": PrimitiveSpec("bomb", "Bomb", "damage", frozenset(("fire",))),
+    "block": PrimitiveSpec("block", "Block", "defense", frozenset(("earth",))),
+    "ward": PrimitiveSpec("ward", "Ward", "defense", frozenset(("earth",))),
+    "weak": PrimitiveSpec("weak", "Weak", "defense", frozenset()),
+    "draw": PrimitiveSpec("draw", "Draw", "tempo", frozenset()),
+    "energy": PrimitiveSpec("energy", "Energy", "tempo", frozenset()),
+    "initiative": PrimitiveSpec("initiative", "Initiative", "tempo", frozenset(("ice",))),
+    "multi_hit": PrimitiveSpec("multi_hit", "Multi-hit", "combo", frozenset(("ice",))),
+    "vulnerable": PrimitiveSpec("vulnerable", "Vulnerable", "combo", frozenset(("ice",))),
+    "conditional": PrimitiveSpec("conditional", "Conditional", "combo", frozenset(("ice", "earth"))),
+    "scaling": PrimitiveSpec("scaling", "Scaling", "combo", frozenset(("fire", "earth"))),
+}
+
+SCHOOL_PRIMITIVES: dict[School, tuple[PrimitiveId, ...]] = {
+    "fire": ("deal", "burn", "bomb", "scaling", "draw", "energy", "block", "conditional"),
+    "ice": ("deal", "initiative", "vulnerable", "multi_hit", "conditional", "draw", "energy", "block"),
+    "earth": ("deal", "ward", "block", "weak", "scaling", "conditional", "draw", "energy"),
+}
+
+SCHOOL_BIAS: dict[School, str] = {
+    "fire": "Prefer immediate Deal first, then Burn/Scaling, then occasional Bomb, Draw, Energy, or Block.",
+    "ice": "Prefer tempo pressure through Deal, Initiative, Vulnerable, Multi-hit, and Conditional, with occasional Draw or Block.",
+    "earth": "Prefer Block and Ward to bank shield charge, then Scaling to release that charge as burst damage. Add some Deal, Weak, and Draw.",
+}
+
+
+# Return all primitive identifiers in canonical order.
+def primitive_ids() -> tuple[PrimitiveId, ...]:
+    return tuple(PRIMITIVES)
+
+
+# Return a primitive spec by id.
+def get_primitive(primitive_id: PrimitiveId) -> PrimitiveSpec:
+    return PRIMITIVES[primitive_id]
+
+
+# Return the primitive ids available to a school.
+def school_primitives(school: School) -> tuple[PrimitiveId, ...]:
+    return SCHOOL_PRIMITIVES[school]
+
+
+# Return whether a primitive belongs in a school's draft pool.
+def primitive_allowed_for_school(primitive_id: PrimitiveId, school: School) -> bool:
+    return primitive_id in SCHOOL_PRIMITIVES[school]
+
+
+# Return a school's generation bias.
+def school_bias(school: School) -> str:
+    return SCHOOL_BIAS[school]
+
+
+# Render a costed effect into fixed card text.
+def render_effect(effect: Effect) -> str:
+    match effect.primitive_id:
+        case "deal":
+            return f"Deal {effect.amount} damage."
+        case "burn":
+            return f"Burn {effect.amount} damage for {effect.duration} turns."
+        case "bomb":
+            return f"Bomb: deal {effect.amount} damage in {effect.delay} turns."
+        case "block":
+            return f"Gain {effect.amount} block until your next turn."
+        case "ward":
+            return f"Gain {effect.amount} ward."
+        case "weak":
+            return f"Opponent deals {effect.amount} less damage until your next turn."
+        case "draw":
+            return f"Draw {effect.amount} card{'s' if effect.amount != 1 else ''}."
+        case "energy":
+            return f"Gain {effect.amount} energy this turn."
+        case "initiative":
+            return "Opponent acts second next round."
+        case "multi_hit":
+            return f"Deal {effect.amount} damage {effect.hits} times."
+        case "vulnerable":
+            return f"Opponent takes {effect.amount} more damage for {effect.duration} turns."
+        case "conditional":
+            return f"Deal up to {effect.amount} damage based on opponent's missing HP."
+        case "scaling":
+            if effect.condition == "shield_charge":
+                return f"Deal {effect.amount} damage plus your banked shield charge, then empty it."
+            return f"Deal {effect.amount} damage plus cards played this turn."

pyproject.toml

@@ -0,0 +1,10 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["ai_runtime", "boss", "budget", "clients", "draft", "game", "generator", "local_llm", "play", "primitives"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 90

tests/test_ai_runtime.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from ai_runtime import chat_endpoint, local_ai_env, minicpm_server_command, start_minicpm_server
+
+
+# Verify local chat endpoints use OpenAI-compatible paths.
+def test_chat_endpoint() -> None:
+    assert chat_endpoint(8090) == "http://127.0.0.1:8090/v1/chat/completions"
+
+
+# Verify the MiniCPM server command points llama.cpp at the GGUF model.
+def test_minicpm_server_command() -> None:
+    command = minicpm_server_command(Path("mini.gguf"), 9000)
+    assert command[:3] == ("llama-server", "--model", "mini.gguf")
+    assert "--port" in command
+    assert "9000" in command
+    assert "--n-gpu-layers" in command
+
+
+# Verify local AI env forces MiniCPM card generation and Nemotron boss play.
+def test_local_ai_env(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_CARD_ENDPOINT", "old")
+    env = local_ai_env(9001)
+    assert env["TABRAS_CARD_BACKEND"] == "llamacpp"
+    assert env["TABRAS_CARD_ENDPOINT"] == "http://127.0.0.1:9001/v1/chat/completions"
+    assert env["TABRAS_AI_BOSS"] == "1"
+    assert env["TABRAS_BOSS_BACKEND"] == "mlx"
+    assert "Nemotron" in env["TABRAS_BOSS_MODEL"]
+
+
+# Verify starting MiniCPM fails early when the GGUF is absent.
+def test_start_minicpm_server_requires_model(tmp_path) -> None:
+    missing = tmp_path / "missing.gguf"
+    try:
+        start_minicpm_server(missing, 9002)
+    except FileNotFoundError as error:
+        assert str(missing) in str(error)
+    else:
+        raise AssertionError("missing MiniCPM model did not fail")

tests/test_boss.py

@@ -0,0 +1,187 @@
+from typing import Any
+
+from boss import (
+    HeuristicBossClient,
+    NemotronBossClient,
+    affordable_indexes,
+    boss_chooser,
+    boss_indexes,
+    boss_payload,
+    boss_prompt,
+    boss_system_prompt,
+    hand_payload,
+    parse_card_indexes,
+    player_payload,
+    safe_boss_indexes,
+)
+from budget import Card
+from game import DuelState, create_player
+from play import run_text_duel
+from primitives import Effect
+
+
+class FakeBossClient:
+    # Initialize the fake boss client with a fixed raw response.
+    def __init__(self, raw: dict[str, Any]) -> None:
+        self.raw = raw
+        self.payload: dict[str, Any] | None = None
+
+    # Capture the payload and return a fixed boss response.
+    def choose_cards(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self.payload = payload
+        return self.raw
+
+
+class FakeChat:
+    # Initialize the fake chat client with fixed text.
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.calls: list[tuple[str, str]] = []
+
+    # Capture prompts and return fixed text.
+    def complete(self, system: str, user: str) -> str:
+        self.calls.append((system, user))
+        return self.text
+
+
+class BrokenBossClient:
+    # Raise like a malformed model response.
+    def choose_cards(self, payload: dict[str, Any]) -> dict[str, Any]:
+        del payload
+        raise ValueError("bad model output")
+
+
+# Build one boss test card.
+def make_card(name: str, cost: int, effect: Effect) -> Card:
+    return Card(name, cost, "fire", "wuxia", (effect,))
+
+
+# Build one boss test duel.
+def make_duel() -> DuelState:
+    return DuelState(create_player("You", []), create_player("Enemy", []))
+
+
+# Verify boss payload exposes visible state.
+def test_boss_payload() -> None:
+    state = make_duel()
+    state.enemy.energy = 3
+    state.enemy.shield_charge = 2
+    state.enemy.hand = [make_card("Strike", 1, Effect("deal", amount=2))]
+    payload = boss_payload(state, state.enemy)
+    assert payload["actor"]["shield_charge"] == 2
+    assert payload["opponent"]["name"] == "You"
+    assert payload["hand"][0]["rules_text"] == "Deal 2 damage."
+
+
+# Verify heuristic boss client returns an empty model choice.
+def test_heuristic_boss_client() -> None:
+    assert HeuristicBossClient().choose_cards({}) == {"card_indexes": []}
+
+
+# Verify boss prompts ask for strict JSON and playable indexes.
+def test_boss_prompts() -> None:
+    payload = {"playable_indexes": (0,), "actor": {}, "opponent": {}, "hand": []}
+    assert "strict JSON" in boss_system_prompt()
+    assert "playable_indexes" in boss_prompt(payload)
+
+
+# Verify Nemotron boss client uses local chat completions.
+def test_nemotron_boss_client() -> None:
+    chat = FakeChat('{"card_indexes": [0], "reason": "lethal"}')
+    client = NemotronBossClient(chat)  # type: ignore[arg-type]
+    assert client.choose_cards({"playable_indexes": [0]})["card_indexes"] == [0]
+    assert "strict JSON" in chat.calls[0][0]
+    assert "card_indexes" in chat.calls[0][1]
+
+
+# Verify player payload includes zone counts.
+def test_player_payload() -> None:
+    player = create_player("Enemy", [make_card("Deck", 1, Effect("deal", amount=1))])
+    player.hand = [make_card("Hand", 1, Effect("deal", amount=1))]
+    player.discard = [make_card("Discard", 1, Effect("deal", amount=1))]
+    assert player_payload(player)["deck_count"] == 1
+    assert player_payload(player)["hand_count"] == 1
+    assert player_payload(player)["discard_count"] == 1
+
+
+# Verify hand payload indexes playable cards.
+def test_hand_payload() -> None:
+    player = create_player("Enemy", [])
+    player.hand = [make_card("Strike", 1, Effect("deal", amount=2))]
+    assert hand_payload(player) == [{"index": 0, "name": "Strike", "cost": 1, "rules_text": "Deal 2 damage."}]
+
+
+# Verify model indexes parse defensively.
+def test_parse_card_indexes() -> None:
+    assert parse_card_indexes({"card_indexes": [2, "x", 0]}) == (2, 0)
+    assert parse_card_indexes({"card_indexes": "bad"}) == ()
+    assert parse_card_indexes({}) == ()
+
+
+# Verify affordability validation preserves sequence.
+def test_affordable_indexes() -> None:
+    actor = create_player("Enemy", [])
+    actor.energy = 3
+    actor.hand = [
+        make_card("One", 1, Effect("deal", amount=1)),
+        make_card("Three", 3, Effect("deal", amount=1)),
+        make_card("Two", 2, Effect("deal", amount=1)),
+    ]
+    assert affordable_indexes(actor, (2, 0, 1, 2, 9)) == (2, 0)
+
+
+# Verify boss indexes go through payload and validation.
+def test_boss_indexes() -> None:
+    state = make_duel()
+    state.enemy.energy = 1
+    state.enemy.hand = [make_card("Strike", 1, Effect("deal", amount=2))]
+    client = FakeBossClient({"card_indexes": [0]})
+    assert boss_indexes(client, state, state.enemy) == (0,)
+    assert client.payload is not None
+    assert client.payload["actor"]["name"] == "Enemy"
+
+
+# Verify boss index safety converts model failures to no choice.
+def test_safe_boss_indexes_handles_model_failure() -> None:
+    state = make_duel()
+    assert safe_boss_indexes(BrokenBossClient(), state, state.enemy) == ()
+
+
+# Verify boss chooser falls back when model output is invalid.
+def test_boss_chooser_falls_back() -> None:
+    state = make_duel()
+    state.enemy.energy = 1
+    state.enemy.hand = [make_card("Strike", 1, Effect("deal", amount=2))]
+    chooser = boss_chooser(FakeBossClient({"card_indexes": [9]}))
+    assert chooser(state, state.enemy) == 0
+
+
+# Verify boss chooser falls back when the model fails.
+def test_boss_chooser_falls_back_on_model_failure() -> None:
+    state = make_duel()
+    state.enemy.energy = 1
+    state.enemy.hand = [make_card("Strike", 1, Effect("deal", amount=2))]
+    chooser = boss_chooser(BrokenBossClient())
+    assert chooser(state, state.enemy) == 0
+
+
+# Verify boss chooser uses a valid model card first.
+def test_boss_chooser_uses_model_card() -> None:
+    state = make_duel()
+    state.enemy.energy = 2
+    state.enemy.hand = [
+        make_card("A", 1, Effect("deal", amount=1)),
+        make_card("B", 2, Effect("block", amount=5)),
+    ]
+    chooser = boss_chooser(FakeBossClient({"card_indexes": [0]}))
+    assert chooser(state, state.enemy) == 0
+
+
+# Verify run_text_duel can use a boss client for enemy turns.
+def test_run_text_duel_uses_boss_client() -> None:
+    outputs: list[str] = []
+    player_deck = tuple(make_card("Wait", 5, Effect("block", amount=1)) for _ in range(4))
+    enemy_deck = tuple(make_card("Strike", 1, Effect("deal", amount=25)) for _ in range(4))
+    result = run_text_duel(player_deck, enemy_deck, lambda _: "pass", outputs.append, max_rounds=1, boss_client=FakeBossClient({"card_indexes": [0]}))
+    assert result == "Enemy"
+    assert any("Enemy plays Strike" in line for line in outputs)

tests/test_budget.py

@@ -0,0 +1,95 @@
+from random import Random
+
+import pytest
+
+from budget import CardSpec, EffectPlan, budget_for_energy, cost_card, cost_effect, cost_effects, miracle_budget
+
+
+class MaxRoll:
+    # Return the largest requested miracle multiplier.
+    def randint(self, low: int, high: int) -> int:
+        assert (low, high) == (1, 3)
+        return high
+
+
+# Verify energy cost maps directly to point budget.
+def test_budget_for_energy_accepts_locked_range() -> None:
+    assert [budget_for_energy(cost) for cost in range(1, 6)] == [1, 2, 3, 4, 5]
+    with pytest.raises(ValueError, match="card cost"):
+        budget_for_energy(0)
+    with pytest.raises(ValueError, match="card cost"):
+        budget_for_energy(6)
+
+
+# Verify miracle budgets are high variance but hard capped.
+def test_miracle_budget_is_capped() -> None:
+    assert miracle_budget(5, MaxRoll()) == 8  # type: ignore[arg-type]
+    assert miracle_budget(2, Random(1)) <= 6
+
+
+# Verify model-selected shapes become engine-owned numbers.
+def test_cost_card_assigns_numbers_from_budget() -> None:
+    spec = CardSpec("Cinder", 3, "fire", "wuxia", (EffectPlan("deal"),), flavor="Hot.")
+    card = cost_card(spec)
+    assert card.effects[0].amount == 6
+    assert card.rules_text() == "Deal 6 damage."
+
+
+# Verify Earth scaling releases shield charge.
+def test_earth_scaling_uses_shield_charge() -> None:
+    spec = CardSpec("Stone Burst", 3, "earth", "wuxia", (EffectPlan("scaling"),))
+    card = cost_card(spec)
+    assert card.effects[0].condition == "shield_charge"
+    assert card.rules_text() == "Deal 3 damage plus your banked shield charge, then empty it."
+
+
+# Verify weighted multi-effect cards spend the full budget.
+def test_cost_effects_split_weighted_budget() -> None:
+    effects = cost_effects(4, (EffectPlan("deal", weight=1), EffectPlan("burn", weight=3)))
+    assert effects[0].amount == 1
+    assert effects[1].amount == 2
+    assert effects[1].duration == 2
+
+
+# Verify low-cost cards cannot keep more effect clauses than they can fund.
+def test_cost_effects_trims_overstuffed_plans() -> None:
+    effects = cost_effects(2, (EffectPlan("deal"), EffectPlan("burn"), EffectPlan("bomb")))
+    assert len(effects) == 2
+    assert [effect.primitive_id for effect in effects] == ["deal", "burn"]
+
+
+@pytest.mark.parametrize(
+    ("primitive_id", "points", "fields"),
+    (
+        ("deal", 2, {"amount": 4}),
+        ("burn", 4, {"amount": 4, "duration": 2}),
+        ("bomb", 4, {"amount": 8, "delay": 3}),
+        ("block", 2, {"amount": 6}),
+        ("ward", 2, {"amount": 2}),
+        ("weak", 2, {"amount": 4, "duration": 1}),
+        ("draw", 3, {"amount": 2}),
+        ("energy", 3, {"amount": 1}),
+        ("initiative", 2, {"duration": 1}),
+        ("multi_hit", 4, {"amount": 4, "hits": 3}),
+        ("vulnerable", 4, {"amount": 4, "duration": 2}),
+        ("conditional", 2, {"amount": 2, "condition": "opponent_below_half"}),
+        ("scaling", 2, {"amount": 2, "condition": "cards_played"}),
+    ),
+)
+# Verify every primitive has a costing rule.
+def test_cost_effect_rules(primitive_id: str, points: int, fields: dict[str, object]) -> None:
+    effect = cost_effect(primitive_id, points)  # type: ignore[arg-type]
+    for name, value in fields.items():
+        assert getattr(effect, name) == value
+
+
+# Verify invalid effect plans are rejected before costing.
+def test_cost_card_rejects_invalid_specs() -> None:
+    with pytest.raises(ValueError, match="at least one"):
+        cost_card(CardSpec("Blank", 1, "fire", "wuxia", ()))
+    with pytest.raises(ValueError, match="weight"):
+        cost_card(CardSpec("Bad", 1, "fire", "wuxia", (EffectPlan("deal", 0),)))
+    with pytest.raises(ValueError, match="not allowed"):
+        cost_card(CardSpec("Bad", 1, "ice", "wuxia", (EffectPlan("bomb"),)))
+    with pytest.raises(ValueError, match="positive"):
+        cost_effect("deal", 0)

tests/test_clients.py

@@ -0,0 +1,100 @@
+from clients import boss_client_from_env, card_client_from_env
+from boss import NemotronBossClient
+from generator import LlamaCppCardClient, MiniCPMCardClient
+from local_llm import LocalChatClient, LocalCompletionClient, nemotron_prompt
+
+
+class FakeChat:
+    # Complete one fake prompt.
+    def complete(self, system: str, user: str) -> str:
+        return "{}"
+
+
+# Verify card client is disabled without an endpoint.
+def test_card_client_from_env_disabled(monkeypatch) -> None:
+    monkeypatch.delenv("TABRAS_CARD_ENDPOINT", raising=False)
+    assert card_client_from_env() is None
+
+
+# Verify card client reads endpoint environment.
+def test_card_client_from_env(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_CARD_ENDPOINT", "http://cards")
+    monkeypatch.setenv("TABRAS_CARD_MODEL", "mini")
+    client = card_client_from_env()
+    assert isinstance(client, MiniCPMCardClient)
+    assert client.chat.endpoint == "http://cards"
+    assert client.chat.model == "mini"
+
+
+# Verify card client can use the direct MiniCPM Transformers backend.
+def test_card_client_from_env_transformers(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_CARD_BACKEND", "transformers")
+    monkeypatch.setenv("TABRAS_CARD_MODEL", "mini-local")
+    monkeypatch.setattr("clients.MiniCPMTransformersChatClient.load", lambda model_path: FakeChat())
+    client = card_client_from_env()
+    assert isinstance(client, MiniCPMCardClient)
+    assert isinstance(client.chat, FakeChat)
+
+
+# Verify card client can use a llama.cpp MiniCPM backend.
+def test_card_client_from_env_llamacpp(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_CARD_BACKEND", "llamacpp")
+    monkeypatch.setenv("TABRAS_CARD_ENDPOINT", "http://cards")
+    monkeypatch.setenv("TABRAS_CARD_MODEL", "mini-q4")
+    client = card_client_from_env()
+    assert isinstance(client, LlamaCppCardClient)
+    assert isinstance(client.chat, LocalChatClient)
+    assert client.chat.endpoint == "http://cards"
+    assert client.chat.model == "mini-q4"
+    assert client.chat.max_tokens == 220
+
+
+# Verify boss client is disabled unless enabled.
+def test_boss_client_from_env_disabled(monkeypatch) -> None:
+    monkeypatch.delenv("TABRAS_AI_BOSS", raising=False)
+    assert boss_client_from_env() is None
+
+
+# Verify boss client reads endpoint environment.
+def test_boss_client_from_env(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_AI_BOSS", "1")
+    monkeypatch.setenv("TABRAS_BOSS_ENDPOINT", "http://boss")
+    monkeypatch.setenv("TABRAS_BOSS_MODEL", "nemotron")
+    client = boss_client_from_env()
+    assert isinstance(client, NemotronBossClient)
+    assert client.chat.endpoint == "http://boss"
+    assert client.chat.model == "nemotron"
+
+
+# Verify boss client can use a Nemotron formatted completion endpoint.
+def test_boss_client_from_env_completion(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_AI_BOSS", "1")
+    monkeypatch.setenv("TABRAS_BOSS_BACKEND", "completion")
+    monkeypatch.setenv("TABRAS_BOSS_ENDPOINT", "http://boss-completion")
+    client = boss_client_from_env()
+    assert isinstance(client, NemotronBossClient)
+    assert isinstance(client.chat, LocalCompletionClient)
+    assert client.chat.endpoint == "http://boss-completion"
+    assert client.chat.prompt_template is nemotron_prompt
+
+
+# Verify boss client can use the direct Nemotron Transformers backend.
+def test_boss_client_from_env_transformers(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_AI_BOSS", "1")
+    monkeypatch.setenv("TABRAS_BOSS_BACKEND", "transformers")
+    monkeypatch.setenv("TABRAS_BOSS_MODEL", "nemotron-local")
+    monkeypatch.setattr("clients.NemotronTransformersChatClient.load", lambda *_args, **_kwargs: FakeChat())
+    client = boss_client_from_env()
+    assert isinstance(client, NemotronBossClient)
+    assert isinstance(client.chat, FakeChat)
+
+
+# Verify boss client can use a quantized MLX backend.
+def test_boss_client_from_env_mlx(monkeypatch) -> None:
+    monkeypatch.setenv("TABRAS_AI_BOSS", "1")
+    monkeypatch.setenv("TABRAS_BOSS_BACKEND", "mlx")
+    monkeypatch.setenv("TABRAS_BOSS_MODEL", "nemotron-mlx")
+    monkeypatch.setattr("clients.MLXChatClient.load", lambda *_args, **_kwargs: FakeChat())
+    client = boss_client_from_env()
+    assert isinstance(client, NemotronBossClient)
+    assert isinstance(client.chat, FakeChat)

tests/test_draft.py

@@ -0,0 +1,108 @@
+import pytest
+from random import Random
+
+from draft import backbone_deck, draft_anchor_indexes, draft_deck, draft_deck_from_packs, draft_order, validated_pack_choice
+
+
+class DraftClient:
+    # Initialize call tracking for draft generation.
+    def __init__(self) -> None:
+        self.calls = 0
+        self.deck_sizes: list[int] = []
+
+    # Return one legal earth card and record deck-aware call order.
+    def create_card(self, payload: dict[str, object]) -> dict[str, object]:
+        self.calls += 1
+        self.deck_sizes.append(len(payload["current_deck"]))  # type: ignore[arg-type]
+        return {"name": f"Ward {self.calls}", "effects": [{"primitive_id": "ward"}]}
+
+
+class DraftPackClient:
+    # Initialize call tracking for pack generation.
+    def __init__(self) -> None:
+        self.calls = 0
+        self.deck_sizes: list[int] = []
+        self.anchor_sizes: list[int] = []
+
+    # Return one legal earth pack and record deck-aware call order.
+    def create_pack(self, payload: dict[str, object]) -> dict[str, object]:
+        self.calls += 1
+        self.deck_sizes.append(len(payload["current_deck"]))  # type: ignore[arg-type]
+        self.anchor_sizes.append(len(payload["draft_anchors"]))  # type: ignore[arg-type]
+        return {
+            "cards": [
+                {"name": f"Ward {self.calls}A", "effects": [{"primitive_id": "ward"}]},
+                {"name": f"Ward {self.calls}B", "effects": [{"primitive_id": "block"}]},
+                {"name": f"Ward {self.calls}C", "effects": [{"primitive_id": "conditional"}]},
+            ]
+        }
+
+
+# Verify backbone decks are six fixed text cards.
+def test_backbone_deck_has_standard_cards() -> None:
+    deck = backbone_deck("ice", "cyberpunk")
+    assert len(deck) == 6
+    assert deck[0].name == "Attack (weak)"
+    assert deck[0].school == "ice"
+    assert deck[5].rules_text() == "Draw 1 card."
+
+
+# Verify synergy drafting makes nine deck-aware model calls.
+def test_draft_deck_adds_nine_synergy_cards() -> None:
+    client = DraftClient()
+    deck = draft_deck(client, "earth", "dark fantasy", (1, 2, 3, 4, 5, 1, 2, 3, 4))
+    assert len(deck) == 15
+    assert client.deck_sizes == [6, 7, 8, 9, 10, 11, 12, 13, 14]
+    assert deck[-1].name == "Ward 9"
+
+
+# Verify pack drafting adds the selected candidate from each pack.
+def test_draft_deck_from_packs_adds_selected_cards() -> None:
+    client = DraftPackClient()
+    choices: list[int] = []
+
+    # Always choose the second card in the pack.
+    def choose_index(current_deck: tuple[object, ...], pack: tuple[object, ...]) -> int:
+        assert len(pack) == 3
+        choices.append(len(current_deck))
+        return 1
+
+    deck = draft_deck_from_packs(client, "earth", "dark fantasy", (1, 2, 3, 4, 5, 1, 2, 3, 4), choose_index, rng=Random(0))
+    assert len(deck) == 15
+    assert client.deck_sizes == [6, 7, 8, 9, 10, 11, 12, 13, 14]
+    assert client.anchor_sizes[:2] == [0, 1]
+    assert client.anchor_sizes[2:] == [2, 2, 2, 2, 2, 2, 2]
+    assert choices == [6, 7, 8, 9, 10, 11, 12, 13, 14]
+    assert deck[-1].name == "Ward 9B"
+
+
+# Verify anchor indexes are two random synergy positions.
+def test_draft_anchor_indexes() -> None:
+    anchors = draft_anchor_indexes(9, Random(0))
+    assert len(anchors) == 2
+    assert anchors <= set(range(9))
+    with pytest.raises(ValueError, match="at least two"):
+        draft_anchor_indexes(1, Random(0))
+
+
+# Verify draft order drafts anchors before remaining cards.
+def test_draft_order_starts_with_anchors() -> None:
+    assert draft_order(5, frozenset((3, 1))) == (1, 3, 0, 2, 4)
+
+
+# Verify draft rejects incomplete synergy cost schedules.
+def test_draft_deck_requires_nine_costs() -> None:
+    with pytest.raises(ValueError, match="exactly nine"):
+        draft_deck(DraftClient(), "earth", "dark fantasy", (1,))
+    with pytest.raises(ValueError, match="exactly nine"):
+        draft_deck_from_packs(DraftPackClient(), "earth", "dark fantasy", (1,), lambda _, __: 0)
+
+
+# Verify draft pack choices must point into the pack.
+def test_validated_pack_choice_rejects_bad_index() -> None:
+    pack = backbone_deck("earth", "dark fantasy")[:3]
+    assert validated_pack_choice(2, pack) == 2
+    with pytest.raises(ValueError, match="outside"):
+        validated_pack_choice(3, pack)
+    with pytest.raises(ValueError, match="outside"):
+        validated_pack_choice(-1, pack)

tests/test_game.py

@@ -0,0 +1,254 @@
+from random import Random
+
+import pytest
+
+from budget import Card
+from game import (
+    DuelState,
+    PendingEffect,
+    advance_pending,
+    begin_turn,
+    create_player,
+    deal_damage,
+    draw_cards,
+    named_player,
+    play_card,
+    play_card_from_hand,
+    round_order,
+    start_round,
+    winner,
+)
+from primitives import Effect
+
+
+# Build a test card with fixed effects.
+def make_card(cost: int, *effects: Effect) -> Card:
+    return Card("Test", cost, "fire", "wuxia", tuple(effects))
+
+
+# Build a duel state with empty decks.
+def make_duel() -> DuelState:
+    return DuelState(create_player("player", []), create_player("enemy", []))
+
+
+# Verify draw applies escalating fatigue when the deck is empty.
+def test_draw_cards_applies_fatigue() -> None:
+    player = create_player("player", [make_card(1, Effect("deal", amount=2))])
+    draw_cards(player, 3)
+    assert len(player.hand) == 1
+    assert player.hp == 17
+    assert player.fatigue == 3
+
+
+# Verify damage resolves through block before HP.
+def test_damage_uses_block() -> None:
+    state = make_duel()
+    state.enemy.block = 3
+    dealt = deal_damage(state.player, state.enemy, 5)
+    assert dealt == 2
+    assert state.enemy.block == 0
+    assert state.enemy.hp == 18
+    assert state.enemy.shield_charge == 1
+
+
+# Verify ward absorbs chip and breaks on a single threshold hit.
+def test_ward_bubble_rule() -> None:
+    state = make_duel()
+    state.enemy.ward = 4
+    assert deal_damage(state.player, state.enemy, 3) == 0
+    assert state.enemy.ward == 4
+    assert state.enemy.hp == 20
+    assert state.enemy.shield_charge == 0
+    assert deal_damage(state.player, state.enemy, 4) == 0
+    assert state.enemy.ward == 0
+    assert state.enemy.hp == 20
+    assert state.enemy.shield_charge == 0
+
+
+# Verify weak and vulnerable modify outgoing damage deterministically.
+def test_weak_and_vulnerable_modify_damage() -> None:
+    state = make_duel()
+    state.player.weak = 2
+    state.enemy.vulnerable = 3
+    assert deal_damage(state.player, state.enemy, 5) == 6
+    assert state.enemy.hp == 14
+    state.player.weak = 10
+    assert deal_damage(state.player, state.enemy, 5) == 0
+
+
+# Verify playing a card spends energy and resolves effects.
+def test_play_card_spends_energy_and_resolves_effects() -> None:
+    state = make_duel()
+    state.player.energy = 3
+    play_card(state, state.player, make_card(2, Effect("deal", amount=4), Effect("block", amount=3)))
+    assert state.player.energy == 1
+    assert state.player.block == 3
+    assert state.enemy.hp == 16
+    with pytest.raises(ValueError, match="not enough"):
+        play_card(state, state.player, make_card(2, Effect("deal", amount=2)))
+
+
+# Verify playing from hand removes the card.
+def test_play_card_from_hand() -> None:
+    state = make_duel()
+    state.player.energy = 1
+    state.player.hand.append(make_card(1, Effect("deal", amount=2)))
+    card = play_card_from_hand(state, state.player, 0)
+    assert card.name == "Test"
+    assert state.player.hand == []
+    assert state.enemy.hp == 18
+
+
+# Verify all non-damage card effects update state.
+def test_card_effects_update_state() -> None:
+    state = make_duel()
+    state.player.deck = [make_card(1, Effect("deal", amount=2))]
+    state.player.energy = 5
+    play_card(
+        state,
+        state.player,
+        make_card(
+            1,
+            Effect("ward", amount=2),
+            Effect("weak", amount=2, duration=1),
+            Effect("draw", amount=1),
+            Effect("energy", amount=2),
+            Effect("initiative"),
+            Effect("vulnerable", amount=1, duration=1),
+        ),
+    )
+    assert state.player.ward == 2
+    assert state.player.energy == 6
+    assert len(state.player.hand) == 1
+    assert state.enemy.weak == 2
+    assert state.enemy.vulnerable == 1
+    assert state.forced_second == "enemy"
+
+
+# Verify multi-hit chip cannot break ward.
+def test_multi_hit_chip_cannot_break_ward() -> None:
+    state = make_duel()
+    state.enemy.ward = 3
+    state.player.energy = 1
+    play_card(state, state.player, make_card(1, Effect("multi_hit", amount=2, hits=2)))
+    assert state.enemy.ward == 3
+    assert state.enemy.hp == 20
+
+
+# Verify conditional and scaling damage use current state.
+def test_conditional_and_scaling_damage() -> None:
+    state = make_duel()
+    state.enemy.hp = 10
+    state.player.energy = 2
+    play_card(state, state.player, make_card(1, Effect("conditional", amount=6), Effect("scaling", amount=1)))
+    assert state.enemy.hp == 5
+
+
+# Verify shield charge scaling releases absorbed damage as burst.
+def test_shield_charge_scaling_spends_charge() -> None:
+    state = make_duel()
+    state.player.shield_charge = 4
+    state.player.energy = 1
+    play_card(state, state.player, make_card(1, Effect("scaling", amount=2, condition="shield_charge")))
+    assert state.enemy.hp == 14
+    assert state.player.shield_charge == 0
+
+
+# Verify burn and bomb use the shared pending effect queue.
+def test_deferred_effects_advance_from_one_queue() -> None:
+    state = make_duel()
+    state.player.energy = 2
+    play_card(state, state.player, make_card(1, Effect("burn", amount=2, duration=2), Effect("bomb", amount=5, delay=1)))
+    assert len(state.pending) == 2
+    advance_pending(state)
+    assert state.enemy.hp == 20
+    advance_pending(state)
+    assert state.enemy.hp == 13
+    assert len(state.pending) == 1
+    advance_pending(state)
+    assert state.enemy.hp == 11
+    assert state.pending == []
+
+
+# Verify start_round refills energy, draws, ticks statuses, and returns order.
+def test_start_round_updates_both_players() -> None:
+    state = DuelState(
+        create_player("player", [make_card(1, Effect("deal", amount=2))]),
+        create_player("enemy", [make_card(1, Effect("deal", amount=2))]),
+    )
+    state.player.vulnerable = 2
+    state.player.vulnerable_turns = 1
+    order = start_round(state, Random(1))
+    assert order in (("player", "enemy"), ("enemy", "player"))
+    assert state.round_number == 1
+    assert state.player.energy == 1
+    assert state.player.vulnerable == 0
+    assert len(state.player.hand) == 1
+    assert len(state.enemy.hand) == 1
+
+
+# Verify multi-turn statuses decrement without clearing early.
+def test_begin_turn_keeps_multi_turn_statuses() -> None:
+    player = create_player("player", [])
+    player.vulnerable = 2
+    player.vulnerable_turns = 2
+    player.weak = 1
+    player.weak_turns = 2
+    begin_turn(player, 3)
+    assert player.vulnerable == 2
+    assert player.vulnerable_turns == 1
+    assert player.weak == 1
+    assert player.weak_turns == 1
+
+
+# Verify one-turn weak clears at turn start.
+def test_begin_turn_clears_one_turn_weak() -> None:
+    player = create_player("player", [])
+    player.weak = 3
+    player.weak_turns = 1
+    begin_turn(player, 2)
+    assert player.weak == 0
+    assert player.weak_turns == 0
+
+
+# Verify initiative forces the named side to act second once.
+def test_round_order_respects_forced_second_once() -> None:
+    state = make_duel()
+    state.forced_second = "enemy"
+    assert round_order(state, Random(1)) == ("player", "enemy")
+    assert state.forced_second is None
+    state.forced_second = "player"
+    assert round_order(state, Random(1)) == ("enemy", "player")
+
+
+# Verify conditional effects do nothing when their condition is false.
+def test_conditional_does_not_fire_above_half_hp() -> None:
+    state = make_duel()
+    state.player.energy = 1
+    play_card(state, state.player, make_card(1, Effect("conditional", amount=6)))
+    assert state.enemy.hp == 20
+
+
+# Verify an already-due bomb resolves directly from the pending queue.
+def test_due_bomb_resolves_from_pending_queue() -> None:
+    state = make_duel()
+    state.pending.append(PendingEffect("bomb", "player", "enemy", 5))
+    advance_pending(state)
+    assert state.enemy.hp == 15
+    assert state.pending == []
+
+
+# Verify named player lookup and winner states.
+def test_named_player_and_winner() -> None:
+    state = make_duel()
+    assert named_player(state, "player") is state.player
+    assert named_player(state, "enemy") is state.enemy
+    with pytest.raises(KeyError):
+        named_player(state, "missing")
+    assert winner(state) is None
+    state.enemy.hp = 0
+    assert winner(state) == "player"
+    state.player.hp = 0
+    assert winner(state) == "draw"
+    state.enemy.hp = 1
+    assert winner(state) == "enemy"

tests/test_generator.py

@@ -0,0 +1,541 @@
+from typing import Any
+import subprocess
+
+import pytest
+
+from budget import Card, CardSpec, EffectPlan, cost_card
+from generator import (
+    CodexCardClient,
+    LlamaCppCardClient,
+    MiniCPMCardClient,
+    balance_json_closers,
+    card_context,
+    codex_pack_prompt,
+    deck_summary,
+    draft_direction,
+    draft_need,
+    extract_json_object,
+    generate_card,
+    generate_pack,
+    generate_llamacpp_card,
+    generator_payload,
+    llamacpp_card_prompt,
+    llama_candidate_need,
+    llamacpp_retry_prompt,
+    normalize_card_response,
+    pack_payload,
+    parse_llamacpp_card_text,
+    parse_card_payload,
+    parse_effect_plan,
+    parse_pack_payload,
+    repair_llamacpp_card,
+    primitive_guidance,
+    school_identity,
+)
+from primitives import Effect
+
+
+class FakeClient:
+    # Initialize the fake client with a fixed raw response.
+    def __init__(self, raw: dict[str, Any]) -> None:
+        self.raw = raw
+        self.payload: dict[str, Any] | None = None
+
+    # Capture the payload and return a fixed model response.
+    def create_card(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self.payload = payload
+        return self.raw
+
+
+class FakePackClient:
+    # Initialize the fake pack client with a fixed raw response.
+    def __init__(self, raw: dict[str, Any]) -> None:
+        self.raw = raw
+        self.payload: dict[str, Any] | None = None
+
+    # Capture the payload and return a fixed model pack response.
+    def create_pack(self, payload: dict[str, Any]) -> dict[str, Any]:
+        self.payload = payload
+        return self.raw
+
+
+class FakeChat:
+    # Initialize the fake chat client with fixed text.
+    def __init__(self, text: str | list[str]) -> None:
+        self.responses = [text] if isinstance(text, str) else text
+        self.calls: list[tuple[str, str]] = []
+
+    # Capture prompts and return fixed text.
+    def complete(self, system: str, user: str) -> str:
+        self.calls.append((system, user))
+        return self.responses[min(len(self.calls) - 1, len(self.responses) - 1)]
+
+
+# Build one card for generator context tests.
+def context_card() -> Card:
+    return cost_card(CardSpec("Spark", 1, "fire", "wuxia", (EffectPlan("deal"),)))
+
+
+# Build one direct card for summary tests.
+def direct_card(name: str, school: str, effects: tuple[Effect, ...]) -> Card:
+    return Card(name, 1, school, "wuxia", effects)  # type: ignore[arg-type]
+
+
+# Verify generator payload includes deck context and tool schema.
+def test_generator_payload_is_deck_aware() -> None:
+    payload = generator_payload("fire", "wuxia", [context_card()], [context_card()])
+    assert payload["allowed_primitives"] == ("deal", "burn", "bomb", "scaling", "draw", "energy", "block", "conditional")
+    assert payload["current_deck"][0]["rules_text"] == "Deal 2 damage."
+    assert payload["current_deck_summary"] == {"deal": 1}
+    assert payload["draft_anchors"][0]["name"] == "Spark"
+    assert payload["draft_anchor_summary"] == {"deal": 1}
+    assert "fast pressure" in payload["draft_direction"]
+    assert "races with direct pressure" in payload["school_identity"]
+    assert "burn for damage over turns" in payload["primitive_guidance"]
+    assert "Fire" in payload["draft_need"]
+    assert payload["tool_schema"]["name"] == "create_card"
+
+
+# Verify school identity text captures class mechanics.
+def test_school_identity() -> None:
+    assert "shield charge" in school_identity("earth")
+    assert "plain deal is secondary" in school_identity("earth")
+
+
+# Verify primitive guidance maps school ideas to primitive ids.
+def test_primitive_guidance() -> None:
+    assert "scaling to spend shield charge" in primitive_guidance("earth")
+
+
+# Verify draft direction is inferred from anchor primitives.
+def test_draft_direction() -> None:
+    anchors = [direct_card("Vuln", "ice", (Effect("vulnerable", amount=1),))]
+    assert "multi_hit" in draft_direction("ice", anchors)
+    assert "No anchor cards" in draft_direction("fire", [])
+
+
+# Verify llama.cpp candidate need points at missing scaling.
+def test_llama_candidate_need_prefers_missing_scaling() -> None:
+    payload = pack_payload("earth", "wuxia", [direct_card("Block", "earth", (Effect("block", amount=1),))], 2, 3)
+    assert "primitive_id scaling" in llama_candidate_need(payload, {})
+
+
+# Verify llama.cpp candidate need points at missing block.
+def test_llama_candidate_need_prefers_missing_block() -> None:
+    deck = [direct_card("Scale", "earth", (Effect("scaling", amount=1, condition="shield_charge"),))]
+    payload = pack_payload("earth", "wuxia", deck, 2, 3)
+    assert "primitive_id block" in llama_candidate_need(payload, {})
+
+
+# Verify llama.cpp candidate need points at missing multi-hit.
+def test_llama_candidate_need_prefers_missing_multi_hit() -> None:
+    deck = [direct_card("Vuln", "ice", (Effect("vulnerable", amount=1),))]
+    payload = pack_payload("ice", "wuxia", deck, 2, 3)
+    assert "primitive_id multi_hit" in llama_candidate_need(payload, {})
+
+
+# Verify llama.cpp candidate need points at missing initiative.
+def test_llama_candidate_need_prefers_missing_initiative() -> None:
+    deck = [
+        direct_card("Vuln A", "ice", (Effect("vulnerable", amount=1),)),
+        direct_card("Vuln B", "ice", (Effect("vulnerable", amount=1),)),
+        direct_card("Hit", "ice", (Effect("multi_hit", amount=1),)),
+    ]
+    payload = pack_payload("ice", "wuxia", deck, 2, 3)
+    assert "primitive_id initiative" in llama_candidate_need(payload, {})
+
+
+# Verify llama.cpp candidate need avoids repeated deal when covered.
+def test_llama_candidate_need_avoids_repeated_deal() -> None:
+    deck = [
+        direct_card("Block", "earth", (Effect("block", amount=1),)),
+        direct_card("Scaling", "earth", (Effect("scaling", amount=1, condition="shield_charge"),)),
+        direct_card("Deal A", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal B", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal C", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal D", "earth", (Effect("deal", amount=1),)),
+    ]
+    payload = pack_payload("earth", "wuxia", deck, 2, 3)
+    assert "primitive_id block" in llama_candidate_need(payload, {"deal": 1, "scaling": 1})
+
+
+# Verify llama.cpp retry prompt names exact primitive requirements.
+def test_llamacpp_retry_prompt_mentions_scaling() -> None:
+    payload = pack_payload("earth", "wuxia", [], 2, 3)
+    prompt = llamacpp_retry_prompt(payload, "explore primitive_id scaling")
+    assert "primitive_id exactly \"block\"" in prompt
+    assert "primitive_id exactly \"scaling\"" in prompt
+    assert "primitive_id exactly \"multi_hit\"" in prompt
+    assert "primitive_id exactly \"initiative\"" in prompt
+
+
+# Verify deck summary counts all costed card effects.
+def test_deck_summary_counts_effects() -> None:
+    deck = [
+        direct_card("Wall", "earth", (Effect("block", amount=3), Effect("ward", amount=1))),
+        direct_card("Payoff", "earth", (Effect("scaling", amount=2),)),
+    ]
+    assert deck_summary(deck) == {"block": 1, "scaling": 1, "ward": 1}
+
+
+# Verify Earth draft need shifts toward payoff after protection.
+def test_earth_draft_need_prefers_payoff_when_protected() -> None:
+    deck = [
+        direct_card("Ward A", "earth", (Effect("ward", amount=1),)),
+        direct_card("Ward B", "earth", (Effect("ward", amount=1),)),
+        direct_card("Block", "earth", (Effect("block", amount=1),)),
+        direct_card("Scaling", "earth", (Effect("scaling", amount=1, condition="shield_charge"),)),
+    ]
+    assert "payoff" in draft_need("earth", deck)
+
+
+# Verify Earth asks for scaling when block exists without payoff.
+def test_earth_draft_need_prefers_scaling_after_block() -> None:
+    deck = [direct_card("Block", "earth", (Effect("block", amount=1),))]
+    assert "scaling" in draft_need("earth", deck)
+
+
+# Verify Earth asks for block when payoff exists without enough charge.
+def test_earth_draft_need_prefers_block_after_scaling() -> None:
+    deck = [direct_card("Scale", "earth", (Effect("scaling", amount=1, condition="shield_charge"),))]
+    assert "add block" in draft_need("earth", deck)
+
+
+# Verify Earth stops asking for plain damage once deal is covered.
+def test_earth_draft_need_moves_away_from_deal() -> None:
+    deck = [
+        direct_card("Block", "earth", (Effect("block", amount=1),)),
+        direct_card("Scaling", "earth", (Effect("scaling", amount=1, condition="shield_charge"),)),
+        direct_card("Deal A", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal B", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal C", "earth", (Effect("deal", amount=1),)),
+        direct_card("Deal D", "earth", (Effect("deal", amount=1),)),
+    ]
+    assert "add block" in draft_need("earth", deck)
+
+
+# Verify Ice asks for multi-hit after vulnerability setup.
+def test_ice_draft_need_prefers_multi_hit_after_vulnerable() -> None:
+    deck = [direct_card("Vuln", "ice", (Effect("vulnerable", amount=1),))]
+    assert "multi_hit" in draft_need("ice", deck)
+
+
+# Verify Ice asks for initiative after setup and payoff exist.
+def test_ice_draft_need_prefers_initiative_after_setup_payoff() -> None:
+    deck = [
+        direct_card("Vuln A", "ice", (Effect("vulnerable", amount=1),)),
+        direct_card("Vuln B", "ice", (Effect("vulnerable", amount=1),)),
+        direct_card("Hit", "ice", (Effect("multi_hit", amount=1),)),
+    ]
+    assert "initiative" in draft_need("ice", deck)
+
+
+# Verify pack payload includes cost and requested pack size.
+def test_pack_payload_includes_draft_context() -> None:
+    payload = pack_payload("fire", "wuxia", [context_card()], cost=3, pack_size=3)
+    assert payload["cost"] == 3
+    assert payload["pack_size"] == 3
+    assert payload["pack_schema"]["required"] == ["cards"]
+
+
+# Verify card batch payload includes a cost schedule.
+def test_cards_payload_includes_cost_schedule() -> None:
+    from generator import cards_payload
+
+    payload = cards_payload("fire", "wuxia", [context_card()], (2, 3))
+    assert payload["costs"] == (2, 3)
+    assert payload["pack_size"] == 2
+    assert "immediate Deal" in payload["school_bias"]
+
+
+# Verify card context exposes compact fixed rules text.
+def test_card_context_is_compact() -> None:
+    assert card_context(context_card()) == {"name": "Spark", "cost": 1, "rules_text": "Deal 2 damage."}
+
+
+# Verify model-authored magnitudes are ignored by engine costing.
+def test_generate_card_ignores_model_numbers() -> None:
+    client = FakeClient(
+        {
+            "name": "Inferno Lie",
+            "flavor": "The model says 999.",
+            "art_prompt": "flame",
+            "effects": [{"primitive_id": "deal", "weight": 1, "amount": 999}],
+        }
+    )
+    card = generate_card(client, "fire", "wuxia", [context_card()], cost=2)
+    assert client.payload is not None
+    assert client.payload["current_deck"][0]["name"] == "Spark"
+    assert card.effects[0].amount == 4
+    assert "999" not in card.rules_text()
+
+
+# Verify pack generation costs every returned candidate.
+def test_generate_pack_returns_costed_candidates() -> None:
+    client = FakePackClient(
+        {
+            "cards": [
+                {"name": "A", "effects": [{"primitive_id": "deal"}]},
+                {"name": "B", "effects": [{"primitive_id": "burn"}]},
+                {"name": "C", "effects": [{"primitive_id": "bomb"}]},
+            ]
+        }
+    )
+    pack = generate_pack(client, "fire", "wuxia", [context_card()], cost=2)
+    assert client.payload is not None
+    assert client.payload["current_deck"][0]["name"] == "Spark"
+    assert [card.name for card in pack] == ["A", "B", "C"]
+    assert pack[0].rules_text() == "Deal 4 damage."
+
+
+# Verify multi-card generation costs cards against their own costs.
+def test_generate_cards_returns_costed_batch() -> None:
+    from generator import generate_cards
+
+    client = FakePackClient(
+        {
+            "cards": [
+                {"name": "A", "effects": [{"primitive_id": "deal"}]},
+                {"name": "B", "effects": [{"primitive_id": "burn"}]},
+            ]
+        }
+    )
+    cards = generate_cards(client, "fire", "wuxia", [context_card()], (2, 3))
+    assert [card.rules_text() for card in cards] == ["Deal 4 damage.", "Burn 3 damage for 2 turns."]
+
+
+# Verify multi-card generation rejects wrong-size output.
+def test_generate_cards_rejects_wrong_size() -> None:
+    from generator import generate_cards
+
+    client = FakePackClient({"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]})
+    with pytest.raises(ValueError, match="wrong size"):
+        generate_cards(client, "fire", "wuxia", [], (2, 3))
+
+
+# Verify pack generation rejects wrong-size model output.
+def test_generate_pack_rejects_wrong_size() -> None:
+    client = FakePackClient({"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]})
+    with pytest.raises(ValueError, match="wrong size"):
+        generate_pack(client, "fire", "wuxia", [], cost=2)
+
+
+# Verify pack generation trims extra model output.
+def test_generate_pack_trims_extra_cards() -> None:
+    client = FakePackClient(
+        {
+            "cards": [
+                {"name": "A", "effects": [{"primitive_id": "deal"}]},
+                {"name": "B", "effects": [{"primitive_id": "burn"}]},
+                {"name": "C", "effects": [{"primitive_id": "bomb"}]},
+                {"name": "D", "effects": [{"primitive_id": "draw"}]},
+            ]
+        }
+    )
+    pack = generate_pack(client, "fire", "wuxia", [], cost=2)
+    assert [card.name for card in pack] == ["A", "B", "C"]
+
+
+# Verify invalid school output is rejected after parsing.
+def test_parse_card_payload_still_goes_through_budget_validation() -> None:
+    raw = {"name": "Off School", "effects": [{"primitive_id": "bomb"}]}
+    spec = parse_card_payload(raw, "ice", "wuxia", 1)
+    with pytest.raises(ValueError, match="not allowed"):
+        cost_card(spec)
+
+
+# Verify pack parsing uses engine costing.
+def test_parse_pack_payload_costs_cards() -> None:
+    pack = parse_pack_payload({"cards": [{"name": "A", "effects": [{"primitive_id": "deal", "amount": 999}]}]}, "fire", "wuxia", 1)
+    assert pack[0].rules_text() == "Deal 2 damage."
+
+
+# Verify invalid model weights normalize to the smallest legal weight.
+def test_parse_effect_plan_clamps_weight() -> None:
+    assert parse_effect_plan({"primitive_id": "deal", "weight": 0}).weight == 1
+
+
+# Verify Codex prompt includes constraints and deck context.
+def test_codex_pack_prompt_mentions_engine_owned_numbers() -> None:
+    prompt = codex_pack_prompt(pack_payload("fire", "wuxia", [context_card()], 2, 3))
+    assert "strict JSON only" in prompt
+    assert "engine owns all final numbers" in prompt
+    assert "meaningfully different" in prompt
+    assert "Class identity" in prompt
+    assert "Primitive guidance" in prompt
+    assert "Draft anchor cards" in prompt
+    assert "Draft direction" in prompt
+    assert "Deck primitive counts" in prompt
+    assert "Draft need" in prompt
+    assert "Return exactly 3 cards" in prompt
+    assert "Spark" in prompt
+
+
+# Verify Codex prompt supports batch cost schedules.
+def test_codex_pack_prompt_mentions_cost_schedule() -> None:
+    from generator import cards_payload
+
+    prompt = codex_pack_prompt(cards_payload("fire", "wuxia", [], (2, 3)))
+    assert "Card costs by index: [2, 3]" in prompt
+
+
+# Verify JSON extraction tolerates surrounding model text.
+def test_extract_json_object() -> None:
+    assert extract_json_object("text {\"cards\": []} more") == "{\"cards\": []}"
+    with pytest.raises(ValueError, match="JSON object"):
+        extract_json_object("no json")
+
+
+# Verify JSON extraction repairs missing closing delimiters.
+def test_extract_json_object_repairs_missing_closer() -> None:
+    assert extract_json_object('{"cards": [{"name": "A"}]') == '{"cards": [{"name": "A"}]}'
+
+
+# Verify JSON closer balancing ignores braces inside strings.
+def test_balance_json_closers_ignores_strings() -> None:
+    assert balance_json_closers('{"text": "}"}') == '{"text": "}"}'
+
+
+# Verify Codex client reads the final-message file.
+def test_codex_client_invokes_subprocess(monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:
+    calls: list[dict[str, Any]] = []
+
+    # Fake subprocess.run by writing the requested output file.
+    def fake_run(command: tuple[str, ...], **kwargs: Any) -> subprocess.CompletedProcess[str]:
+        output_path = command[command.index("--output-last-message") + 1]
+        calls.append({"command": command, "kwargs": kwargs})
+        with open(output_path, "w") as output:
+            output.write('{"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]}')
+        return subprocess.CompletedProcess(command, 0, "", "")
+
+    monkeypatch.setattr("generator.subprocess.run", fake_run)
+    client = CodexCardClient(command=("codex", "exec", "-"), cwd=str(tmp_path))
+    raw = client.create_pack(pack_payload("fire", "wuxia", [], 1, 1))
+    assert raw["cards"][0]["name"] == "A"
+    assert "--output-last-message" in calls[0]["command"]
+    assert calls[0]["kwargs"]["cwd"] == str(tmp_path)
+
+
+# Verify single-card Codex calls reuse the pack path.
+def test_codex_client_create_card_uses_pack(monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:
+    # Fake subprocess.run by writing one valid card.
+    def fake_run(command: tuple[str, ...], **_: Any) -> subprocess.CompletedProcess[str]:
+        output_path = command[command.index("--output-last-message") + 1]
+        with open(output_path, "w") as output:
+            output.write('{"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]}')
+        return subprocess.CompletedProcess(command, 0, "", "")
+
+    monkeypatch.setattr("generator.subprocess.run", fake_run)
+    client = CodexCardClient(command=("codex", "exec", "-"), cwd=str(tmp_path))
+    raw = client.create_card(generator_payload("fire", "wuxia", []))
+    assert raw["name"] == "A"
+
+
+# Verify MiniCPM card client uses local chat completions.
+def test_minicpm_card_client() -> None:
+    chat = FakeChat('{"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]}')
+    client = MiniCPMCardClient(chat)  # type: ignore[arg-type]
+    raw = client.create_pack(pack_payload("fire", "wuxia", [], 1, 1))
+    assert raw["cards"][0]["name"] == "A"
+    assert "strict JSON" in chat.calls[0][0]
+    assert "Allowed primitives" in chat.calls[0][1]
+
+
+# Verify MiniCPM single-card calls reuse the pack path.
+def test_minicpm_card_client_create_card() -> None:
+    chat = FakeChat('{"cards": [{"name": "A", "effects": [{"primitive_id": "deal"}]}]}')
+    client = MiniCPMCardClient(chat)  # type: ignore[arg-type]
+    assert client.create_card(generator_payload("fire", "wuxia", []))["name"] == "A"
+
+
+# Verify llama.cpp card prompt asks for one compact card.
+def test_llamacpp_card_prompt() -> None:
+    payload = pack_payload("fire", "wuxia", [context_card()], 2, 3)
+    prompt = llamacpp_card_prompt(payload, [{"name": "A", "effects": [{"primitive_id": "burn"}]}])
+    assert "Create exactly one Tabras card" in prompt
+    assert "Fit the school identity" in prompt
+    assert "Primitive guidance" in prompt
+    assert "Current draft need" in prompt
+    assert "This candidate should" in prompt
+    assert "Already in this pack" in prompt
+    assert "\"burn\": 1" in prompt
+    assert "Spark" in prompt
+
+
+# Verify llama.cpp card client assembles packs from single-card calls.
+def test_llamacpp_card_client() -> None:
+    chat = FakeChat('{"name": "A", "effects": [{"primitive_id": "deal"}]}')
+    client = LlamaCppCardClient(chat)  # type: ignore[arg-type]
+    raw = client.create_pack(pack_payload("fire", "wuxia", [], 1, 3))
+    assert [card["name"] for card in raw["cards"]] == ["A", "A", "A"]
+    assert len(chat.calls) == 3
+
+
+# Verify llama.cpp card generation retries missed candidate needs.
+def test_generate_llamacpp_card_retries_missed_need() -> None:
+    payload = pack_payload("earth", "wuxia", [direct_card("Block", "earth", (Effect("block", amount=1),))], 2, 3)
+    chat = FakeChat(
+        [
+            '{"name": "Plain", "effects": [{"primitive_id": "deal"}]}',
+            '{"earth_tabras": {"name": "Payoff", "effects": [{"primitive_id": "scaling"}]}}',
+        ]
+    )
+    card = generate_llamacpp_card(chat, payload, [])
+    assert card["name"] == "Payoff"
+    assert card["effects"] == [{"primitive_id": "scaling", "weight": 1}]
+    assert len(chat.calls) == 2
+
+
+# Verify llama.cpp repair fills required schema fields.
+def test_repair_llamacpp_card_fills_missing_fields() -> None:
+    payload = pack_payload("fire", "wuxia", [], 1, 3)
+    raw = {"school": "fire", "effects": [{"primitive_id": "deal", "weight": 0}, {"primitive_id": "burn"}]}
+    card = repair_llamacpp_card(raw, payload, [])
+    assert card["name"] == "Fire Deal Burn"
+    assert card["flavor"] == ""
+    assert card["art_prompt"] == "wuxia fire card art"
+    assert card["effects"] == [{"primitive_id": "deal", "weight": 1}, {"primitive_id": "burn", "weight": 1}]
+
+
+# Verify llama.cpp repair drops invalid primitives.
+def test_repair_llamacpp_card_drops_invalid_primitives() -> None:
+    payload = pack_payload("ice", "wuxia", [], 1, 3)
+    card = repair_llamacpp_card({"effects": [{"primitive_id": "bomb"}]}, payload, [])
+    assert card["effects"] == [{"primitive_id": "deal", "weight": 1}]
+
+
+# Verify one-card normalization accepts pack-shaped responses.
+def test_normalize_card_response() -> None:
+    assert normalize_card_response({"cards": [{"name": "A"}]}) == {"name": "A"}
+
+
+# Verify one-card normalization unwraps named wrapper objects.
+def test_normalize_card_response_unwraps_wrapper() -> None:
+    raw = {"earth_tabras": {"name": "Earth Tabras", "effects": [{"primitive_id": "scaling"}]}}
+    assert normalize_card_response(raw) == {"name": "Earth Tabras", "effects": [{"primitive_id": "scaling"}]}
+
+
+# Verify one-card normalization unwraps MiniCPM shape wrappers.
+def test_normalize_card_response_unwraps_shape() -> None:
+    raw = {"shape": {"name": "Shield of Scale", "effects": [{"primitive_id": "scaling"}]}, "school": "earth"}
+    assert normalize_card_response(raw) == {"name": "Shield of Scale", "effects": [{"primitive_id": "scaling"}]}
+
+
+# Verify malformed llama.cpp card JSON becomes a legal fallback card.
+def test_parse_llamacpp_card_text_falls_back() -> None:
+    payload = pack_payload("earth", "wuxia", [], 1, 3)
+    card = parse_llamacpp_card_text('{"name" "Broken"}', payload, [])
+    assert card["name"] == "Earth Deal"
+    assert card["effects"] == [{"primitive_id": "deal", "weight": 1}]
+
+
+# Verify Codex client reports subprocess failures.
+def test_codex_client_reports_failure(monkeypatch: pytest.MonkeyPatch, tmp_path: Any) -> None:
+    # Fake subprocess.run with a failed Codex result.
+    def fake_run(command: tuple[str, ...], **_: Any) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(command, 1, "", "blocked")
+
+    monkeypatch.setattr("generator.subprocess.run", fake_run)
+    client = CodexCardClient(command=("codex", "exec", "-"), cwd=str(tmp_path))
+    with pytest.raises(RuntimeError, match="blocked"):
+        client.create_pack(pack_payload("fire", "wuxia", [], 1, 1))

tests/test_local_llm.py

@@ -0,0 +1,287 @@
+import json
+from typing import Any
+
+from local_llm import (
+    LocalChatClient,
+    LocalCompletionClient,
+    LocalJsonChatClient,
+    MLXChatClient,
+    MiniCPMTransformersChatClient,
+    NemotronTransformersChatClient,
+    chat_messages,
+    chat_payload,
+    completion_payload,
+    decode_generated_text,
+    json_chat_payload,
+    minicpm_text_prompt,
+    nemotron_prompt,
+    parse_chat_response,
+    parse_completion_response,
+    tensor_to_model_device,
+    token_length,
+    transformers_model_kwargs,
+)
+
+
+class FakeResponse:
+    # Initialize a fake HTTP response body.
+    def __init__(self, raw: dict[str, Any]) -> None:
+        self.raw = raw
+
+    # Enter the fake response context.
+    def __enter__(self) -> "FakeResponse":
+        return self
+
+    # Exit the fake response context.
+    def __exit__(self, *_: object) -> None:
+        return None
+
+    # Return encoded response bytes.
+    def read(self) -> bytes:
+        return json.dumps(self.raw).encode("utf-8")
+
+
+class FakeInputs(list):
+    # Initialize tensor-like fake inputs.
+    def __init__(self) -> None:
+        super().__init__([[1, 2]])
+        self.shape = (1, 2)
+        self.moved_to: str | None = None
+
+    # Capture device moves.
+    def to(self, device: str) -> "FakeInputs":
+        self.moved_to = device
+        return self
+
+
+class FakeTokenizer:
+    # Initialize a fake tokenizer.
+    def __init__(self) -> None:
+        self.messages: list[dict[str, str]] = []
+
+    # Capture chat template messages.
+    def apply_chat_template(self, messages: list[dict[str, str]], **_: Any) -> FakeInputs:
+        self.messages = messages
+        return FakeInputs()
+
+    # Decode generated token ids.
+    def decode(self, tokens: list[int], **_: Any) -> str:
+        return f"decoded:{tokens}"
+
+
+class FakeModel:
+    device = "cuda"
+
+    # Return a generated token sequence with prompt prefix included.
+    def generate(self, inputs: FakeInputs, **kwargs: Any) -> list[list[int]]:
+        self.inputs = inputs
+        self.kwargs = kwargs
+        return [[1, 2, 3, 4]]
+
+
+class FakeMiniCPMModel:
+    # Capture MiniCPM chat kwargs.
+    def chat(self, **kwargs: Any) -> str:
+        self.kwargs = kwargs
+        return "mini"
+
+
+class FakeMLXGenerate:
+    # Capture MLX generation arguments.
+    def __call__(self, *args: Any, **kwargs: Any) -> str:
+        self.args = args
+        self.kwargs = kwargs
+        return "mlx"
+
+
+class FakeTorch:
+    bfloat16 = "bf16"
+
+    class cuda:
+        # Report no CUDA for dtype fallback tests.
+        @staticmethod
+        def is_available() -> bool:
+            return False
+
+
+class FakeCudaTorch:
+    bfloat16 = "bf16"
+
+    class cuda:
+        # Report CUDA for dtype selection tests.
+        @staticmethod
+        def is_available() -> bool:
+            return True
+
+
+# Verify chat payload shape matches OpenAI-compatible endpoints.
+def test_chat_payload() -> None:
+    payload = chat_payload("local", "sys", "user", 0.5)
+    assert payload["model"] == "local"
+    assert payload["messages"][0]["role"] == "system"
+    assert payload["temperature"] == 0.5
+    assert "max_tokens" not in payload
+    assert chat_payload("local", "sys", "user", 0.5, 44)["max_tokens"] == 44
+
+
+# Verify completion payload shape matches OpenAI-compatible endpoints.
+def test_completion_payload() -> None:
+    payload = completion_payload("local", "prompt", 0.4, 99)
+    assert payload == {"model": "local", "prompt": "prompt", "temperature": 0.4, "max_tokens": 99}
+
+
+# Verify JSON chat payload requests JSON object output.
+def test_json_chat_payload() -> None:
+    payload = json_chat_payload("local", "sys", "user", 0.0, 55)
+    assert payload["response_format"] == {"type": "json_object"}
+    assert payload["max_tokens"] == 55
+
+
+# Verify chat message payloads use standard roles.
+def test_chat_messages() -> None:
+    assert chat_messages("sys", "user") == [{"role": "system", "content": "sys"}, {"role": "user", "content": "user"}]
+
+
+# Verify Nemotron prompt markers match the documented template.
+def test_nemotron_prompt() -> None:
+    assert nemotron_prompt("sys", "user") == "<extra_id_0>System\nsys\n\n<extra_id_1>User\nuser\n<extra_id_1>Assistant\n"
+
+
+# Verify MiniCPM receives system and user text in one chat prompt.
+def test_minicpm_text_prompt() -> None:
+    assert minicpm_text_prompt("sys", "user") == "System:\nsys\n\nUser:\nuser"
+
+
+# Verify chat response parsing returns assistant content.
+def test_parse_chat_response() -> None:
+    assert parse_chat_response({"choices": [{"message": {"content": "ok"}}]}) == "ok"
+
+
+# Verify completion response parsing supports common local shapes.
+def test_parse_completion_response() -> None:
+    assert parse_completion_response({"content": "llama"}) == "llama"
+    assert parse_completion_response({"choices": [{"text": "done"}]}) == "done"
+    assert parse_completion_response({"choices": [{"message": {"content": "chat"}}]}) == "chat"
+
+
+# Verify local chat client posts JSON and returns content.
+def test_local_chat_client(monkeypatch: Any) -> None:
+    calls: list[Any] = []
+
+    # Capture the request and return a fake response.
+    def fake_urlopen(req: Any, timeout: int) -> FakeResponse:
+        calls.append((req, timeout))
+        return FakeResponse({"choices": [{"message": {"content": "done"}}]})
+
+    monkeypatch.setattr("local_llm.request.urlopen", fake_urlopen)
+    client = LocalChatClient("http://localhost/v1/chat/completions", "local", timeout_seconds=3)
+    assert client.complete("sys", "user") == "done"
+    assert calls[0][1] == 3
+    payload = json.loads(calls[0][0].data.decode("utf-8"))
+    assert payload["model"] == "local"
+    assert payload["max_tokens"] == 256
+
+
+# Verify local JSON chat client posts JSON mode payloads.
+def test_local_json_chat_client(monkeypatch: Any) -> None:
+    calls: list[Any] = []
+
+    # Capture the request and return a fake response.
+    def fake_urlopen(req: Any, timeout: int) -> FakeResponse:
+        calls.append((req, timeout))
+        return FakeResponse({"choices": [{"message": {"content": "{\"ok\": true}"}}]})
+
+    monkeypatch.setattr("local_llm.request.urlopen", fake_urlopen)
+    client = LocalJsonChatClient("http://localhost/v1/chat/completions", "local", timeout_seconds=5, max_tokens=22)
+    assert client.complete("sys", "user") == "{\"ok\": true}"
+    payload = json.loads(calls[0][0].data.decode("utf-8"))
+    assert payload["response_format"] == {"type": "json_object"}
+    assert payload["max_tokens"] == 22
+    assert calls[0][1] == 5
+
+
+# Verify local completion client posts a rendered prompt and returns content.
+def test_local_completion_client(monkeypatch: Any) -> None:
+    calls: list[Any] = []
+
+    # Capture the request and return a fake response.
+    def fake_urlopen(req: Any, timeout: int) -> FakeResponse:
+        calls.append((req, timeout))
+        return FakeResponse({"choices": [{"text": "done"}]})
+
+    monkeypatch.setattr("local_llm.request.urlopen", fake_urlopen)
+    client = LocalCompletionClient("http://localhost/v1/completions", "local", nemotron_prompt, timeout_seconds=4, max_tokens=12)
+    assert client.complete("sys", "user") == "done"
+    payload = json.loads(calls[0][0].data.decode("utf-8"))
+    assert payload["prompt"] == nemotron_prompt("sys", "user")
+    assert payload["max_tokens"] == 12
+    assert calls[0][1] == 4
+
+
+# Verify tensor device moves are optional.
+def test_tensor_to_model_device() -> None:
+    inputs = FakeInputs()
+    assert tensor_to_model_device(inputs, FakeModel()).moved_to == "cuda"
+    assert tensor_to_model_device([1, 2], object()) == [1, 2]
+
+
+# Verify token length handles tensor-like and list inputs.
+def test_token_length() -> None:
+    assert token_length(FakeInputs()) == 2
+    assert token_length([[1, 2, 3]]) == 3
+    assert token_length([1, 2]) == 2
+
+
+# Verify generated decoding removes the prompt prefix.
+def test_decode_generated_text() -> None:
+    assert decode_generated_text(FakeTokenizer(), FakeInputs(), [[1, 2, 3]]) == "decoded:[3]"
+
+
+# Verify Nemotron Transformers client uses tokenizer chat templates.
+def test_nemotron_transformers_chat_client() -> None:
+    tokenizer = FakeTokenizer()
+    model = FakeModel()
+    client = NemotronTransformersChatClient(model, tokenizer, max_new_tokens=7, temperature=0.0)
+    assert client.complete("sys", "user") == "decoded:[3, 4]"
+    assert tokenizer.messages[0]["role"] == "system"
+    assert model.inputs.moved_to == "cuda"
+    assert model.kwargs["max_new_tokens"] == 7
+    assert model.kwargs["do_sample"] is False
+
+
+# Verify MLX chat client renders prompts and calls generate.
+def test_mlx_chat_client() -> None:
+    generate = FakeMLXGenerate()
+    client = MLXChatClient("model", "tok", nemotron_prompt, generate, max_tokens=11)
+    assert client.complete("sys", "user") == "mlx"
+    assert generate.args == ("model", "tok", nemotron_prompt("sys", "user"))
+    assert generate.kwargs == {"verbose": False, "max_tokens": 11}
+
+
+# Verify MiniCPM Transformers client uses model.chat with no image.
+def test_minicpm_transformers_chat_client() -> None:
+    model = FakeMiniCPMModel()
+    client = MiniCPMTransformersChatClient(model, tokenizer="tok", max_new_tokens=77)
+    assert client.complete("sys", "user") == "mini"
+    assert model.kwargs["image"] is None
+    assert model.kwargs["tokenizer"] == "tok"
+    assert model.kwargs["system_prompt"] == "sys"
+    assert model.kwargs["sampling"] is False
+    assert model.kwargs["max_new_tokens"] == 77
+    assert model.kwargs["msgs"][0]["content"] == "user"
+
+
+# Verify Transformers model kwargs use auto dtype.
+def test_transformers_model_kwargs(monkeypatch: Any) -> None:
+    monkeypatch.setenv("TABRAS_MODEL_OFFLOAD", "/tmp/custom-offload")
+    assert transformers_model_kwargs()["torch_dtype"] == "auto"
+    if "device_map" in transformers_model_kwargs():
+        assert transformers_model_kwargs()["offload_folder"] == "/tmp/custom-offload"
+
+
+# Verify MiniCPM dtype follows CUDA availability.
+def test_local_torch_dtype() -> None:
+    from local_llm import local_torch_dtype
+
+    assert local_torch_dtype(FakeTorch) == "auto"
+    assert local_torch_dtype(FakeCudaTorch) == "bf16"

tests/test_play.py

@@ -0,0 +1,314 @@
+from random import Random
+
+from budget import Card
+from game import DuelState, create_player
+from play import (
+    best_pack_index,
+    best_draft_index,
+    card_line,
+    card_primitives,
+    choose_assistant_card,
+    choose_enemy_card,
+    choice_state_line,
+    combat_card_score,
+    demo_deck,
+    draft_enemy_deck,
+    draft_card_score,
+    draft_player_deck,
+    ice_need_bonus,
+    earth_need_bonus,
+    effect_score,
+    immediate_hp_damage,
+    pack_line,
+    playable_indexes,
+    player_line,
+    play_turn,
+    prompt_pack_choice,
+    prompt_human_choice,
+    run_text_duel,
+    shuffled_deck,
+)
+from primitives import Effect
+
+
+# Build a play-loop test card.
+def make_card(name: str, cost: int, effect: Effect) -> Card:
+    return Card(name, cost, "fire", "wuxia", (effect,))
+
+
+# Build a play-loop test duel.
+def make_duel() -> DuelState:
+    return DuelState(create_player("You", []), create_player("Enemy", []))
+
+
+class PlayPackClient:
+    # Initialize call tracking for play draft generation.
+    def __init__(self) -> None:
+        self.calls = 0
+
+    # Return one legal fire pack.
+    def create_pack(self, payload: dict[str, object]) -> dict[str, object]:
+        self.calls += 1
+        if "costs" in payload:
+            costs = payload["costs"]  # type: ignore[assignment]
+            return {
+                "cards": [
+                    {"name": f"Spark {self.calls}-{index}", "flavor": "A", "effects": [{"primitive_id": "deal"}]}
+                    for index, _ in enumerate(costs, 1)
+                ]
+            }
+        return {
+            "cards": [
+                {"name": f"Spark {self.calls}A", "flavor": "A", "effects": [{"primitive_id": "deal"}]},
+                {"name": f"Spark {self.calls}B", "flavor": "B", "effects": [{"primitive_id": "burn"}]},
+                {"name": f"Spark {self.calls}C", "flavor": "C", "effects": [{"primitive_id": "scaling"}]},
+            ]
+        }
+
+
+# Verify card and player display lines stay compact.
+def test_display_lines() -> None:
+    card = make_card("Spark", 1, Effect("deal", amount=2))
+    player = create_player("You", [])
+    player.energy = 1
+    player.block = 2
+    player.ward = 3
+    assert card_line(0, card) == "0: Spark [1] - Deal 2 damage."
+    assert player_line(player) == "You: 20 HP, 1 energy, 2 block, 3 ward, 0 charge (hand 0, deck 0, discard 0)"
+
+
+# Verify choice state shows the active energy and target defenses.
+def test_choice_state_line() -> None:
+    state = make_duel()
+    state.player.energy = 3
+    state.enemy.hp = 12
+    state.enemy.block = 2
+    state.enemy.ward = 1
+    assert choice_state_line(state, state.player) == "You energy 3. Enemy: 12 HP, 2 block, 1 ward."
+
+
+# Verify draft pack lines include flavor.
+def test_pack_line() -> None:
+    card = Card("Spark", 1, "fire", "wuxia", (Effect("deal", amount=2),), flavor="Hot.")
+    assert pack_line(0, card) == "0: Spark [1] - Deal 2 damage. | Hot."
+
+
+# Verify playable indexes filter by current energy.
+def test_playable_indexes() -> None:
+    player = create_player("You", [])
+    player.energy = 2
+    player.hand = [
+        make_card("One", 1, Effect("deal", amount=2)),
+        make_card("Three", 3, Effect("deal", amount=6)),
+    ]
+    assert playable_indexes(player) == (0,)
+
+
+# Verify the enemy chooses lethal before other playable cards.
+def test_choose_enemy_card_prefers_lethal() -> None:
+    state = make_duel()
+    state.enemy.energy = 3
+    state.player.hp = 2
+    state.enemy.hand = [
+        make_card("Cheap", 1, Effect("deal", amount=2)),
+        make_card("Big", 3, Effect("block", amount=10)),
+    ]
+    assert choose_enemy_card(state, state.enemy) == 0
+    assert choose_assistant_card(state, state.enemy) == 0
+
+
+# Verify the enemy passes without playable cards.
+def test_choose_enemy_card_passes_without_playable_cards() -> None:
+    state = make_duel()
+    state.enemy.energy = 0
+    state.enemy.hand = [make_card("Big", 3, Effect("deal", amount=4))]
+    assert choose_assistant_card(state, state.enemy) is None
+
+
+# Verify the enemy values defense when behind.
+def test_choose_enemy_card_values_defense_when_behind() -> None:
+    state = make_duel()
+    state.enemy.hp = 5
+    state.player.hp = 12
+    state.enemy.energy = 2
+    state.enemy.hand = [
+        make_card("Small hit", 1, Effect("deal", amount=2)),
+        make_card("Guard", 2, Effect("block", amount=6)),
+    ]
+    assert choose_enemy_card(state, state.enemy) == 1
+
+
+# Verify human input accepts pass and retries invalid choices.
+def test_prompt_human_choice() -> None:
+    outputs: list[str] = []
+    answers = iter(["9", "0"])
+    state = make_duel()
+    state.player.energy = 1
+    state.player.hand = [make_card("Spark", 1, Effect("deal", amount=2))]
+    chooser = prompt_human_choice(lambda _: next(answers), outputs.append)
+    assert chooser(state, state.player) == 0
+    assert "That card is not playable." in outputs
+    assert "You energy 1. Enemy: 20 HP, 0 block, 0 ward." in outputs
+    pass_chooser = prompt_human_choice(lambda _: "pass", outputs.append)
+    assert pass_chooser(state, state.player) is None
+
+
+# Verify draft prompt accepts one shown card and retries invalid input.
+def test_prompt_pack_choice() -> None:
+    outputs: list[str] = []
+    answers = iter(["5", "1"])
+    pack = (
+        make_card("A", 1, Effect("deal", amount=2)),
+        make_card("B", 1, Effect("deal", amount=2)),
+        make_card("C", 1, Effect("deal", amount=2)),
+    )
+    chooser = prompt_pack_choice(lambda _: next(answers), outputs.append)
+    assert chooser((), pack) == 1
+    assert "Choose one of the shown draft cards." in outputs
+
+
+# Verify player drafting produces a 15-card deck from nine packs.
+def test_draft_player_deck() -> None:
+    outputs: list[str] = []
+    client = PlayPackClient()
+    deck = draft_player_deck(client, "fire", "dark fantasy", lambda _: "2", outputs.append)
+    assert len(deck) == 15
+    assert client.calls == 9
+    assert deck[-1].name == "Spark 9C"
+    assert "Draft pick 9/9. Current deck: 14 cards." in outputs
+
+
+# Verify enemy drafting chooses the highest-scoring generated card.
+def test_draft_enemy_deck() -> None:
+    outputs: list[str] = []
+    client = PlayPackClient()
+    deck = draft_enemy_deck(client, "fire", "dark fantasy", outputs.append, Random(0))
+    assert len(deck) == 15
+    assert client.calls == 9
+    assert any("Enemy generated pick 9/9" in line for line in outputs)
+
+
+# Verify pack selection uses static card scoring.
+def test_best_pack_index() -> None:
+    pack = (
+        make_card("Block", 1, Effect("block", amount=3)),
+        make_card("Hit", 1, Effect("deal", amount=4)),
+        make_card("Draw", 1, Effect("draw", amount=1)),
+    )
+    assert best_pack_index(pack) == 1
+
+
+# Verify deck-aware draft selection can choose synergy over raw damage.
+def test_best_draft_index_uses_school_needs() -> None:
+    current_deck = (Card("Setup", 1, "ice", "wuxia", (Effect("vulnerable", amount=1),)),)
+    pack = (
+        Card("Damage", 2, "ice", "wuxia", (Effect("deal", amount=8),)),
+        Card("Payoff", 2, "ice", "wuxia", (Effect("multi_hit", amount=1, hits=2),)),
+    )
+    assert best_draft_index(current_deck, pack) == 1
+    assert draft_card_score(current_deck, pack[1]) > draft_card_score(current_deck, pack[0])
+
+
+# Verify Ice bonus rewards missing payoff.
+def test_ice_need_bonus_rewards_missing_payoff() -> None:
+    assert ice_need_bonus(("multi_hit",), {"vulnerable": 1}) > 0
+    assert card_primitives(make_card("Hit", 1, Effect("deal", amount=1))) == ("deal",)
+
+
+# Verify Earth bonus rewards block after scaling payoff.
+def test_earth_need_bonus_rewards_block_engine() -> None:
+    assert earth_need_bonus(("block",), {"scaling": 2, "block": 1}) > earth_need_bonus(("deal",), {"scaling": 2, "block": 1})
+
+
+# Verify tactical score helpers cover primitive categories.
+def test_score_helpers() -> None:
+    state = make_duel()
+    state.enemy.hp = 5
+    state.player.hp = 10
+    card = make_card("Guard", 1, Effect("block", amount=3))
+    assert combat_card_score(state, state.enemy, card) > combat_card_score(state, state.player, card)
+    assert effect_score("multi_hit", 2, 3) == 12
+    assert effect_score("burn", 2, 1) == 4
+    assert effect_score("initiative", 0, 1) == 2
+    assert effect_score("unknown", 0, 1) == 0
+
+
+# Verify immediate damage estimates cover tactical effect shapes.
+def test_immediate_hp_damage_shapes() -> None:
+    state = make_duel()
+    state.enemy.block = 1
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Hits", 1, Effect("multi_hit", amount=2, hits=2))) == 2
+    state.enemy.block = 0
+    state.enemy.hp = 10
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Finish", 1, Effect("conditional", amount=3))) == 1
+    state.player.cards_played_this_turn = 1
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Grow", 1, Effect("scaling", amount=2))) == 4
+    state.player.shield_charge = 5
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Burst", 1, Effect("scaling", amount=2, condition="shield_charge"))) == 7
+    state.enemy.ward = 1
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Stopped", 1, Effect("deal", amount=9))) == 0
+    state.enemy.ward = 0
+    state.player.weak = 9
+    assert immediate_hp_damage(state.player, state.enemy, make_card("Weak", 1, Effect("deal", amount=3))) == 0
+
+
+# Verify play_turn resolves selected cards until pass.
+def test_play_turn_resolves_cards() -> None:
+    outputs: list[str] = []
+    state = make_duel()
+    state.player.energy = 2
+    state.player.hand = [
+        make_card("Spark", 1, Effect("deal", amount=2)),
+        make_card("Guard", 1, Effect("block", amount=3)),
+    ]
+    choices = iter([0, None])
+    play_turn(state, state.player, lambda _, __: next(choices), outputs.append)
+    assert state.enemy.hp == 18
+    assert state.player.hand[0].name == "Guard"
+    assert state.player.discard[0].name == "Spark"
+    assert outputs[-1] == "You passes."
+
+
+# Verify the demo deck has the locked deck size.
+def test_demo_deck_has_fifteen_cards() -> None:
+    deck = demo_deck("fire", "dark fantasy")
+    assert len(deck) == 15
+    assert deck[0].rules_text() == "Deal 2 damage."
+
+
+# Verify deck shuffling is deterministic from the run RNG.
+def test_shuffled_deck_uses_rng() -> None:
+    deck = tuple(make_card(str(index), 1, Effect("deal", amount=1)) for index in range(5))
+    shuffled = shuffled_deck(deck, Random(1))
+    assert [card.name for card in shuffled] != [card.name for card in deck]
+    assert [card.name for card in shuffled] == [card.name for card in shuffled_deck(deck, Random(1))]
+
+
+# Verify a short scripted duel can produce a winner.
+def test_run_text_duel_returns_winner() -> None:
+    outputs: list[str] = []
+    player_deck = tuple(make_card("Strike", 1, Effect("deal", amount=25)) for _ in range(4))
+    enemy_deck = (
+        make_card("Wait", 5, Effect("block", amount=1)),
+        make_card("Wait", 5, Effect("block", amount=1)),
+        make_card("Wait", 5, Effect("block", amount=1)),
+        make_card("Wait", 5, Effect("block", amount=1)),
+    )
+    result = run_text_duel(player_deck, enemy_deck, lambda _: "0", outputs.append, Random(0), max_rounds=1)
+    assert result == "You"
+    assert outputs[-1] == "Winner: You"
+
+
+# Verify the round stops immediately when the first actor wins.
+def test_run_text_duel_stops_after_first_actor_win() -> None:
+    outputs: list[str] = []
+    player_deck = tuple(make_card("Strike", 1, Effect("deal", amount=25)) for _ in range(4))
+    enemy_deck = (
+        make_card("Wait", 1, Effect("deal", amount=1)),
+        make_card("Wait", 1, Effect("deal", amount=1)),
+        make_card("Wait", 1, Effect("deal", amount=1)),
+        make_card("Wait", 1, Effect("deal", amount=1)),
+    )
+    result = run_text_duel(player_deck, enemy_deck, lambda _: "0", outputs.append, Random(3), max_rounds=1)
+    assert result == "You"
+    assert not any(line.startswith("Enemy plays") for line in outputs)

tests/test_primitives.py

@@ -0,0 +1,70 @@
+import pytest
+
+from primitives import Effect, get_primitive, primitive_allowed_for_school, primitive_ids, render_effect, school_bias, school_primitives
+
+
+# Verify the fixed primitive vocabulary stays complete.
+def test_primitive_ids_are_the_locked_thirteen() -> None:
+    assert primitive_ids() == (
+        "deal",
+        "burn",
+        "bomb",
+        "block",
+        "ward",
+        "weak",
+        "draw",
+        "energy",
+        "initiative",
+        "multi_hit",
+        "vulnerable",
+        "conditional",
+        "scaling",
+    )
+
+
+# Verify school draft pools match the README.
+def test_school_primitives_match_spec() -> None:
+    assert school_primitives("fire") == ("deal", "burn", "bomb", "scaling", "draw", "energy", "block", "conditional")
+    assert school_primitives("ice") == ("deal", "initiative", "vulnerable", "multi_hit", "conditional", "draw", "energy", "block")
+    assert school_primitives("earth") == ("deal", "ward", "block", "weak", "scaling", "conditional", "draw", "energy")
+    assert primitive_allowed_for_school("deal", "fire")
+    assert primitive_allowed_for_school("deal", "ice")
+    assert not primitive_allowed_for_school("bomb", "ice")
+
+
+# Verify school bias explains generation weights.
+def test_school_bias() -> None:
+    assert "immediate Deal" in school_bias("fire")
+    assert "shield charge" in school_bias("earth")
+
+
+# Verify primitive lookup returns the stored schema.
+def test_get_primitive_returns_spec() -> None:
+    primitive = get_primitive("ward")
+    assert primitive.name == "Ward"
+    assert primitive.category == "defense"
+
+
+@pytest.mark.parametrize(
+    ("effect", "text"),
+    (
+        (Effect("deal", amount=4), "Deal 4 damage."),
+        (Effect("burn", amount=2, duration=3), "Burn 2 damage for 3 turns."),
+        (Effect("bomb", amount=9, delay=3), "Bomb: deal 9 damage in 3 turns."),
+        (Effect("block", amount=6), "Gain 6 block until your next turn."),
+        (Effect("ward", amount=2), "Gain 2 ward."),
+        (Effect("weak", amount=2), "Opponent deals 2 less damage until your next turn."),
+        (Effect("draw", amount=1), "Draw 1 card."),
+        (Effect("draw", amount=2), "Draw 2 cards."),
+        (Effect("energy", amount=1), "Gain 1 energy this turn."),
+        (Effect("initiative"), "Opponent acts second next round."),
+        (Effect("multi_hit", amount=2, hits=3), "Deal 2 damage 3 times."),
+        (Effect("vulnerable", amount=1, duration=2), "Opponent takes 1 more damage for 2 turns."),
+        (Effect("conditional", amount=6), "Deal up to 6 damage based on opponent's missing HP."),
+        (Effect("scaling", amount=2), "Deal 2 damage plus cards played this turn."),
+        (Effect("scaling", amount=2, condition="shield_charge"), "Deal 2 damage plus your banked shield charge, then empty it."),
+    ),
+)
+# Verify every effect renders to fixed parseable text.
+def test_render_effect(effect: Effect, text: str) -> None:
+    assert render_effect(effect) == text

tests/test_ui.py

@@ -0,0 +1,318 @@
+from ui import (
+    CARD_PANEL_COUNT,
+    board_html,
+    choose_draft_card,
+    choose_draft_card_steps,
+    draft_screen_html,
+    enemy_school_for,
+    fallback_pack,
+    log_html,
+    mana_html,
+    new_run,
+    pass_turn,
+    pass_turn_steps,
+    pending_tokens_html,
+    play_hand_card,
+)
+
+
+# Build a run state that has finished drafting and entered battle.
+def battle_state(seed: int = 2):
+    state = new_run("Ada", "dark fantasy", "fire", seed=seed)
+    for _ in range(9):
+        state = choose_draft_card(state, 0)
+    return state
+
+
+# Verify enemy school rotation is deterministic.
+def test_enemy_school_for() -> None:
+    assert enemy_school_for("fire") == "earth"
+    assert enemy_school_for("earth") == "ice"
+    assert enemy_school_for("ice") == "fire"
+
+
+# Verify fallback packs produce three costed card panels.
+def test_fallback_pack() -> None:
+    pack = fallback_pack("earth", "dark fantasy", 3)
+    assert len(pack) == CARD_PANEL_COUNT
+    assert any("banked shield charge" in card.rules_text() for card in pack)
+
+
+# Verify a new run starts in draft state with three clickable cards.
+def test_new_run_starts_draft() -> None:
+    state = new_run("Ada", "anime", "ice", seed=1)
+    assert state.player_name == "Ada"
+    assert state.enemy_school == "fire"
+    assert state.duel is None
+    html = draft_screen_html(state)
+    assert html.count("tabras-card") == CARD_PANEL_COUNT
+    assert all(f"draft-btn-{index}" in html for index in range(CARD_PANEL_COUNT))
+    assert "Deck 6/15" in html
+
+
+# Verify choosing nine draft cards starts combat.
+def test_choose_draft_card_starts_battle() -> None:
+    state = battle_state()
+    assert state.duel is not None
+    assert len(state.player_deck) == 15
+    assert len(state.enemy_deck) == 15
+    assert "Boss" in state.duel.enemy.name
+    assert draft_screen_html(state) == ""
+
+
+# Verify the board renders heroes, mana, hand, and end-turn control.
+def test_board_html_shows_battle_state() -> None:
+    state = battle_state()
+    html = board_html(state)
+    assert "hp-gem" in html
+    assert "mana-bar" in html
+    assert "hand-fan" in html
+    assert "end-turn-btn" in html
+    assert html.count("hand-card") >= len(state.duel.player.hand)
+
+
+# Verify the board is empty before battle.
+def test_board_html_empty_outside_battle() -> None:
+    assert board_html(None) == ""
+    assert board_html(new_run("Ada", "anime", "ice", seed=1)) == ""
+
+
+# Verify picking a draft card first fades the old pack, then deals the next.
+def test_draft_pick_fades_between_packs() -> None:
+    state = new_run("Ada", "anime", "ice", seed=1)
+    old_pack = state.current_pack
+    steps = list(choose_draft_card_steps(state, 1))
+    fading, fresh = steps[0], steps[1]
+    assert fading.pack_fading == 1
+    assert fading.current_pack == old_pack
+    html = draft_screen_html(fading)
+    assert html.count("fading") == 2
+    assert "picked" in html
+    assert "draft-btn" not in html
+    assert fresh.pack_fading == -1
+    assert "draft-btn-0" in draft_screen_html(fresh)
+
+
+# Verify playing a card never ends the turn; only END TURN brings the boss out.
+def test_playing_card_keeps_turn() -> None:
+    state = battle_state()
+    state.duel.player.energy = sum(card.cost for card in state.duel.player.hand)
+    for _ in range(len(state.duel.player.hand)):
+        state = play_hand_card(state, 0)
+    assert all(owner != "Boss" for owner, _ in state.showcase)
+    assert state.duel.round_number == battle_state().duel.round_number
+
+
+# Verify the battlefield drops END TURN and the your-turn banner when the duel ends.
+def test_battlefield_quiets_after_winner() -> None:
+    state = battle_state()
+    live = board_html(state)
+    assert "END TURN" in live and "your turn" in live
+    state.duel.enemy.hp = 0
+    over = board_html(state)
+    assert "END TURN" not in over
+    assert "your turn" not in over
+    assert "duel over" in over
+
+
+# Verify playing a hand card consumes it and logs the play.
+def test_play_hand_card_plays_and_logs() -> None:
+    state = battle_state()
+    state.duel.player.energy = max(card.cost for card in state.duel.player.hand)
+    before = len(state.duel.player.hand)
+    played = play_hand_card(state, 0)
+    assert any("plays" in line for line in played.log)
+    assert len(played.duel.player.hand) <= before
+
+
+# Verify an unaffordable card is refused with a log line.
+def test_play_hand_card_refuses_expensive_card() -> None:
+    state = battle_state()
+    expensive = next((i for i, card in enumerate(state.duel.player.hand) if card.cost > state.duel.player.energy), None)
+    if expensive is None:
+        return
+    played = play_hand_card(state, expensive)
+    assert "needs" in played.log[-1]
+    assert len(played.duel.player.hand) == len(state.duel.player.hand)
+
+
+# Verify out-of-range plays leave the state unchanged.
+def test_play_hand_card_ignores_bad_index() -> None:
+    state = battle_state()
+    assert play_hand_card(state, 99) is state
+    assert play_hand_card(state, -1) is state
+
+
+# Verify passing advances the battle log.
+def test_pass_turn_updates_log() -> None:
+    state = battle_state(seed=4)
+    passed = pass_turn(state)
+    assert any("passes" in line for line in passed.log)
+
+
+# Verify played cards land in the showcase with an owner label.
+def test_showcase_records_plays() -> None:
+    state = battle_state()
+    state.duel.player.energy = max(card.cost for card in state.duel.player.hand)
+    played = play_hand_card(state, 0)
+    assert played.showcase[0][0] == "Ada"
+    html = board_html(played)
+    assert "played-card" in html
+    assert "You played" in html
+
+
+# Verify a round turnover step announces the round and initiative on a darkened board.
+def test_round_splash_announces_initiative() -> None:
+    state = battle_state()
+    steps = list(pass_turn_steps(state))
+    splash = next(step for step in steps if step.round_flash)
+    html = board_html(splash)
+    assert f"ROUND {splash.round_flash}" in html
+    assert "YOU GO FIRST" in html or "BOSS GOES FIRST" in html
+    assert "splash-initiative" in html
+
+
+# Verify the boss takes a visible thinking step before playing.
+def test_boss_turn_shows_thinking() -> None:
+    state = battle_state(seed=4)
+    for _ in range(3):
+        steps = list(pass_turn_steps(state))
+        thinking = [step for step in steps if step.boss_thinking]
+        if thinking:
+            assert "boss-thinking" in board_html(thinking[0])
+            assert "Boss is scheming" in board_html(thinking[0])
+            return
+        state = steps[-1]
+    raise AssertionError("boss never took a visible thinking step")
+
+
+# Verify boss cards stream in one step at a time, newest marked fresh.
+def test_boss_plays_stream_stepwise() -> None:
+    state = battle_state(seed=4)
+    for _ in range(3):
+        steps = list(pass_turn_steps(state))
+        counts = [len(step.showcase) for step in steps if step.showcase]
+        if counts:
+            assert counts == sorted(counts)
+            final = next(step for step in reversed(steps) if step.showcase)
+            assert board_html(final).count("play-slot fresh") == 1
+            return
+        state = steps[-1]
+    raise AssertionError("boss never played a card")
+
+
+# Verify playable hand cards launch through the animated play handler.
+def test_hand_cards_use_play_handler() -> None:
+    state = battle_state()
+    state.duel.player.energy = max(card.cost for card in state.duel.player.hand)
+    assert "tabrasPlay('hand-btn-0', this)" in board_html(state)
+
+
+# Verify play log entries are structured with owner, card, and effect text.
+def test_log_html_styles_plays_and_rounds() -> None:
+    state = battle_state()
+    state.duel.player.energy = max(card.cost for card in state.duel.player.hand)
+    html = log_html(play_hand_card(state, 0))
+    assert "log-play log-you" in html
+    assert "log-owner" in html
+    assert "log-round" in html
+
+
+# Verify boss plays join the showcase after the player passes.
+def test_showcase_includes_boss_plays() -> None:
+    state = battle_state(seed=4)
+    for _ in range(3):
+        state = pass_turn(state)
+    assert any(owner == "Boss" for owner, _ in state.showcase)
+
+
+# Verify per-step damage flashes sum to the action's total HP loss.
+def test_hp_flash_tracks_damage() -> None:
+    state = battle_state(seed=4)
+    for _ in range(8):
+        hp_before = state.duel.player.hp
+        steps = list(pass_turn_steps(state))
+        flashes = [step for step in steps if step.hp_flash[0] > 0]
+        assert sum(step.hp_flash[0] for step in steps) == max(0, hp_before - steps[-1].duel.player.hp)
+        if flashes:
+            assert "dmg-pop" in board_html(flashes[0])
+            return
+        state = steps[-1]
+    raise AssertionError("boss never dealt damage in eight rounds")
+
+
+# Verify unplayable hand cards render dimmed without a click handler.
+def test_hand_fan_marks_unplayable_cards() -> None:
+    state = battle_state()
+    player = state.duel.player
+    if all(card.cost <= player.energy for card in player.hand):
+        player.energy = 0
+    html = board_html(state)
+    assert "unplayable" in html
+
+
+# Verify mana crystals reflect energy against the round cap.
+def test_mana_html_fills_to_energy() -> None:
+    state = battle_state()
+    player = state.duel.player
+    html = mana_html(player, state.duel.round_number)
+    assert html.count("mana filled") == player.energy
+    assert f"{player.energy}/" in html
+
+
+# Verify pending bombs render as telegraphed tokens.
+def test_pending_tokens_show_bombs() -> None:
+    state = battle_state()
+    duel = state.duel
+    from game import PendingEffect
+
+    duel.pending.append(PendingEffect("bomb", duel.player.name, duel.enemy.name, 9, delay=2))
+    html = pending_tokens_html(duel, duel.enemy.name)
+    assert "bomb in 3" in html
+    assert pending_tokens_html(duel, duel.player.name) == ""
+
+
+# Verify the winner banner appears when the duel ends.
+def test_winner_banner_on_victory() -> None:
+    state = battle_state()
+    state.duel.enemy.hp = 0
+    html = board_html(state)
+    assert "VICTORY" in html
+    assert "restart-btn" in html
+    assert "game-over" in html
+
+
+# Verify the boss chooser is built once and falls back without a model.
+def test_ui_boss_chooser_cached_fallback(monkeypatch) -> None:
+    import ui
+
+    monkeypatch.delenv("TABRAS_AI_BOSS", raising=False)
+    monkeypatch.setattr(ui, "_boss_chooser_cache", None)
+    chooser = ui.ui_boss_chooser()
+    assert ui.ui_boss_chooser() is chooser
+    state = battle_state(seed=4)
+    from play import choose_enemy_card
+
+    assert chooser(state.duel, state.duel.enemy) == choose_enemy_card(state.duel, state.duel.enemy)
+
+
+# Verify the draft banner survives the final fade frame after pick nine.
+def test_draft_banner_after_final_pick() -> None:
+    state = new_run("Ada", "anime", "ice", seed=1)
+    for _ in range(8):
+        state = choose_draft_card(state, 0)
+    final_steps = list(choose_draft_card_steps(state, 0))
+    fade = final_steps[0]
+    assert fade.pack_fading == 0
+    assert "Deck complete" in draft_screen_html(fade)
+    assert final_steps[-1].duel is not None
+
+
+# Verify the log renders newest-first for bottom-anchored scroll.
+def test_log_html_newest_first() -> None:
+    state = battle_state()
+    html = log_html(state)
+    assert html.startswith("<div class='log-scroll'>")
+    newest = state.log[-1]
+    assert html.index(newest[:20]) < html.index(state.log[0][:10])
+    assert log_html(None) == ""

ui.py

@@ -0,0 +1,655 @@
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, replace
+from random import Random
+from typing import Sequence
+
+from boss import boss_chooser
+from budget import Card, CardSpec, EffectPlan, cost_card
+from clients import boss_client_from_env
+from draft import backbone_deck, draft_anchor_indexes, draft_order
+from game import MAX_ENERGY, DuelState, PlayerState, create_player, draw_cards, play_card_from_hand, start_round, winner
+from generator import CardPackClient, generate_pack
+from play import OPENING_HAND_SIZE, SYNERGY_COSTS, best_draft_index, choose_enemy_card, playable_indexes, shuffled_deck
+from primitives import School
+
+CARD_PANEL_COUNT = 3
+HAND_PANEL_COUNT = 10
+THEME = "dark fantasy"
+
+
+@dataclass(frozen=True)
+class RunState:
+    player_name: str
+    world: str
+    school: School
+    enemy_school: School
+    player_deck: tuple[Card, ...]
+    enemy_deck: tuple[Card, ...]
+    draft_step: int
+    draft_order: tuple[int, ...]
+    anchor_indexes: frozenset[int]
+    draft_anchors: tuple[Card, ...]
+    current_pack: tuple[Card, ...]
+    duel: DuelState | None
+    turn_order: tuple[str, ...]
+    turn_position: int
+    log: tuple[str, ...]
+    rng: Random
+    showcase: tuple[tuple[str, Card], ...] = ()
+    hp_flash: tuple[int, int] = (0, 0)
+    round_flash: int = 0
+    boss_thinking: bool = False
+    pack_fading: int = -1
+
+
+Steps = Iterator[RunState]
+
+
+# Return the next school used by the enemy.
+def enemy_school_for(school: School) -> School:
+    return {"fire": "earth", "earth": "ice", "ice": "fire"}[school]
+
+
+# Start a new run and generate the first draft pack.
+def new_run(player_name: str, world: str, school: School, client: CardPackClient | None = None, seed: int = 7) -> RunState:
+    rng = Random(seed)
+    player_deck = backbone_deck(school, world or THEME)
+    enemy_school = enemy_school_for(school)
+    order = draft_order(len(SYNERGY_COSTS), draft_anchor_indexes(len(SYNERGY_COSTS), rng))
+    state = RunState(
+        player_name=player_name or "You",
+        world=world or THEME,
+        school=school,
+        enemy_school=enemy_school,
+        player_deck=player_deck,
+        enemy_deck=(),
+        draft_step=0,
+        draft_order=order,
+        anchor_indexes=frozenset(order[:2]),
+        draft_anchors=(),
+        current_pack=(),
+        duel=None,
+        turn_order=(),
+        turn_position=0,
+        log=(f"{player_name or 'You'} enters {world or THEME}.",),
+        rng=rng,
+    )
+    return deal_next_pack(state, client)
+
+
+# Choose a draft card, yielding paced battle states once drafting completes.
+def choose_draft_card_steps(state: RunState, index: int, client: CardPackClient | None = None) -> Steps:
+    if index < 0 or index >= len(state.current_pack):
+        yield add_log(state, "That draft card is not available.")
+        return
+    selected = state.current_pack[index]
+    cost_index = state.draft_order[state.draft_step]
+    anchors = state.draft_anchors + ((selected,) if cost_index in state.anchor_indexes else ())
+    state = replace(
+        state,
+        player_deck=state.player_deck + (selected,),
+        draft_anchors=anchors,
+        draft_step=state.draft_step + 1,
+        log=state.log + (f"Drafted {selected.name}.",),
+    )
+    yield replace(state, pack_fading=index)
+    if state.draft_step >= len(state.draft_order):
+        yield from start_battle_steps(state, client)
+        return
+    yield replace(deal_next_pack(state, client), pack_fading=-1)
+
+
+# Choose a draft card and advance to the next pack or battle.
+def choose_draft_card(state: RunState, index: int, client: CardPackClient | None = None) -> RunState:
+    return last_state(choose_draft_card_steps(state, index, client))
+
+
+# Generate the next draft pack.
+def deal_next_pack(state: RunState, client: CardPackClient | None = None) -> RunState:
+    cost_index = state.draft_order[state.draft_step]
+    cost = SYNERGY_COSTS[cost_index]
+    pack = make_pack(client, state.school, state.world, state.player_deck, cost, state.draft_anchors)
+    return replace(state, current_pack=pack)
+
+
+# Start combat after drafting, yielding paced states for the opening round.
+def start_battle_steps(state: RunState, client: CardPackClient | None = None) -> Steps:
+    enemy_deck = draft_enemy_deck_for_ui(client, state.enemy_school, state.world, state.rng)
+    duel = DuelState(
+        create_player(state.player_name, shuffled_deck(state.player_deck, state.rng)),
+        create_player("Boss", shuffled_deck(enemy_deck, state.rng)),
+    )
+    draw_cards(duel.player, OPENING_HAND_SIZE)
+    draw_cards(duel.enemy, OPENING_HAND_SIZE)
+    state = replace(
+        state,
+        enemy_deck=enemy_deck,
+        current_pack=(),
+        duel=duel,
+        log=state.log + ("The boss takes the far side of the table.",),
+    )
+    yield from paced_action(state, advance_to_player_steps)
+
+
+# Draft a boss deck for the UI.
+def draft_enemy_deck_for_ui(client: CardPackClient | None, school: School, world: str, rng: Random) -> tuple[Card, ...]:
+    deck = list(backbone_deck(school, world))
+    anchors: list[Card] = []
+    anchor_indexes = draft_anchor_indexes(len(SYNERGY_COSTS), rng)
+    for cost_index in draft_order(len(SYNERGY_COSTS), anchor_indexes):
+        pack = make_pack(client, school, world, tuple(deck), SYNERGY_COSTS[cost_index], tuple(anchors))
+        selected = pack[best_draft_index(tuple(deck), pack)]
+        deck.append(selected)
+        if cost_index in anchor_indexes:
+            anchors.append(selected)
+    return tuple(deck)
+
+
+# Generate a model pack or deterministic fallback.
+def make_pack(
+    client: CardPackClient | None,
+    school: School,
+    world: str,
+    current_deck: Sequence[Card],
+    cost: int,
+    anchors: Sequence[Card] = (),
+) -> tuple[Card, ...]:
+    if client is not None:
+        try:
+            return generate_pack(client, school, world, current_deck, cost, draft_anchors=anchors)
+        except Exception:
+            pass
+    return fallback_pack(school, world, cost, anchors)
+
+
+# Return a deterministic draft pack when no model is configured.
+def fallback_pack(school: School, world: str, cost: int, anchors: Sequence[Card] = ()) -> tuple[Card, ...]:
+    plans = fallback_plans(school, anchors)
+    return tuple(cost_card(CardSpec(name, cost, school, world, effects, flavor, art)) for name, effects, flavor, art in plans)
+
+
+# Return fallback effect plans for a school.
+def fallback_plans(school: School, anchors: Sequence[Card]) -> tuple[tuple[str, tuple[EffectPlan, ...], str, str], ...]:
+    if school == "fire":
+        return (
+            ("Cinder Rush", (EffectPlan("deal"), EffectPlan("burn")), "Heat hits first, then keeps biting.", "burning playing card on a wooden table"),
+            ("Fuse Prayer", (EffectPlan("bomb"),), "A delayed blast tucked under the enemy's next breath.", "black powder sigil glowing under ash"),
+            ("Kindling Draw", (EffectPlan("draw"), EffectPlan("deal")), "The next spark finds your hand.", "embers curling into paper cards"),
+        )
+    if school == "ice":
+        return (
+            ("Glass Tempo", (EffectPlan("initiative"), EffectPlan("vulnerable")), "The table freezes one heartbeat ahead.", "frosted hourglass over cards"),
+            ("Needle Flurry", (EffectPlan("multi_hit"),), "Small cuts find the opening.", "ice needles striking a portrait frame"),
+            ("Crack in Winter", (EffectPlan("vulnerable"), EffectPlan("conditional")), "A weakness appears where the frost thins.", "blue crack in a frozen shield"),
+        )
+    if any(effect.primitive_id == "scaling" for card in anchors for effect in card.effects):
+        return (
+            ("Stone Intake", (EffectPlan("block"), EffectPlan("scaling")), "The shield drinks the blow and answers later.", "stone shield lit with stored gold"),
+            ("Table Ward", (EffectPlan("block"), EffectPlan("ward")), "A quiet wall between you and ruin.", "earthen ward on an old desk"),
+            ("Buried Leverage", (EffectPlan("draw"), EffectPlan("block")), "Patience becomes pressure.", "roots lifting cards from soil"),
+        )
+    return (
+        ("Stone Intake", (EffectPlan("block"), EffectPlan("scaling")), "The shield drinks the blow and answers later.", "stone shield lit with stored gold"),
+        ("Gravemoss Guard", (EffectPlan("block"), EffectPlan("weak")), "The ground takes their strength first.", "mossy shield under candlelight"),
+        ("Cairn Echo", (EffectPlan("scaling"),), "Stored force returns with interest.", "runes glowing in cracked stone"),
+    )
+
+
+# Play one hand card, yielding paced states for the boss response.
+def play_hand_card_steps(state: RunState, index: int) -> Steps:
+    if state.duel is None or index < 0 or index >= len(state.duel.player.hand):
+        yield state
+        return
+    card = state.duel.player.hand[index]
+    if card.cost > state.duel.player.energy:
+        yield add_log(state, f"{card.name} needs {card.cost} energy.")
+        return
+    yield from paced_action(state, resolve_card_steps, index)
+
+
+# Play one player hand card by index.
+def play_hand_card(state: RunState, index: int) -> RunState:
+    return last_state(play_hand_card_steps(state, index))
+
+
+# Pass the turn, yielding paced states for the boss response.
+def pass_turn_steps(state: RunState) -> Steps:
+    if state.duel is None or winner(state.duel):
+        yield state
+        return
+    yield from paced_action(state, resolve_pass_steps)
+
+
+# Pass the current player turn.
+def pass_turn(state: RunState) -> RunState:
+    return last_state(pass_turn_steps(state))
+
+
+# Yield action steps stamped with per-step damage and round-turnover flashes.
+def paced_action(state: RunState, steps_fn: Callable[..., Steps], *args: object) -> Steps:
+    assert state.duel is not None
+    duel = state.duel
+    player_hp, enemy_hp, round_seen = duel.player.hp, duel.enemy.hp, duel.round_number
+    fresh = replace(state, showcase=(), hp_flash=(0, 0), round_flash=0, boss_thinking=False)
+    for step in steps_fn(fresh, *args):
+        assert step.duel is not None
+        flash = (max(0, player_hp - step.duel.player.hp), max(0, enemy_hp - step.duel.enemy.hp))
+        turned = step.duel.round_number if step.duel.round_number != round_seen else 0
+        player_hp, enemy_hp, round_seen = step.duel.player.hp, step.duel.enemy.hp, step.duel.round_number
+        yield replace(step, hp_flash=flash, round_flash=turned)
+
+
+# Resolve one affordable hand card; the turn ends only when the player ends it.
+def resolve_card_steps(state: RunState, index: int) -> Steps:
+    assert state.duel is not None
+    player = state.duel.player
+    played = play_card_from_hand(state.duel, player, index)
+    state = show_play(state, player.name, played)
+    state = add_log(state, f"{player.name} plays {played.name}: {played.rules_text()}")
+    if winner(state.duel):
+        yield add_log(state, f"Winner: {winner(state.duel)}")
+        return
+    yield state
+
+
+# Resolve a pass by spending remaining energy, then advance.
+def resolve_pass_steps(state: RunState) -> Steps:
+    assert state.duel is not None
+    state.duel.player.energy = 0
+    state = add_log(state, f"{state.duel.player.name} passes.")
+    yield state
+    yield from advance_after_player_steps(state)
+
+
+# Yield combat steps after the player has ended their action.
+def advance_after_player_steps(state: RunState) -> Steps:
+    assert state.duel is not None
+    if winner(state.duel):
+        yield state
+        return
+    position = state.turn_position + 1
+    if position < len(state.turn_order) and state.turn_order[position] == state.duel.enemy.name:
+        state = yield from boss_turn_steps(replace(state, turn_position=position))
+    if winner(state.duel):
+        yield add_log(state, f"Winner: {winner(state.duel)}")
+        return
+    yield from advance_to_player_steps(state)
+
+
+# Yield round turnovers until the player can act.
+def advance_to_player_steps(state: RunState) -> Steps:
+    assert state.duel is not None
+    if winner(state.duel):
+        yield state
+        return
+    while not winner(state.duel):
+        order = start_round(state.duel, state.rng)
+        header = (
+            f"Round {state.duel.round_number}: {' then '.join(order)} · "
+            f"{state.duel.player.name} {state.duel.player.hp} HP · Boss {state.duel.enemy.hp} HP"
+        )
+        state = replace(state, turn_order=order, turn_position=0, log=state.log + (header,))
+        yield state
+        if order[0] == state.duel.player.name:
+            return
+        state = yield from boss_turn_steps(state)
+        if len(order) > 1 and order[1] == state.duel.player.name and not winner(state.duel):
+            state = replace(state, turn_position=1)
+            yield state
+            return
+    yield add_log(state, f"Winner: {winner(state.duel)}")
+
+
+_boss_chooser_cache = None
+
+
+# Return the boss chooser, wiring the env-configured boss model once.
+def ui_boss_chooser():
+    global _boss_chooser_cache
+    if _boss_chooser_cache is None:
+        _boss_chooser_cache = boss_chooser(boss_client_from_env(), choose_enemy_card)
+    return _boss_chooser_cache
+
+
+# Yield boss plays one card at a time with thinking pauses; return the final state.
+def boss_turn_steps(state: RunState) -> Steps:
+    assert state.duel is not None
+    chooser = ui_boss_chooser()
+    played_any = False
+    while playable_indexes(state.duel.enemy):
+        yield replace(state, boss_thinking=True)
+        choice = chooser(state.duel, state.duel.enemy)
+        if choice is None:
+            state.duel.enemy.energy = 0
+            state = add_log(state, "Boss passes.")
+            yield state
+            return state
+        card = play_card_from_hand(state.duel, state.duel.enemy, choice)
+        played_any = True
+        state = show_play(state, state.duel.enemy.name, card)
+        state = add_log(state, f"Boss plays {card.name}: {card.rules_text()}")
+        yield state
+        if winner(state.duel):
+            return state
+    if not played_any:
+        state = add_log(state, "Boss has no playable cards.")
+    state.duel.enemy.energy = 0
+    return state
+
+
+# Record one played card for the battlefield showcase.
+def show_play(state: RunState, owner: str, card: Card) -> RunState:
+    return replace(state, showcase=state.showcase + ((owner, card),))
+
+
+# Return the last state from an action generator.
+def last_state(steps: Steps) -> RunState:
+    state = None
+    for state in steps:
+        pass
+    assert state is not None
+    return state
+
+
+# Add one line to the turn log.
+def add_log(state: RunState, line: str) -> RunState:
+    return replace(state, log=(state.log + (line,))[-80:])
+
+
+# Return HTML for one card face with a blank art slot for future generation.
+def card_html(card: Card | None, classes: str = "", style: str = "", onclick: str = "") -> str:
+    if card is None:
+        return "<div class='tabras-card empty'></div>"
+    return (
+        f'<div class="tabras-card school-{card.school} {classes}" style="{style}" onclick="{onclick}">'
+        f"<div class='card-cost'>{card.cost}</div>"
+        f"<div class='card-name'>{escape_html(card.name)}</div>"
+        "<div class='card-art'></div>"
+        f"<div class='card-rules'>{escape_html(card.rules_text())}</div>"
+        f"<div class='card-flavor'>{escape_html(card.flavor)}</div>"
+        "</div>"
+    )
+
+
+# Return HTML for the full draft screen.
+def draft_screen_html(state: RunState | None) -> str:
+    if state is None or state.duel is not None or not state.current_pack:
+        return ""
+    if state.draft_step >= len(state.draft_order):
+        banner = "<div class='draft-banner'><h2>Deck complete</h2><p>The boss shuffles its deck&hellip;</p></div>"
+    else:
+        cost_index = state.draft_order[state.draft_step]
+        kind = "Anchor pick" if cost_index in state.anchor_indexes else "Pick"
+        banner = (
+            f"<div class='draft-banner'><h2>{kind} {state.draft_step + 1} of {len(state.draft_order)}</h2>"
+            f"<p>{escape_html(state.player_name)} of {escape_html(state.world)} &mdash; {school_mark(state.school)}</p></div>"
+        )
+    cards = "".join(
+        draft_card_html(state, index, card) for index, card in enumerate(state.current_pack)
+    )
+    return f"<div class='draft-board'>{banner}<div class='draft-pack'>{cards}</div>{deck_strip_html(state)}</div>"
+
+
+# Return one draft card, fading the old pack out after a pick.
+def draft_card_html(state: RunState, index: int, card: Card) -> str:
+    if state.pack_fading < 0:
+        return card_html(card, "draft-card", "", f"tabrasClick('draft-btn-{index}')")
+    chosen = index == state.pack_fading
+    return card_html(card, "draft-card picked" if chosen else "draft-card fading")
+
+
+# Return a mini-chip strip of the deck drafted so far.
+def deck_strip_html(state: RunState) -> str:
+    chips = "".join(
+        f"<span class='deck-chip{' anchor' if card in state.draft_anchors else ''}'>"
+        f"<b>{card.cost}</b> {escape_html(card.name)}</span>"
+        for card in state.player_deck
+    )
+    return f"<div class='deck-strip'><span class='deck-strip-label'>Deck {len(state.player_deck)}/15</span>{chips}</div>"
+
+
+# Return HTML for the full Hearthstone-style battle board.
+def board_html(state: RunState | None) -> str:
+    if state is None or state.duel is None:
+        return ""
+    duel = state.duel
+    over = " game-over" if winner(duel) else ""
+    quake = " quake" if state.hp_flash[0] >= 4 else ""
+    thinking = " thinking" if state.boss_thinking else ""
+    return (
+        f"<div class='board{over}{quake}{thinking}'>"
+        f"{enemy_zone_html(state)}"
+        f"{battlefield_html(state)}"
+        f"{player_zone_html(state)}"
+        f"{round_splash_html(state)}"
+        f"{winner_banner_html(state)}"
+        "</div>"
+    )
+
+
+# Return the enemy side of the board.
+def enemy_zone_html(state: RunState) -> str:
+    assert state.duel is not None
+    enemy = state.duel.enemy
+    thinking = "<div class='boss-thinking'>Boss is scheming&hellip;</div>" if state.boss_thinking else ""
+    return (
+        "<div class='zone enemy-zone'>"
+        f"<div class='zone-center'>{enemy_hand_html(enemy)}{hero_html(enemy, state.enemy_school, 'Boss', True, state.hp_flash[1])}{thinking}</div>"
+        f"{piles_html(enemy)}"
+        "</div>"
+    )
+
+
+# Return the player side of the board.
+def player_zone_html(state: RunState) -> str:
+    assert state.duel is not None
+    player = state.duel.player
+    return (
+        "<div class='zone player-zone'>"
+        "<div class='zone-center'>"
+        f"{hero_html(player, state.school, state.player_name, False, state.hp_flash[0])}"
+        f"{mana_html(player, state.duel.round_number)}"
+        f"{hand_fan_html(player)}"
+        "</div>"
+        f"{piles_html(player)}"
+        "</div>"
+    )
+
+
+# Return the middle strip with pending effects, played cards, round banner, and end turn.
+def battlefield_html(state: RunState) -> str:
+    assert state.duel is not None
+    duel = state.duel
+    over = winner(duel) is not None
+    pulse = " pulse" if not over and not playable_indexes(duel.player) else ""
+    waiting = "the boss responds" if state.boss_thinking else "your turn"
+    banner = "duel over" if over else waiting
+    end_turn = "" if over else f"<button class='end-turn{pulse}' onclick=\"tabrasClick('end-turn-btn')\">END TURN</button>"
+    return (
+        "<div class='battlefield'>"
+        f"<div class='pending-row'>{pending_tokens_html(duel, duel.enemy.name)}</div>"
+        f"{showcase_html(state)}"
+        f"<div class='round-banner'>Round {duel.round_number} &mdash; {banner}</div>"
+        f"{end_turn}"
+        f"<div class='pending-row'>{pending_tokens_html(duel, duel.player.name)}</div>"
+        "</div>"
+    )
+
+
+# Return the cards played since the last player action, labeled, newest animated in.
+def showcase_html(state: RunState) -> str:
+    assert state.duel is not None
+    enemy = state.duel.enemy.name
+    last = len(state.showcase) - 1
+    slots = []
+    for index, (owner, card) in enumerate(state.showcase):
+        boss = owner == enemy
+        fresh = " fresh" if index == last else ""
+        slots.append(
+            f"<div class='play-slot{fresh}'>"
+            f"<span class='play-label {'boss' if boss else 'you'}'>{'Boss played' if boss else 'You played'}</span>"
+            f"{card_html(card, 'played-card ' + ('enemy-play' if boss else 'player-play'))}"
+            "</div>"
+        )
+    return f"<div class='showcase'>{''.join(slots)}</div>"
+
+
+# Return the darkened round-turnover splash announcing initiative.
+def round_splash_html(state: RunState) -> str:
+    if not state.round_flash or state.duel is None:
+        return ""
+    first = state.turn_order[0] if state.turn_order else state.duel.player.name
+    you_first = first == state.duel.player.name
+    line = "YOU GO FIRST" if you_first else "BOSS GOES FIRST"
+    return (
+        "<div class='round-splash'>"
+        f"<div class='splash-round'>ROUND {state.round_flash}</div>"
+        f"<div class='splash-initiative {'you' if you_first else 'boss'}'>{line}</div>"
+        "</div>"
+    )
+
+
+# Return a hero portrait with HP gem, defenses, status chips, and damage pop.
+def hero_html(player: PlayerState, school: School, title: str, enemy: bool, damage: int = 0) -> str:
+    block = f"<div class='block-gem'>{player.block}</div>" if player.block else ""
+    ward = f"<div class='ward-gem'>{player.ward}</div>" if player.ward else ""
+    pop = f"<div class='dmg-pop'>-{damage}</div>" if damage else ""
+    hit = " hit" if damage else ""
+    return (
+        f"<div class='hero {'enemy' if enemy else 'you'}'>"
+        f"<div class='hero-frame{hit}'><div class='hero-face'>{school_mark(school)}</div>"
+        f"<div class='hp-gem'>{player.hp}</div>{block}{ward}{pop}</div>"
+        f"<div class='hero-name'>{escape_html(title)}</div>"
+        f"{status_chips_html(player)}"
+        "</div>"
+    )
+
+
+# Return status chips for charge, weak, and vulnerable.
+def status_chips_html(player: PlayerState) -> str:
+    chips = []
+    if player.shield_charge:
+        chips.append(f"<span class='chip charge'>Charge {player.shield_charge}</span>")
+    if player.weak:
+        chips.append(f"<span class='chip weak'>Weak {player.weak} ({player.weak_turns}t)</span>")
+    if player.vulnerable:
+        chips.append(f"<span class='chip vuln'>Vulnerable +{player.vulnerable} ({player.vulnerable_turns}t)</span>")
+    return f"<div class='chips'>{''.join(chips)}</div>"
+
+
+# Return the mana crystal bar for the player.
+def mana_html(player: PlayerState, round_number: int) -> str:
+    cap = min(MAX_ENERGY, round_number)
+    total = max(cap, player.energy)
+    gems = "".join(f"<span class='mana{' filled' if index < player.energy else ''}'></span>" for index in range(total))
+    return f"<div class='mana-bar'>{gems}<span class='mana-count'>{player.energy}/{cap}</span></div>"
+
+
+# Return deck and discard piles with a fatigue warning when decked out.
+def piles_html(player: PlayerState) -> str:
+    fatigue = f"<div class='fatigue-warn'>Fatigue {player.fatigue}</div>" if not player.deck else ""
+    return (
+        "<div class='piles'>"
+        f"<div class='pile deck'><span>{len(player.deck)}</span><label>Deck</label>{fatigue}</div>"
+        f"<div class='pile discard'><span>{len(player.discard)}</span><label>Discard</label></div>"
+        "</div>"
+    )
+
+
+# Return the face-down enemy hand fan.
+def enemy_hand_html(enemy: PlayerState) -> str:
+    backs = "".join("<div class='enemy-card-back'></div>" for _ in enemy.hand[:HAND_PANEL_COUNT])
+    return f"<div class='enemy-hand'>{backs}</div>"
+
+
+# Return the fanned, clickable player hand.
+def hand_fan_html(player: PlayerState) -> str:
+    cards = player.hand[:HAND_PANEL_COUNT]
+    middle = (len(cards) - 1) / 2
+    pieces = []
+    for index, card in enumerate(cards):
+        offset = index - middle
+        style = f"--rot:{offset * 3.5:.1f}deg;--ty:{abs(offset) * 8:.0f}px;z-index:{index + 1};"
+        playable = card.cost <= player.energy
+        classes = "hand-card" if playable else "hand-card unplayable"
+        onclick = f"tabrasPlay('hand-btn-{index}', this)" if playable else ""
+        pieces.append(card_html(card, classes, style, onclick))
+    return f"<div class='hand-fan'>{''.join(pieces)}</div>"
+
+
+# Return telegraphed pending-effect tokens aimed at one player.
+def pending_tokens_html(duel: DuelState, target: str) -> str:
+    tokens = []
+    for effect in duel.pending:
+        if effect.target != target:
+            continue
+        if effect.primitive_id == "bomb":
+            tokens.append(f"<div class='token bomb'><b>{effect.amount}</b><span>bomb in {effect.delay + 1}</span></div>")
+        else:
+            tokens.append(f"<div class='token burn'><b>{effect.amount}</b><span>burn &times;{max(effect.duration, 1)}</span></div>")
+    return "".join(tokens)
+
+
+# Return the end-of-duel banner with a new-run control.
+def winner_banner_html(state: RunState) -> str:
+    assert state.duel is not None
+    win = winner(state.duel)
+    if win is None:
+        return ""
+    text = "VICTORY" if win == state.duel.player.name else ("DRAW" if win == "draw" else "DEFEAT")
+    return (
+        f"<div class='winner-banner {text.lower()}'><h1>{text}</h1>"
+        "<button class='new-run' onclick=\"tabrasClick('restart-btn')\">New Run</button></div>"
+    )
+
+
+# Return the battle log as styled entries, newest at the bottom.
+def log_html(state: RunState | None) -> str:
+    if state is None:
+        return ""
+    entries = "".join(log_entry_html(line) for line in reversed(state.log[-24:]))
+    return f"<div class='log-scroll'>{entries}</div>"
+
+
+# Return one styled log entry, breaking plays into owner, card, and effect.
+def log_entry_html(line: str) -> str:
+    kind = log_kind(line)
+    if " plays " in line and ": " in line:
+        head, rules = line.split(": ", 1)
+        owner, card_name = head.split(" plays ", 1)
+        return (
+            f"<div class='log-line {kind}'><span class='log-owner'>{escape_html(owner)} played</span>"
+            f"<b>{escape_html(card_name)}</b><span class='log-rules'>{escape_html(rules)}</span></div>"
+        )
+    return f"<div class='log-line {kind}'>{escape_html(line)}</div>"
+
+
+# Classify one log line for styling.
+def log_kind(line: str) -> str:
+    if line.startswith("Round "):
+        return "log-round"
+    if line.startswith("Winner:"):
+        return "log-winner"
+    if " plays " in line:
+        return "log-play log-boss" if line.startswith("Boss") else "log-play log-you"
+    if "Drafted" in line:
+        return "log-draft"
+    if "passes" in line or "no playable" in line:
+        return "log-muted"
+    return "log-info"
+
+
+# Return the school display mark.
+def school_mark(school: str) -> str:
+    return {"fire": "Fire", "ice": "Ice", "earth": "Earth"}.get(school, school.title())
+
+
+# Escape HTML for generated card text.
+def escape_html(text: str) -> str:
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#x27;")
+    )

uv.lock

@@ -0,0 +1,3 @@
+version = 1
+revision = 3
+requires-python = ">=3.10"