solvi arcade: game agents that explain every move, running in your browser

README.md

@@ -1,10 +1,74 @@
 ---
-title: Arcade
-emoji: 🚀
-colorFrom: pink
+title: solvi arcade
+emoji: 🕹️
+colorFrom: purple
 colorTo: yellow
 sdk: static
+app_file: index.html
 pinned: false
+license: apache-2.0
+short_description: Explainable game agents that run in your browser
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# solvi arcade (runs in your browser)
+
+Game agents built with [solvi](https://github.com/solvi-ai/solvi) from small Python functions, a few rules and hard
+checks. They play well, and every move comes with its reason: the rule's inputs, the facts computed this turn, and which
+hard check fired, if any. No models, and **no server**: the page runs Python in the visitor's browser with
+[Gradio-Lite](https://www.gradio.app/guides/gradio-lite) (Pyodide, Python compiled to WebAssembly). solvi is pure Python
+on numpy/scipy, so it installs from PyPI straight into the browser.
+
+The first visit downloads the Python runtime with numpy, scipy, Gradio and solvi (about 20–30 MB, once; later visits use
+the browser cache). Write your own decision task in the [solvi playground](https://huggingface.co/spaces/solvi-ai/playground).
+
+| Tab | What you see |
+|---|---|
+| ❌⭕ Tic-tac-toe | The catalog from `examples/05_tic_tac_toe.py` (vendored), with an extra `reason` rule that names the move (win, block, fork, forcing, center ...). A "you can't beat it" counter and an "explain the position" view. |
+| 👻 Ghost maze | Pac is a catalog of BFS functions plus one scoring rule. The hard check `greedy_is_safe` blocks any step into a ghost's reach while a safer move exists. Turn the check off, take over with the arrows, run the benchmark in the browser. |
+| 🃏 Card fusion lab | Fuse two weapon cards with BLEND or DOMINANT. A balance catalog clamps slow, lifesteal and cooldown (hard checks) and rescales damage when the power is out of band (soft check). |
+| 🛠️ Build your own bot | Edit the maze agent's scoring function and run 20 seeded games against the default bot, in your own browser. |
+
+## Maze benchmark (100 seeded games, same scoring rule and ghosts)
+
+| agent | games cleared | avg score | dots eaten | lives lost (of 3) |
+|---|---|---|---|---|
+| hard safety check ON | 59% | 764 | 94% | 1.95 |
+| hard safety check OFF | 4% | 531 | 76% | 2.96 |
+
+Native Python computes this in about 7 s on one CPU core; the browser, on a button click, in about 20 s, with the same
+numbers.
+
+## Layout
+
+- `index.html`: loads `@gradio/lite@5.45.0` from jsDelivr, lists the requirement (`solvi>=0.1.1`) and mounts `app.py`
+  and `games/*.py` by URL.
+- `app.py`: the Gradio 5 UI (theme and CSS in `gr.Blocks(...)`).
+- `games/tictactoe.py`, `games/maze.py`, `games/fusion.py`: pure game logic and solvi catalogs, the same as in the
+  server version of this Space. `games/_ttt_catalog.py` is a vendored copy of the tic-tac-toe example catalog.
+- `games/explain.py`: renders a solvi `Response` as a "why" card.
+- `games/sandbox.py`: runs the visitor's bot code in-process, in a fresh namespace, under a `sys.settrace` guard: a call
+  that runs more than 200,000 lines of the bot's code (an infinite loop), or a run longer than 30 s, is stopped. It
+  protects against runaway Python loops, not against a loop inside C code, and it is not a security sandbox (the code
+  runs in the visitor's own browser tab).
+
+### Differences from the server version (`../arcade`)
+
+- No threads or subprocesses in Pyodide: the maze benchmark runs on a button click (20 or 100 games) instead of at
+  startup, and the bot runs in-process with the guard above instead of a resource-limited subprocess.
+- The tic-tac-toe counter is per tab (there is no shared server to count everyone's games).
+- "Play 50 ticks" uses an async generator with `asyncio.sleep` (a blocking `time.sleep` would stall the worker).
+
+### Workaround in `index.html`
+
+Gradio-Lite 5.45.0 (the latest release) installs gradio 5.45 with micropip, whose resolver is greedy. With today's PyPI
+it picks `huggingface-hub` 1.x/2.x for `gradio_client` and then fails on gradio's `huggingface-hub<1.0` pin (also
+`anyio<5`, ...), so the app does not start. `index.html` wraps the web worker and filters PyPI's simple index to files
+uploaded before the Gradio-Lite release (2025-09-10), except `solvi`. If a future Gradio-Lite release fixes this, the
+wrapper script can be removed.
+
+## Run locally
+
+```bash
+cd solvi/spaces/arcade-lite
+python -m http.server 8080      # then open http://localhost:8080
+```

app.py

@@ -0,0 +1,614 @@
+"""solvi arcade (browser edition) — game agents built from small Python functions, rules and hard checks, explaining
+every move. Runs in the visitor's browser with Gradio-Lite (Pyodide): index.html mounts this file and games/*.py.
+
+No threads and no subprocesses in Pyodide: the benchmark runs on a button click, and "Build your own bot" runs the code
+in-process under a sys.settrace guard (games/sandbox.py).
+
+Local run with a normal Python (from solvi/spaces/arcade-lite):  PYTHONPATH=../../src python app.py"""
+from __future__ import annotations
+
+import asyncio
+import html
+import random
+import time
+
+import gradio as gr
+from games import fusion, maze, sandbox, tictactoe
+from games.explain import why_html
+
+REPO = "https://github.com/solvi-ai/solvi"
+PLAYGROUND = "https://huggingface.co/spaces/solvi-ai/playground"
+
+# ====================================================================================================================
+# Tic-tac-toe
+# ====================================================================================================================
+
+CELL_NAMES = ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"]
+EMPTY = " "
+
+
+def _ttt_counter(stats):
+    return (f"### You can't beat it\n"
+            f"**You, in this tab:** {stats['games']} games · agent won {stats['agent_wins']} · draws {stats['draws']} · "
+            f"**agent lost {stats['agent_losses']}**")
+
+
+def _ttt_cells(game):
+    out = []
+    for i, ch in enumerate(game.board):
+        label = EMPTY if ch == "." else ("❌" if ch == "X" else "⭕")
+        out.append(gr.Button(value=label, variant="primary" if i == game.last_agent_cell else "secondary"))
+    return out
+
+
+def _ttt_status(game):
+    if game.over:
+        return {"agent": "### solvi wins. Try again?", "human": "### You beat solvi! (please report a bug)",
+                "draw": "### Draw. That is the best anyone can do."}[game.result]
+    return f"### Your move ({'❌' if game.human == 'X' else '⭕'})"
+
+
+def _ttt_why(game, resp):
+    if resp is None:
+        return "<div class='sv-card sv-dim'>solvi has not moved yet. It explains each of its moves here.</div>"
+    r = resp["move"]
+    if r.answer in (None, "none"):
+        return why_html(resp, tictactoe.cat, ["move", "reason"], title="solvi could not move")
+    c = int(r.answer)
+    reason = resp["reason"].answer
+    title = f"solvi plays {CELL_NAMES[c]} (cell {c}) — {tictactoe.REASONS[reason]}"
+    return why_html(resp, tictactoe.cat, ["move", "reason"], title=title)
+
+
+def _ttt_position(game, explain):
+    if not explain:
+        return gr.HTML(visible=False)
+    me = game.turn
+    resp = tictactoe.explain_position(game.board, me)
+    side = "you" if me == game.human else "solvi"
+    title = (f"Position seen from the side to move ({'❌' if me == 'X' else '⭕'}, {side}) — "
+             f"every fact the catalog computes, and the move solvi would play here")
+    if game.over:
+        title = "Game over: the hard check board_valid refuses to pick a move on a finished board"
+    return gr.HTML(why_html(resp, tictactoe.cat, ["move", "reason", "outcome"], title=title), visible=True)
+
+
+def _ttt_count(game, stats):
+    if not game.over or game.counted:
+        return
+    game.counted = True
+    key = {"agent": "agent_wins", "human": "agent_losses", "draw": "draws"}[game.result]
+    stats["games"] += 1
+    stats[key] += 1
+
+
+def _ttt_outputs(game, resp, stats, explain, status=None):
+    return (*_ttt_cells(game), status or _ttt_status(game), _ttt_why(game, resp), _ttt_position(game, explain),
+            _ttt_counter(stats), game, resp, stats)
+
+
+def ttt_new(side, stats, explain):
+    game, resp = tictactoe.new_game("X" if side.startswith("X") else "O")
+    return _ttt_outputs(game, resp, stats, explain)
+
+
+def ttt_click(i, game, resp, stats, explain):
+    err = tictactoe.human_move(game, i)
+    if err:
+        return _ttt_outputs(game, resp, stats, explain, status=f"### {err}")
+    if not game.over:
+        resp = tictactoe.agent_move(game)
+    _ttt_count(game, stats)
+    return _ttt_outputs(game, resp, stats, explain)
+
+
+def ttt_explain(game, explain):
+    return _ttt_position(game, explain)
+
+
+# ====================================================================================================================
+# Ghost maze
+# ====================================================================================================================
+
+CAT_ON, SYS_ON = maze.build_system(True)
+CAT_OFF, SYS_OFF = maze.build_system(False)
+PAC_ANGLE = {"UP": 0, "RIGHT": 90, "DOWN": 180, "LEFT": 270, None: 90}
+NATIVE_BENCH = {"with_check": {"win_rate": 0.59, "avg_score": 764, "avg_dots_pct": 0.94, "avg_deaths": 1.95},
+                "without_check": {"win_rate": 0.04, "avg_score": 531, "avg_dots_pct": 0.76, "avg_deaths": 2.96}}
+BENCH_SIZES = {"20 games (about 8 s)": 20, "100 games (about 20 s)": 100}
+
+
+def _bench_rows(b, vetoes=True):
+    rows = []
+    for key, label in (("with_check", "hard safety check **ON**"), ("without_check", "hard safety check OFF")):
+        s = b[key]
+        rows.append(f"| {label} | **{s['win_rate'] * 100:.0f}%** | {s['avg_score']:.0f} | {s['avg_dots_pct'] * 100:.0f}% | "
+                    f"{s['avg_deaths']:.2f} |" + (f" {s['avg_forced']:.1f} |" if vetoes else ""))
+    return "\n".join(rows)
+
+
+def bench_native_markdown():
+    return ("#### Benchmark: 100 seeded games, same scoring rule, same ghosts\n"
+            "| agent | games cleared | avg score | dots eaten | lives lost (of 3) |\n|---|---|---|---|---|\n" +
+            _bench_rows(NATIVE_BENCH, vetoes=False) +
+            "\n\n<span class='sv-dim'>Measured with native Python (about 7 s on one CPU core). "
+            f"A game is cleared when Pac eats all {maze.TOTAL_DOTS} dots before losing 3 lives (limit {maze.MAX_TICKS} ticks). "
+            "The only difference between the rows is one hard check. Press the button to recompute it here, in your "
+            "browser.</span>")
+
+
+def bench_run(size):
+    n = BENCH_SIZES.get(size, 20)
+    t0 = time.time()
+    b = maze.benchmark(n)
+    dt = time.time() - t0
+    return (f"#### Benchmark: {n} seeded games, computed in your browser in {dt:.1f} s\n"
+            "| agent | games cleared | avg score | dots eaten | lives lost (of 3) | vetoes per game |\n"
+            "|---|---|---|---|---|---|\n" + _bench_rows(b) +
+            "\n\n<span class='sv-dim'>Seeds 0 to " + str(n - 1) + ", the same as the native run. "
+            "The native numbers over 100 games: check ON 59% cleared, avg score 764; check OFF 4%, avg score 531.</span>")
+
+
+def board_html(game, resp=None, show_danger=False):
+    ghosts = {}
+    for gh in game.ghosts:
+        ghosts.setdefault(gh.pos, gh)
+    danger = set()
+    if show_danger and not game.over:
+        # the agent's ghost_reach fact; computed here too, because with the check OFF the flow does not need it
+        reach = resp.values.get("ghost_reach") if resp is not None else None
+        if reach is None:
+            reach = {n for gh in game.ghosts for _, n in maze.open_neighbors(gh.pos)} | {gh.pos for gh in game.ghosts}
+        danger = set(map(tuple, reach))
+    cells = []
+    for r in range(maze.H):
+        for c in range(maze.W):
+            cell = (r, c)
+            if cell in maze.WALLS:
+                cells.append("<div class='mz c-wall'></div>")
+                continue
+            cls = "mz c-open" + (" c-danger" if cell in danger else "")
+            inner = ""
+            if cell == game.pac:
+                a = PAC_ANGLE[game.last_move] - 35
+                inner = (f"<div class='mz-pac' style='background:conic-gradient(from {a}deg, transparent 0deg 70deg, "
+                         f"#ffd400 70deg 360deg)'></div>")
+            elif cell in ghosts:
+                gh = ghosts[cell]
+                inner = f"<div class='mz-ghost' style='background:{gh.color}' title='{gh.name}'>👀</div>"
+            elif cell in game.dots:
+                inner = "<div class='mz-dot'></div>"
+            cells.append(f"<div class='{cls}'>{inner}</div>")
+    banner = ""
+    if game.over:
+        banner = ("<div class='mz-banner mz-win'>CLEARED! 🎉</div>" if game.won
+                  else "<div class='mz-banner mz-lose'>GAME OVER</div>")
+    return (f"<div class='mz-wrap'>{banner}<div class='mz-grid' style='grid-template-columns:repeat({maze.W}, 1fr)'>"
+            f"{''.join(cells)}</div></div>")
+
+
+def maze_stats(game):
+    eaten = maze.TOTAL_DOTS - len(game.dots)
+    return (f"**Score** {game.score} &nbsp;·&nbsp; **Lives** {'❤️' * game.lives or '—'} &nbsp;·&nbsp; "
+            f"**Dots** {eaten}/{maze.TOTAL_DOTS} &nbsp;·&nbsp; **Tick** {game.tick} &nbsp;·&nbsp; "
+            f"**hard-check vetoes** {game.forced} &nbsp;·&nbsp; seed {game.seed}")
+
+
+def _maze_why(resp, move, note, safety, who="solvi"):
+    if resp is None:
+        return "<div class='sv-card sv-dim'>Press Step or Play to let the solvi agent move. Each tick is explained here.</div>"
+    cat = CAT_ON if safety else CAT_OFF
+    qs = ["move", "fallback"] if safety else ["move"]
+    if who == "you":
+        title = f"You played {move}. solvi would have played {note}."
+    else:
+        title = "solvi: " + maze.describe(move, resp, note)
+    return why_html(resp, cat, qs, title=title)
+
+
+def _maze_outputs(game, resp, move, note, safety, show_danger, who="solvi"):
+    log = "\n".join(reversed(game.log[-40:]))
+    return board_html(game, resp, show_danger), maze_stats(game), log, _maze_why(resp, move, note, safety, who), game
+
+
+def _event_suffix(ev):
+    return {"dot": "", "caught": "  ✖ caught by a ghost!", "won": "  ★ all dots eaten!", "over": "  ✖ game over"}.get(ev, "")
+
+
+def _agent_tick(game, safety):
+    system = SYS_ON if safety else SYS_OFF
+    mv, resp, note = maze.agent_decide(system, game, safety)
+    line = f"t{game.tick + 1:03d} " + maze.describe(mv, resp, note)
+    ev = maze.step(game, mv, note)
+    game.log.append(line + _event_suffix(ev))
+    return mv, resp, note
+
+
+def maze_step(game, safety, show_danger):
+    if game.over:
+        return _maze_outputs(game, None, None, None, safety, show_danger)
+    mv, resp, note = _agent_tick(game, safety)
+    return _maze_outputs(game, resp, mv, note, safety, show_danger)
+
+
+async def maze_play(game, safety, show_danger):
+    resp = mv = note = None
+    for _ in range(50):
+        if game.over:
+            break
+        mv, resp, note = _agent_tick(game, safety)
+        yield _maze_outputs(game, resp, mv, note, safety, show_danger)
+        await asyncio.sleep(0.07)       # time.sleep would block the browser's Python worker
+    yield _maze_outputs(game, resp, mv, note, safety, show_danger)
+
+
+def maze_reset(seed, safety, show_danger):
+    game = maze.new_game(int(seed or 0))
+    game.log.append(f"new game, seed {game.seed}: {maze.TOTAL_DOTS} dots, 3 ghosts, 3 lives")
+    return _maze_outputs(game, None, None, None, safety, show_danger)
+
+
+def maze_human(move, game, safety, show_danger):
+    if game.over:
+        return _maze_outputs(game, None, None, None, safety, show_danger)
+    system = SYS_ON if safety else SYS_OFF
+    smv, resp, note = maze.agent_decide(system, game, safety)
+    v = resp.values
+    line = (f"t{game.tick + 1:03d} you {move} (ghost {v['ghost_dist'].get(move, 'wall')} away) — "
+            f"solvi would play {smv}" + (" (hard check vetoed its first choice)" if note == "forced" else ""))
+    ev = maze.step(game, move)
+    game.log.append(line + _event_suffix(ev))
+    return _maze_outputs(game, resp, move, smv, safety, show_danger, who="you")
+
+
+def maze_redraw(game, safety, show_danger):
+    system = SYS_ON if safety else SYS_OFF
+    resp = None if game.over else system.ask(game.state(), ["move", "fallback"] if safety else ["move"])
+    return board_html(game, resp, show_danger)
+
+
+# ====================================================================================================================
+# Card fusion lab
+# ====================================================================================================================
+
+CARD_COLORS = {"Whip": "#b5651d", "Magic Wand": "#7b61ff", "Frost Orb": "#2fa4e7", "Fire Staff": "#ff5a36",
+               "Vampire Fang": "#b3123f", "Thunder Hammer": "#e0b000", "Throwing Knives": "#6f7f8f", "Poison Cloud": "#3fa34d"}
+BAR_MAX = {"damage": 40, "fire_rate": 3.4, "area": 6, "speed": 18, "pierce": 10}
+BAR_LABEL = {"damage": "damage", "fire_rate": "fire rate /s", "area": "area", "speed": "speed", "pierce": "pierce"}
+
+
+def card_html(c, colors, tag="", marks=None, small=False):
+    marks = marks or {}
+    bars = []
+    for k in fusion.NUMERIC:
+        v = getattr(c, k)
+        pct = max(4, min(100, 100 * v / BAR_MAX[k]))
+        mark = f" <span class='fx-mark'>{html.escape(marks[k])}</span>" if k in marks else ""
+        txt = f"{v:.0f}" if k == "pierce" else f"{v:.2f}" if v < 10 else f"{v:.1f}"
+        bars.append(f"<div class='fx-row'><span class='fx-k'>{BAR_LABEL[k]}</span><div class='fx-bar'>"
+                    f"<div style='width:{pct:.0f}%'></div></div><span class='fx-v'>{txt}{mark}</span></div>")
+    chips = []
+    for k, icon, label in (("slow", "❄️", "slow"), ("burn", "🔥", "burn"), ("lifesteal", "🩸", "lifesteal")):
+        v = getattr(c, k)
+        if v > 1e-9:
+            mark = f" <span class='fx-mark'>{html.escape(marks[k])}</span>" if k in marks else ""
+            chips.append(f"<span class='fx-chip'>{icon} {label} {'+' if k == 'burn' else ''}{v * 100:.0f}%{mark}</span>")
+    cd_mark = f" <span class='fx-mark'>{html.escape(marks['cooldown'])}</span>" if "cooldown" in marks else ""
+    chips.append(f"<span class='fx-chip'>⏱ cooldown {c.cooldown:.2f}s{cd_mark}</span>")
+    grad = f"linear-gradient(135deg, {colors[0]}, {colors[-1]})"
+    sig = f"<div class='fx-sig'>style trait: {html.escape(c.signature)}</div>" if c.signature else ""
+    return (f"<div class='fx-card{' fx-small' if small else ''}' style='--fx-grad:{grad}'>"
+            f"<div class='fx-head'><span class='fx-icon'>{c.icon}</span><div><div class='fx-name'>{html.escape(c.name)}</div>"
+            f"<div class='fx-shape'>{html.escape(c.shape)}{(' · ' + html.escape(tag)) if tag else ''}</div></div></div>"
+            f"{''.join(bars)}<div class='fx-chips'>{''.join(chips)}</div>{sig}"
+            f"<div class='fx-power'>⚡ power {fusion.card_power(c):.1f}</div></div>")
+
+
+def gallery_html():
+    return "<div class='fx-gallery'>" + "".join(card_html(c, [CARD_COLORS[c.name]] * 2, small=True) for c in fusion.BASE) + "</div>"
+
+
+def do_fuse(a_name, b_name, law):
+    a, b = fusion.BY_NAME[a_name], fusion.BY_NAME[b_name]
+    raw = fusion.fuse(a, b, law)
+    final, resp, changes = fusion.balance(raw)
+    colors = [CARD_COLORS[a_name], CARD_COLORS[b_name]]
+    marks = {}
+    for q, key, txt in (("slow", "slow", "clamped"), ("lifesteal", "lifesteal", "clamped"), ("cooldown", "cooldown", "clamped")):
+        if resp[q].answer == "clamp":
+            marks[key] = txt
+    if resp["power"].answer != "in_band":
+        marks["damage"] = f"×{resp.values['damage_scale']:.2f}"
+    law_txt = ("BLEND — order does not matter: shape of the stronger parent, numbers averaged in log space, effects stack"
+               if law == "BLEND" else
+               f"DOMINANT — {a.name} in the style of {b.name}: shape and 75% of the numbers from {a.name}, "
+               f"{b.name}'s effects stack on top, plus its trait ({b.signature})")
+    cards = (f"<div class='fx-law'>{html.escape(law_txt)}</div><div class='fx-flow'>"
+             f"{card_html(a, [colors[0]] * 2, 'parent A', small=True)}<div class='fx-op'>{'＋' if law == 'BLEND' else '◀'}</div>"
+             f"{card_html(b, [colors[1]] * 2, 'parent B', small=True)}<div class='fx-op'>＝</div>"
+             f"{card_html(raw, colors, 'raw fusion', small=True)}<div class='fx-op'>⚖️</div>"
+             f"{card_html(final, colors, 'balanced by solvi', marks)}</div>")
+    ch = ("".join(f"<li>{html.escape(x)}</li>" for x in changes) if changes
+          else "<li>nothing to fix: every hard check passed and the power is inside the band</li>")
+    verdict = "ships unchanged ✅" if resp["ship_as_is"].answer == "yes" else "needed fixes 🔧"
+    report = (f"<div class='sv-card'><div class='sv-title'>Balance report: {html.escape(raw.name)} {verdict}</div>"
+              f"<ul class='fx-changes'>{ch}</ul></div>" +
+              why_html(resp, fusion.cat, [q.name for q in fusion.QUESTIONS], title="solvi answers (rule inputs, hard checks, facts)"))
+    return cards, report
+
+
+def surprise():
+    rng = random.Random()
+    a, b = rng.sample([c.name for c in fusion.BASE], 2)
+    law = rng.choice(["BLEND", "DOMINANT"])
+    return (a, b, law, *do_fuse(a, b, law))
+
+
+# ====================================================================================================================
+# Build your own bot
+# ====================================================================================================================
+
+_DEFAULT_RUNS: dict = {}
+
+
+def _default_run(safety):
+    if safety not in _DEFAULT_RUNS:
+        _, system = maze.build_system(safety)
+        _DEFAULT_RUNS[safety] = maze.summarize([maze.run_game(system, s, safety) for s in range(sandbox.N_GAMES)])
+    return _DEFAULT_RUNS[safety]
+
+
+def run_user_bot(code, safety):
+    t0 = time.time()
+    res = sandbox.run_bot(code, safety=safety)
+    dt = time.time() - t0
+    if not res["ok"]:
+        return (f"<div class='sv-err'><b>Your bot did not run ({html.escape(res['kind'])}).</b>"
+                f"<pre>{html.escape(res['error'])}</pre></div>", "")
+    base = _default_run(safety)
+    you = res["summary"]
+
+    def row(name, s):
+        return (f"| {name} | **{s['win_rate'] * 100:.0f}%** | {s['avg_score']:.0f} | {s['avg_dots_pct'] * 100:.0f}% | "
+                f"{s['avg_deaths']:.2f} | {s['avg_forced']:.1f} |")
+    diff = you["avg_score"] - base["avg_score"]
+    verdict = ("🏆 Your bot beats the default!" if diff > 0 else "🤝 Same score as the default." if diff == 0
+               else "The default bot is still ahead. Tweak and try again.")
+    warn = ""
+    if res.get("abstains"):
+        warn = (f"<div class='sv-err'><b>Your function failed or returned an invalid move on {res['abstains']} ticks</b> "
+                f"(solvi abstained and Pac took the first legal move). First problem:"
+                f"<pre>{html.escape(str(res.get('first_error')))}</pre></div>")
+    md = (f"### {verdict}\n"
+          f"{sandbox.N_GAMES} seeded games, hard safety check {'ON' if safety else 'OFF'}, ran in your browser in {dt:.1f} s "
+          f"(limit {sandbox.DEADLINE_S:.0f} s)\n\n"
+          "| bot | games cleared | avg score | dots eaten | lives lost | vetoes per game |\n|---|---|---|---|---|---|\n"
+          f"{row('your bot', you)}\n{row('default bot', base)}\n\n"
+          "Per game (seed: score, ✓ = cleared): " +
+          " · ".join(f"{i}: {g['score']}{' ✓' if g['won'] else ''}" for i, g in enumerate(res["games"])))
+    return warn, md
+
+
+# ====================================================================================================================
+# UI
+# ====================================================================================================================
+
+CSS = """
+.gradio-container {max-width: 1180px !important; margin: auto;}
+#hero h1 {font-size: 2.1rem; margin-bottom: 0;}
+.sv-card {border: 1px solid var(--border-color-primary); border-radius: 12px; padding: 12px 14px; margin: 6px 0;
+  background: var(--block-background-fill); font-size: 0.92rem; overflow-x: auto;}
+.sv-title {font-weight: 700; font-size: 1.02rem; margin-bottom: 8px;}
+.sv-ans {margin: 4px 0 8px;}
+.sv-why {font-family: var(--font-mono); font-size: 0.82rem; opacity: 0.85; margin-top: 2px; word-break: break-word;}
+.sv-badge {display: inline-block; border-radius: 999px; padding: 1px 9px; font-size: 0.76rem; font-weight: 600; margin: 2px 2px;}
+.sv-ok {background: #16a34a22; color: #16a34a; border: 1px solid #16a34a66;}
+.sv-forced {background: #dc262622; color: #ef4444; border: 1px solid #dc262688;}
+.sv-abstain {background: #ca8a0422; color: #ca8a04; border: 1px solid #ca8a0466;}
+.sv-dim {opacity: 0.7;}
+.sv-hc {margin: 6px 0;}
+.sv-facts {width: 100%; border-collapse: collapse; font-size: 0.8rem; margin-top: 6px;}
+.sv-facts td {border-top: 1px solid var(--border-color-primary); padding: 3px 6px; vertical-align: top;}
+.sv-facts td:first-child {font-family: var(--font-mono); white-space: nowrap;}
+.sv-err {border: 1px solid #dc2626aa; background: #dc262614; border-radius: 10px; padding: 10px 12px; margin: 6px 0;}
+.sv-err pre {white-space: pre-wrap; font-size: 0.8rem; margin: 6px 0 0;}
+.ttt-grid {max-width: 330px; gap: 6px !important;}
+.ttt-grid button {min-height: 92px !important; font-size: 2.4rem !important; border-radius: 14px !important;}
+.mz-wrap {position: relative; max-width: 440px; margin: 0 auto;}
+.mz-grid {display: grid; gap: 0; background: #05061a; padding: 6px; border-radius: 12px; border: 2px solid #2233aa;}
+.mz {aspect-ratio: 1; position: relative; display: flex; align-items: center; justify-content: center;}
+.c-wall {background: #1b2a9e; border-radius: 4px; box-shadow: inset 0 0 0 2px #3b52ff55; margin: 1px;}
+.c-danger {background: #ff2d2d33;}
+.mz-dot {width: 22%; height: 22%; border-radius: 50%; background: #ffcfa0;}
+.mz-pac {width: 82%; height: 82%; border-radius: 50%;}
+.mz-ghost {width: 82%; height: 82%; border-radius: 45% 45% 12% 12%; display: flex; align-items: center; justify-content: center;
+  font-size: 0.7rem; line-height: 1;}
+.mz-banner {position: absolute; top: 42%; left: 0; right: 0; text-align: center; font-weight: 800; font-size: 2rem; z-index: 2;
+  letter-spacing: 2px; text-shadow: 0 2px 8px #000;}
+.mz-win {color: #7CFF7C;} .mz-lose {color: #ff5a5a;}
+.arrows button {font-size: 1.4rem !important; min-width: 56px !important;}
+.fx-gallery {display: grid; grid-template-columns: repeat(auto-fill, minmax(170px, 1fr)); gap: 10px;}
+.fx-flow {display: flex; flex-wrap: wrap; align-items: center; gap: 8px;}
+.fx-op {font-size: 1.6rem; opacity: 0.8;}
+.fx-law {font-size: 0.88rem; opacity: 0.85; margin-bottom: 8px;}
+.fx-card {background: var(--fx-grad); color: #fff; border-radius: 16px; padding: 12px; width: 250px; box-sizing: border-box;
+  box-shadow: 0 6px 18px #0004; text-shadow: 0 1px 2px #0006;}
+.fx-small {width: 185px; padding: 9px; font-size: 0.85rem;}
+.fx-gallery .fx-small {width: auto;}
+.fx-head {display: flex; gap: 8px; align-items: center; margin-bottom: 6px;}
+.fx-icon {font-size: 2rem; background: #ffffff30; border-radius: 12px; padding: 2px 6px;}
+.fx-small .fx-icon {font-size: 1.5rem;}
+.fx-icon {white-space: nowrap;}
+.fx-small .fx-row {grid-template-columns: 60px 1fr 44px;}
+.fx-name {font-weight: 800; font-size: 1.08rem;}
+.fx-shape {font-size: 0.72rem; opacity: 0.9; text-transform: uppercase; letter-spacing: 1px;}
+.fx-row {display: grid; grid-template-columns: 74px 1fr 64px; align-items: center; gap: 6px; font-size: 0.76rem; margin: 2px 0;}
+.fx-bar {height: 7px; background: #00000040; border-radius: 4px; overflow: hidden;}
+.fx-bar div {height: 100%; background: #fff; border-radius: 4px;}
+.fx-v {text-align: right; font-variant-numeric: tabular-nums;}
+.fx-chips {display: flex; flex-wrap: wrap; gap: 4px; margin-top: 6px;}
+.fx-chip {background: #00000038; border-radius: 999px; padding: 1px 7px; font-size: 0.72rem; color: #fff;}
+.fx-card span, .fx-card div {color: inherit;}
+.fx-card .fx-mark {background: #fff; color: #b00020; border-radius: 6px; padding: 0 4px; font-weight: 700; text-shadow: none; font-size: 0.68rem;}
+.fx-power {margin-top: 7px; font-weight: 800;}
+.fx-sig {font-size: 0.7rem; margin-top: 5px; opacity: 0.9;}
+.fx-changes {margin: 0 0 4px 18px;}
+@media (max-width: 640px) { .fx-card {width: 100%;} .fx-small {width: 46%;} .fx-op {display: none;} }
+"""
+
+INTRO = f"""
+# 🕹️ solvi arcade
+**Game agents made of small Python functions, a few rules and hard checks — strong, and every move is explained.**
+No neural network, no GPU, **no server: the agents run right here, in your browser** (Python compiled to WebAssembly).
+Each agent is a [solvi]({REPO}) catalog. For every move it shows the rule's inputs, the facts it computed this turn and
+which hard check fired. Write your own decision task in the [solvi playground]({PLAYGROUND}).
+"""
+
+# Soft's default fonts are served from the Gradio server's /static folder, which Gradio-Lite does not have: use Google Fonts.
+THEME = gr.themes.Soft(primary_hue="violet", secondary_hue="amber",
+                       font=[gr.themes.GoogleFont("Montserrat"), "ui-sans-serif", "system-ui", "sans-serif"],
+                       font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "ui-monospace", "Consolas", "monospace"])
+
+with gr.Blocks(title="solvi arcade", theme=THEME, css=CSS) as demo:
+    gr.Markdown(INTRO, elem_id="hero")
+    with gr.Tabs():
+        # ---------------------------------------------------------------------------------------------------- TTT
+        with gr.Tab("❌⭕ Tic-tac-toe"):
+            gr.Markdown("Play against a solvi agent whose whole brain is seven small functions (win, block, fork, forcing move ...) "
+                        f"and one rule, from `{tictactoe.SOURCE}`. It answers every move with its reason. "
+                        "It has never lost.")
+            ttt_game, ttt_resp = gr.State(), gr.State()
+            ttt_stats = gr.State({"games": 0, "agent_losses": 0, "agent_wins": 0, "draws": 0})
+            with gr.Row():
+                with gr.Column(scale=4, min_width=300):
+                    with gr.Row():
+                        ttt_side = gr.Radio(["X (you start)", "O (solvi starts)"], value="X (you start)", label="You play",
+                                            scale=3)
+                        ttt_new_btn = gr.Button("New game", variant="primary", scale=1)
+                    ttt_status = gr.Markdown("### Your move (❌)")
+                    ttt_buttons = []
+                    with gr.Column(elem_classes="ttt-grid"):
+                        for _ in range(3):
+                            with gr.Row(equal_height=True):
+                                for _ in range(3):
+                                    ttt_buttons.append(gr.Button(EMPTY, min_width=80))
+                    ttt_counter = gr.Markdown()
+                with gr.Column(scale=6):
+                    ttt_why = gr.HTML()
+                    ttt_explain_cb = gr.Checkbox(label="Explain the position (all computed facts for the side to move)")
+                    ttt_pos = gr.HTML(visible=False)
+            ttt_outs = [*ttt_buttons, ttt_status, ttt_why, ttt_pos, ttt_counter, ttt_game, ttt_resp, ttt_stats]
+            ttt_new_btn.click(ttt_new, [ttt_side, ttt_stats, ttt_explain_cb], ttt_outs)
+            ttt_side.change(ttt_new, [ttt_side, ttt_stats, ttt_explain_cb], ttt_outs)
+            for i, b in enumerate(ttt_buttons):
+                b.click(lambda g, rs, s, e, i=i: ttt_click(i, g, rs, s, e), [ttt_game, ttt_resp, ttt_stats, ttt_explain_cb],
+                        ttt_outs)
+            ttt_explain_cb.change(ttt_explain, [ttt_game, ttt_explain_cb], ttt_pos)
+            demo.load(ttt_new, [ttt_side, ttt_stats, ttt_explain_cb], ttt_outs)
+
+        # ---------------------------------------------------------------------------------------------------- maze
+        with gr.Tab("👻 Ghost maze"):
+            gr.Markdown(
+                "Pac is a solvi catalog: `legal_moves`, BFS `dot_dist` and `ghost_dist` per move, `ghost_reach`, `danger`, "
+                "`safe_moves`, one scoring function `greedy_move`, and a **hard check** `greedy_is_safe`: *never step onto a "
+                "cell a ghost can reach this tick when a safer move exists*. When it fires, the answer is forced to EVADE and "
+                "Pac takes the best safe move. Turn the check off and watch Pac die. Or take over with the arrows.")
+            mz_game = gr.State()
+            with gr.Row():
+                with gr.Column(scale=5, min_width=320):
+                    mz_board = gr.HTML()
+                    mz_stats = gr.Markdown()
+                    with gr.Row():
+                        mz_step = gr.Button("Step", variant="secondary")
+                        mz_play = gr.Button("▶ Play 50 ticks", variant="primary")
+                        mz_reset = gr.Button("Reset")
+                    with gr.Row():
+                        mz_safety = gr.Checkbox(value=True, label="hard safety check ON")
+                        mz_danger = gr.Checkbox(value=False, label="show ghost reach (red)")
+                        mz_seed = gr.Number(value=0, precision=0, label="seed", minimum=0, maximum=10**6)
+                    gr.Markdown("**Take over** (one tick per press; solvi's choice is shown for comparison):")
+                    with gr.Row(elem_classes="arrows"):
+                        mz_left = gr.Button("←")
+                        mz_up = gr.Button("↑")
+                        mz_down = gr.Button("↓")
+                        mz_right = gr.Button("→")
+                with gr.Column(scale=6):
+                    mz_log = gr.Textbox(label="tick log (newest first)", lines=9, max_lines=9, interactive=False)
+                    mz_why = gr.HTML()
+            with gr.Row(equal_height=True):
+                mz_bench_size = gr.Radio(list(BENCH_SIZES), value=next(iter(BENCH_SIZES)), label="benchmark size", scale=3)
+                mz_bench_btn = gr.Button("📊 Run the benchmark in your browser", scale=2)
+            mz_bench = gr.Markdown(bench_native_markdown())
+            mz_outs = [mz_board, mz_stats, mz_log, mz_why, mz_game]
+            mz_step.click(maze_step, [mz_game, mz_safety, mz_danger], mz_outs)
+            mz_play.click(maze_play, [mz_game, mz_safety, mz_danger], mz_outs)
+            mz_reset.click(maze_reset, [mz_seed, mz_safety, mz_danger], mz_outs)
+            for btn, mv in ((mz_left, "LEFT"), (mz_up, "UP"), (mz_down, "DOWN"), (mz_right, "RIGHT")):
+                btn.click(lambda g, s, d, mv=mv: maze_human(mv, g, s, d), [mz_game, mz_safety, mz_danger], mz_outs)
+            mz_danger.change(maze_redraw, [mz_game, mz_safety, mz_danger], mz_board)
+            demo.load(maze_reset, [mz_seed, mz_safety, mz_danger], mz_outs)
+            mz_bench_btn.click(lambda: "#### Benchmark: running in your browser …", None, mz_bench).then(
+                bench_run, mz_bench_size, mz_bench)
+
+        # ---------------------------------------------------------------------------------------------------- fusion
+        with gr.Tab("🃏 Card fusion lab"):
+            gr.Markdown(
+                "Fuse two weapon cards. The fused card then goes through a solvi balance catalog: it computes the power "
+                "(dps × targets × effects), **hard checks** slow ≤ 0.5, lifesteal ≤ 0.4, cooldown ≥ 0.3 s (a violation is "
+                "clamped and reported) and a soft check that power stays within [0.5 × median, 1.5 × max] of the base cards "
+                "(outside → damage is rescaled, and the report says by how much).")
+            with gr.Accordion("The 8 base cards", open=False):
+                gr.HTML(gallery_html())
+            names = [c.name for c in fusion.BASE]
+            with gr.Row():
+                fx_a = gr.Dropdown(names, value="Whip", label="Card A")
+                fx_b = gr.Dropdown(names, value="Frost Orb", label="Card B")
+                fx_law = gr.Radio(["BLEND", "DOMINANT"], value="BLEND", label="Fusion law",
+                                  info="BLEND: A+B = B+A · DOMINANT: A in the style of B")
+            with gr.Row():
+                fx_go = gr.Button("✨ Fuse", variant="primary")
+                fx_swap = gr.Button("⇄ Swap A and B")
+                fx_rand = gr.Button("🎲 Surprise me")
+            fx_cards = gr.HTML()
+            fx_report = gr.HTML()
+            gr.Markdown("Try **Whip ◀ Vampire Fang** (DOMINANT: lifesteal over the cap), **Magic Wand ◀ Throwing Knives** "
+                        "(cooldown too short), **Thunder Hammer + Frost Orb** (BLEND: slow over the cap), or **Thunder Hammer ◀ "
+                        "Fire Staff** (too strong, damage rescaled).")
+            fx_go.click(do_fuse, [fx_a, fx_b, fx_law], [fx_cards, fx_report])
+            fx_swap.click(lambda a, b: (b, a), [fx_a, fx_b], [fx_a, fx_b]).then(do_fuse, [fx_a, fx_b, fx_law], [fx_cards, fx_report])
+            fx_rand.click(surprise, None, [fx_a, fx_b, fx_law, fx_cards, fx_report])
+            demo.load(do_fuse, [fx_a, fx_b, fx_law], [fx_cards, fx_report])
+
+        # ---------------------------------------------------------------------------------------------------- bot
+        with gr.Tab("🛠️ Build your own bot"):
+            gr.Markdown(
+                "This is the maze agent's scoring function — the one piece of Pac's catalog you can rewrite. Change the "
+                f"weights or the logic, then run {sandbox.N_GAMES} seeded games against the default bot. solvi plans the flow "
+                "from your function's argument names, so you can use any fact listed in the comments. "
+                "Ideas: set `W_GHOST = 0` and turn the safety check off; use `danger` or `safe_moves` yourself; prefer moves "
+                "that keep more `legal_moves` open.")
+            with gr.Row():
+                with gr.Column(scale=6):
+                    bot_code = gr.Code(value=maze.DEFAULT_BOT_CODE, language="python", lines=26, max_lines=40,
+                                       label="greedy_move (Python)", interactive=True)
+                with gr.Column(scale=6):
+                    bot_safety = gr.Checkbox(value=True, label="keep the hard safety check greedy_is_safe")
+                    with gr.Row():
+                        bot_run = gr.Button(f"▶ Run {sandbox.N_GAMES} games", variant="primary")
+                        bot_reset = gr.Button("Reset code")
+                    bot_err = gr.HTML()
+                    bot_out = gr.Markdown()
+                    gr.Markdown("<span class='sv-dim'>Your code runs **in your own browser**, in this page's Python, so "
+                                "nothing is sent to a server. A guard stops it when one call runs more than "
+                                f"{sandbox.MAX_LINES_PER_CALL:,} lines (an infinite loop) or the whole run takes more than "
+                                f"{sandbox.DEADLINE_S:.0f} s. A loop inside C code (e.g. `sum(itertools.count())`) "
+                                "cannot be interrupted: then reload the page.</span>")
+            bot_run.click(run_user_bot, [bot_code, bot_safety], [bot_err, bot_out])
+            bot_reset.click(lambda: maze.DEFAULT_BOT_CODE, None, bot_code)
+
+    gr.Markdown(f"<span class='sv-dim'>Built with [solvi]({REPO}) (`pip install solvi`) — decision systems from a catalog "
+                "of Python functions and checks. No models, no server: this page runs Python in your browser with "
+                "Gradio-Lite and Pyodide. Every answer here is a solvi `Response`: `r[q].answer / .why / .status`, "
+                f"the planned `flow` and a hash-chained `trace`. More: the [solvi playground]({PLAYGROUND}).</span>")
+
+demo.launch()

games/_ttt_catalog.py

@@ -0,0 +1,108 @@
+"""Vendored copy of solvi/examples/05_tic_tac_toe.py (catalog part only), so the browser app needs nothing but solvi."""
+from __future__ import annotations
+
+from solvi import Answer, Catalog, Question
+
+LINES = [(0, 1, 2), (3, 4, 5), (6, 7, 8), (0, 3, 6), (1, 4, 7), (2, 5, 8), (0, 4, 8), (2, 4, 6)]
+CELLS = [str(i) for i in range(9)]
+
+cat = Catalog()
+
+
+def _wins(board, who):
+    return [c for c in range(9) if board[c] == "." and any(c in ln and sum(board[i] == who for i in ln) == 2 and
+                                                           all(board[i] in (who, ".") for i in ln) for ln in LINES)]
+
+
+def _winner(board):
+    for a, b, c in LINES:
+        if board[a] != "." and board[a] == board[b] == board[c]:
+            return board[a]
+    return None
+
+
+@cat.fn
+def opponent(me):
+    return "O" if me == "X" else "X"
+
+
+@cat.fn
+def free_cells(board):
+    return [c for c in range(9) if board[c] == "."]
+
+
+@cat.fn
+def winning_moves(board, me):
+    """cells where `me` completes a line right now"""
+    return _wins(board, me)
+
+
+@cat.fn
+def blocking_moves(board, opponent):
+    """cells where the opponent would complete a line next move"""
+    return _wins(board, opponent)
+
+
+@cat.fn
+def fork_moves(board, me, free_cells):
+    """cells that create two winning threats at once"""
+    return [c for c in free_cells if len(_wins(board[:c] + me + board[c + 1:], me)) >= 2]
+
+
+@cat.fn
+def opponent_forks(board, opponent, free_cells):
+    return [c for c in free_cells if len(_wins(board[:c] + opponent + board[c + 1:], opponent)) >= 2]
+
+
+@cat.fn
+def forcing_moves(board, me, opponent, free_cells):
+    """cells that threaten a win so the opponent must block — at a cell that does not give the opponent a fork"""
+    out = []
+    for c in free_cells:
+        b = board[:c] + me + board[c + 1:]
+        threats = _wins(b, me)
+        if len(threats) == 1:
+            r = threats[0]
+            b2 = b[:r] + opponent + b[r + 1:]
+            if len(_wins(b2, opponent)) < 2:
+                out.append(c)
+    return out
+
+
+@cat.fn
+def winner(board):
+    return _winner(board) or "-"
+
+
+@cat.check(hard=True, then={"move": "none"})
+def board_valid(board, me):
+    """hard: 9 cells of X/O/., fair turn order, game not over"""
+    x, o = board.count("X"), board.count("O")
+    turn_ok = (x == o and me == "X") or (x == o + 1 and me == "O")
+    return len(board) == 9 and set(board) <= {"X", "O", "."} and turn_ok and _winner(board) is None and "." in board
+
+
+@cat.rule("move")
+def pick_move(winning_moves, blocking_moves, fork_moves, opponent_forks, forcing_moves, free_cells):
+    for group in (winning_moves, blocking_moves, fork_moves):
+        if group:
+            return str(group[0])
+    if len(opponent_forks) == 1:                          # a single fork cell: take it
+        return str(opponent_forks[0])
+    if opponent_forks and forcing_moves:                  # several: force the opponent to answer a threat instead
+        return str(forcing_moves[0])
+    for c in (4, 0, 2, 6, 8, 1, 3, 5, 7):                 # center, corners, edges
+        if c in free_cells:
+            return str(c)
+    return "none"
+
+
+@cat.rule("outcome")
+def outcome(winner, free_cells, me):
+    if winner == "-":
+        return "draw" if not free_cells else "ongoing"
+    return "won" if winner == me else "lost"
+
+
+QUESTIONS = [Question("move", "Which cell to play?", Answer.choice(CELLS + ["none"]), checkpoints=["board_valid"]),
+             Question("outcome", "State of the game for me?", Answer.choice(["ongoing", "won", "lost", "draw"]))]

games/explain.py

@@ -0,0 +1,52 @@
+"""Shared helpers: turn a solvi Response into a readable "why" panel (rule inputs, facts computed this turn, hard checks)."""
+from __future__ import annotations
+
+import html
+
+from solvi.runtime import MISSING
+
+
+def _short(v, limit=90):
+    s = repr(v)
+    return s if len(s) <= limit else s[: limit - 1] + "…"
+
+
+def hard_checks(resp, catalog):
+    """[(name, passed)] for every hard check that ran in this response."""
+    out = []
+    for r in resp.trace.records:
+        p = catalog.parts.get(r.name)
+        if p is not None and p.kind == "check" and p.hard and r.value is not MISSING:
+            out.append((r.name, bool(r.value)))
+    return out
+
+
+def facts(resp):
+    """[(name, value, kind)] for every fact computed in this response (rules excluded)."""
+    return [(r.name, r.value, r.kind) for r in resp.trace.records if r.kind != "rule" and r.value is not MISSING]
+
+
+def why_html(resp, catalog, questions, show_facts=True, title=None):
+    """An HTML card: answers with status/why, hard checks, and (optionally) all facts computed this turn."""
+    rows = []
+    for q in questions:
+        r = resp[q]
+        badge = {"ok": "ok", "forced": "forced by a hard check", "abstain": "abstained"}[r.status]
+        cls = {"ok": "sv-ok", "forced": "sv-forced", "abstain": "sv-abstain"}[r.status]
+        rows.append(f"<div class='sv-ans'><b>{html.escape(q)}</b> = <code>{html.escape(str(r.answer))}</code> "
+                    f"<span class='sv-badge {cls}'>{badge}</span> <span class='sv-dim'>confidence {r.confidence:.2f}</span>"
+                    f"<div class='sv-why'>why: {html.escape(r.why)}</div></div>")
+    hc = hard_checks(resp, catalog)
+    if hc:
+        items = " ".join(f"<span class='sv-badge {'sv-ok' if ok else 'sv-forced'}'>{html.escape(n)}: "
+                         f"{'passed' if ok else 'FIRED'}</span>" for n, ok in hc)
+        rows.append(f"<div class='sv-hc'>hard checks: {items}</div>")
+    else:
+        rows.append("<div class='sv-hc sv-dim'>hard checks: none in this flow</div>")
+    if show_facts:
+        fr = "".join(f"<tr><td>{html.escape(n)}</td><td class='sv-dim'>{k}</td><td><code>{html.escape(_short(v))}</code></td></tr>"
+                     for n, v, k in facts(resp))
+        rows.append(f"<details open><summary>facts computed this turn ({len(facts(resp))} steps, "
+                    f"{resp.ms:.2f} ms)</summary><table class='sv-facts'>{fr}</table></details>")
+    head = f"<div class='sv-title'>{html.escape(title)}</div>" if title else ""
+    return f"<div class='sv-card'>{head}{''.join(rows)}</div>"

games/fusion.py

@@ -0,0 +1,275 @@
+"""Card fusion lab: fuse two weapon cards with a fusion law, then let a solvi catalog balance the result.
+
+Laws
+  BLEND     order does not matter: shape of the stronger parent, numbers averaged in log space (geometric mean),
+            effects stack (added).
+  DOMINANT  "A in the style of B", order matters: shape of A, numbers 75% A / 25% B in log space, B's effects stack
+            onto A's, then B's signature trait is applied.
+
+Balance (solvi): hard checks slow <= 0.5, lifesteal <= 0.4, cooldown >= 0.3 s (a violation is clamped and reported);
+soft check: power within [0.5 x median, 1.5 x max] of the base cards (outside -> damage is scaled and the factor reported)."""
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import asdict, dataclass, replace
+
+from solvi import Answer, Catalog, Question, System
+
+SLOW_CAP, LIFESTEAL_CAP, COOLDOWN_MIN = 0.5, 0.4, 0.3
+NUMERIC = ["damage", "fire_rate", "area", "speed", "pierce"]
+
+
+@dataclass(frozen=True)
+class Card:
+    name: str
+    prefix: str          # used when this card gives its style to a fusion ("Frost ...")
+    noun: str            # used when this card gives its shape ("... Whip")
+    icon: str
+    shape: str
+    damage: float
+    fire_rate: float     # shots per second (cooldown = 1 / fire_rate)
+    area: float
+    speed: float
+    pierce: float
+    slow: float = 0.0
+    burn: float = 0.0    # extra damage over time, as a fraction of hit damage
+    lifesteal: float = 0.0
+    signature: str = ""  # trait applied when this card is the style (B) in DOMINANT
+
+    @property
+    def cooldown(self):
+        return 1.0 / self.fire_rate
+
+
+SIGNATURES = {  # name -> (description, function Card -> Card)
+    "Whip": ("reach: area x1.3", lambda c: replace(c, area=c.area * 1.3)),
+    "Magic Wand": ("homing: speed x1.5, pierce +1", lambda c: replace(c, speed=c.speed * 1.5, pierce=c.pierce + 1)),
+    "Frost Orb": ("chill: slow +0.15", lambda c: replace(c, slow=c.slow + 0.15)),
+    "Fire Staff": ("ignite: burn +0.4", lambda c: replace(c, burn=c.burn + 0.4)),
+    "Vampire Fang": ("thirst: lifesteal +0.15", lambda c: replace(c, lifesteal=c.lifesteal + 0.15)),
+    "Thunder Hammer": ("weight: damage x1.4, fire rate x0.8", lambda c: replace(c, damage=c.damage * 1.4, fire_rate=c.fire_rate * 0.8)),
+    "Throwing Knives": ("flurry: fire rate x1.6", lambda c: replace(c, fire_rate=c.fire_rate * 1.6)),
+    "Poison Cloud": ("spread: area x1.5, damage x0.7", lambda c: replace(c, area=c.area * 1.5, damage=c.damage * 0.7)),
+}
+
+BASE = [
+    Card("Whip", "Lashing", "Whip", "🪢", "arc", 12, 1.2, 2.0, 4, 5, lifesteal=0.2),
+    Card("Magic Wand", "Arcane", "Wand", "🪄", "bolt", 10, 2.0, 0.5, 9, 1),
+    Card("Frost Orb", "Frost", "Orb", "🔮", "orb", 8, 0.8, 2.5, 3, 3, slow=0.35),
+    Card("Fire Staff", "Blazing", "Staff", "🔥", "fireball", 14, 1.0, 1.5, 5, 1, burn=0.6),
+    Card("Vampire Fang", "Vampiric", "Fang", "🦇", "bite", 12, 1.5, 0.6, 7, 1, lifesteal=0.25),
+    Card("Thunder Hammer", "Thunder", "Hammer", "🔨", "shockwave", 30, 0.5, 3.0, 2, 8, slow=0.2),
+    Card("Throwing Knives", "Swift", "Knives", "🗡️", "volley", 6, 3.0, 0.3, 12, 2),
+    Card("Poison Cloud", "Toxic", "Cloud", "☠️", "cloud", 3, 1.0, 4.0, 1, 10, burn=1.0),
+]
+BASE = [replace(c, signature=SIGNATURES[c.name][0]) for c in BASE]
+BY_NAME = {c.name: c for c in BASE}
+
+
+def targets_of(pierce, area):
+    """expected enemies hit per shot: area finds them, pierce caps them"""
+    return min(pierce, 1 + area)
+
+
+def power_of(damage, fire_rate, pierce, area, burn, slow, lifesteal):
+    return damage * fire_rate * targets_of(pierce, area) * (1 + burn) * (1 + slow) * (1 + lifesteal)
+
+
+def card_power(c: Card):
+    return power_of(c.damage, c.fire_rate, c.pierce, c.area, c.burn, c.slow, c.lifesteal)
+
+
+BASE_POWERS = tuple(round(card_power(c), 3) for c in BASE)
+
+
+def _lmix(a, b, wa):
+    return math.exp(wa * math.log(a) + (1 - wa) * math.log(b))
+
+
+def fuse(a: Card, b: Card, law: str) -> Card:
+    """Raw fusion (before balancing)."""
+    law = law.upper()
+    if law == "BLEND":
+        pa, pb = card_power(a), card_power(b)
+        strong, weak = (a, b) if (pa, a.name) >= (pb, b.name) else (b, a)
+        nums = {k: _lmix(getattr(a, k), getattr(b, k), 0.5) for k in NUMERIC}
+        name = f"Twin {strong.noun}" if a == b else f"{weak.prefix} {strong.noun}"
+        shape_from, style_from = strong, weak
+    elif law == "DOMINANT":
+        nums = {k: _lmix(getattr(a, k), getattr(b, k), 0.75) for k in NUMERIC}
+        name = f"Mighty {a.noun}" if a == b else f"{b.prefix} {a.noun}"
+        shape_from, style_from = a, b
+    else:
+        raise ValueError(f"unknown law {law}")
+    nums["pierce"] = float(max(1, round(nums["pierce"])))
+    c = Card(name, style_from.prefix, shape_from.noun, shape_from.icon + (style_from.icon if style_from != shape_from else ""),
+             shape_from.shape, slow=a.slow + b.slow if a != b else a.slow, burn=a.burn + b.burn if a != b else a.burn,
+             lifesteal=a.lifesteal + b.lifesteal if a != b else a.lifesteal, **nums)
+    if law == "DOMINANT":
+        c = SIGNATURES[b.name][1](c)
+        c = replace(c, pierce=float(max(1, round(c.pierce))))
+    return replace(c, signature="")
+
+
+# --------------------------------------------------------------------------------------------------------------------
+# The balance catalog
+# --------------------------------------------------------------------------------------------------------------------
+
+cat = Catalog()
+
+
+@cat.fn
+def cooldown(fire_rate):
+    """seconds between shots"""
+    return round(1.0 / fire_rate, 4)
+
+
+@cat.fn
+def targets(pierce, area):
+    return round(targets_of(pierce, area), 4)
+
+
+@cat.fn
+def raw_dps(damage, fire_rate, targets):
+    """hit damage per second over all enemies hit, before effects"""
+    return round(damage * fire_rate * targets, 3)
+
+
+@cat.fn
+def slow_final(slow):
+    return min(slow, SLOW_CAP)
+
+
+@cat.fn
+def lifesteal_final(lifesteal):
+    return min(lifesteal, LIFESTEAL_CAP)
+
+
+@cat.fn
+def fire_rate_final(fire_rate):
+    return min(fire_rate, 1.0 / COOLDOWN_MIN)
+
+
+@cat.fn
+def power_after_clamps(raw_dps, fire_rate, fire_rate_final, burn, slow_final, lifesteal_final):
+    """effective power = raw dps x (1 + burn) x (1 + slow) x (1 + lifesteal), with the hard limits applied"""
+    return round(raw_dps * fire_rate_final / fire_rate * (1 + burn) * (1 + slow_final) * (1 + lifesteal_final), 3)
+
+
+@cat.fn
+def band_lo(base_powers):
+    return round(0.5 * statistics.median(base_powers), 3)
+
+
+@cat.fn
+def band_hi(base_powers):
+    return round(1.5 * max(base_powers), 3)
+
+
+@cat.check
+def power_in_band(power_after_clamps, band_lo, band_hi):
+    """soft: power within [0.5 x median, 1.5 x max] of the base cards"""
+    return band_lo <= power_after_clamps <= band_hi
+
+
+@cat.fn
+def damage_scale(power_after_clamps, band_lo, band_hi):
+    """factor on damage that brings power back to the nearest edge of the band (1.0 when inside)"""
+    if power_after_clamps > band_hi:
+        return round(band_hi / power_after_clamps, 4)
+    if power_after_clamps < band_lo:
+        return round(band_lo / power_after_clamps, 4)
+    return 1.0
+
+
+@cat.check(hard=True, then={"slow": "clamp", "ship_as_is": "no"})
+def slow_within_cap(slow):
+    """hard: slow <= 0.5"""
+    return slow <= SLOW_CAP + 1e-9
+
+
+@cat.check(hard=True, then={"lifesteal": "clamp", "ship_as_is": "no"})
+def lifesteal_within_cap(lifesteal):
+    """hard: lifesteal <= 0.4"""
+    return lifesteal <= LIFESTEAL_CAP + 1e-9
+
+
+@cat.check(hard=True, then={"cooldown": "clamp", "ship_as_is": "no"})
+def cooldown_ok(cooldown):
+    """hard: cooldown >= 0.3 s"""
+    return cooldown >= COOLDOWN_MIN - 1e-9
+
+
+@cat.rule("slow")
+def slow_rule(slow):
+    return "keep"
+
+
+@cat.rule("lifesteal")
+def lifesteal_rule(lifesteal):
+    return "keep"
+
+
+@cat.rule("cooldown")
+def cooldown_rule(cooldown):
+    return "keep"
+
+
+@cat.rule("power")
+def power_rule(power_in_band, power_after_clamps, band_lo, band_hi, damage_scale):
+    if power_in_band:
+        return "in_band"
+    return "scale_down" if power_after_clamps > band_hi else "scale_up"
+
+
+@cat.rule("ship_as_is")
+def ship_rule(power_in_band):
+    return power_in_band
+
+
+QUESTIONS = [
+    Question("slow", "Keep the slow as fused?", Answer.choice(["keep", "clamp"]), checkpoints=["slow_within_cap"]),
+    Question("lifesteal", "Keep the lifesteal as fused?", Answer.choice(["keep", "clamp"]), checkpoints=["lifesteal_within_cap"]),
+    Question("cooldown", "Keep the cooldown as fused?", Answer.choice(["keep", "clamp"]), checkpoints=["cooldown_ok"]),
+    Question("power", "Is the power in the base cards' band?", Answer.choice(["in_band", "scale_down", "scale_up"])),
+    Question("ship_as_is", "Can the fused card ship unchanged?", Answer.yes_no(),
+             checkpoints=["slow_within_cap", "lifesteal_within_cap", "cooldown_ok"]),
+]
+system = System(cat, QUESTIONS)
+
+
+def card_state(c: Card):
+    return {"damage": c.damage, "fire_rate": c.fire_rate, "area": c.area, "speed": c.speed, "pierce": c.pierce,
+            "slow": c.slow, "burn": c.burn, "lifesteal": c.lifesteal, "base_powers": BASE_POWERS}
+
+
+def balance(c: Card):
+    """Run the balance catalog. Returns (final card, response, list of human-readable changes)."""
+    resp = system.ask(card_state(c))
+    v = resp.values
+    changes = []
+    out = c
+    if resp["slow"].answer == "clamp":
+        changes.append(f"slow {c.slow:.2f} → {SLOW_CAP:.2f} (hard check slow_within_cap)")
+        out = replace(out, slow=v["slow_final"])
+    if resp["lifesteal"].answer == "clamp":
+        changes.append(f"lifesteal {c.lifesteal:.2f} → {LIFESTEAL_CAP:.2f} (hard check lifesteal_within_cap)")
+        out = replace(out, lifesteal=v["lifesteal_final"])
+    if resp["cooldown"].answer == "clamp":
+        changes.append(f"cooldown {c.cooldown:.2f}s → {COOLDOWN_MIN:.2f}s (hard check cooldown_ok)")
+        out = replace(out, fire_rate=v["fire_rate_final"])
+    p = resp["power"].answer
+    if p in ("scale_down", "scale_up"):
+        s = v["damage_scale"]
+        changes.append(f"power {v['power_after_clamps']:.1f} is {'above' if p == 'scale_down' else 'below'} the band "
+                       f"[{v['band_lo']:.1f}, {v['band_hi']:.1f}] → damage x{s:.2f} ({(s - 1) * 100:+.0f}%)")
+        out = replace(out, damage=c.damage * s)
+    return out, resp, changes
+
+
+def card_dict(c: Card):
+    d = asdict(c)
+    d["cooldown"] = c.cooldown
+    d["power"] = card_power(c)
+    return d

games/maze.py

@@ -0,0 +1,371 @@
+"""Ghost maze: a small Pac-Man-like game. The Pac agent is a solvi catalog of small functions over the board
+(legal moves, BFS distance to the nearest dot and to the nearest ghost per move, danger per move ...), one scoring rule,
+and a HARD check: never step onto a cell a ghost can reach this tick when a safer move exists.
+
+Pure logic, no UI: `new_game`, `agent_decide`, `step`, `run_game`, `benchmark`."""
+from __future__ import annotations
+
+import copy
+import random
+from collections import deque
+from dataclasses import dataclass, field
+
+from solvi import Answer, Catalog, Question, System
+
+LAYOUT = [
+    "#############",
+    "#.....#.....#",
+    "#.###.#.###.#",
+    "#...........#",
+    "#.#.##.##.#.#",
+    "#.#...G...#.#",
+    "#.#.##.##.#.#",
+    "#...........#",
+    "#.###.#.###.#",
+    "#.....P.....#",
+    "#############",
+]
+H, W = len(LAYOUT), len(LAYOUT[0])
+WALLS = frozenset((r, c) for r in range(H) for c in range(W) if LAYOUT[r][c] == "#")
+PAC_START = next((r, c) for r in range(H) for c in range(W) if LAYOUT[r][c] == "P")
+GHOST_HOME = next((r, c) for r in range(H) for c in range(W) if LAYOUT[r][c] == "G")
+ALL_DOTS = tuple(sorted((r, c) for r in range(H) for c in range(W) if LAYOUT[r][c] in ".G"))
+TOTAL_DOTS = len(ALL_DOTS)      # Pac's start cell has no dot
+
+DIRS = {"UP": (-1, 0), "LEFT": (0, -1), "DOWN": (1, 0), "RIGHT": (0, 1)}
+REVERSE = {"UP": "DOWN", "DOWN": "UP", "LEFT": "RIGHT", "RIGHT": "LEFT", None: None}
+MOVES = list(DIRS)
+
+# ghost tuning (chosen so the game is fair but not trivial; see benchmark numbers in the README)
+GHOSTS = [  # name, color, scatter corner, release tick
+    ("Blinky", "#ff4d4d", (1, 11), 0),
+    ("Pinky", "#ff8fd8", (1, 1), 8),
+    ("Clyde", "#ffb347", (9, 1), 16),
+]
+SCATTER, CYCLE = 7, 34          # first SCATTER ticks of every CYCLE ticks: ghosts go to their corners
+GHOST_NOISE = 0.12              # chance a ghost takes a random turn at a junction
+GHOST_SPEED = 0.9               # chance a ghost moves on a given tick
+MAX_TICKS = 400
+LIVES = 3
+DOT_POINTS, CLEAR_BONUS = 10, 200
+
+
+def step_cell(cell, move):
+    dr, dc = DIRS[move]
+    return (cell[0] + dr, cell[1] + dc)
+
+
+def open_neighbors(cell):
+    return [(m, step_cell(cell, m)) for m in MOVES if step_cell(cell, m) not in WALLS]
+
+
+def bfs_dist(start, targets):
+    """Shortest path length (through open cells) from start to the nearest cell in targets; 99 if none."""
+    targets = set(targets)
+    if not targets:
+        return 99
+    if start in targets:
+        return 0
+    seen, q = {start}, deque([(start, 0)])
+    while q:
+        cell, d = q.popleft()
+        for _, n in open_neighbors(cell):
+            if n not in seen:
+                if n in targets:
+                    return d + 1
+                seen.add(n)
+                q.append((n, d + 1))
+    return 99
+
+
+# --------------------------------------------------------------------------------------------------------------------
+# The Pac agent as a solvi catalog
+# --------------------------------------------------------------------------------------------------------------------
+
+DEFAULT_BOT_CODE = '''\
+# The Pac agent's scoring rule. It is an ordinary solvi function:
+# its argument names are facts the catalog computes each tick, its name is the fact it sets.
+# Facts you can use: pac, ghosts, dots, last_move, legal_moves, next_cells, dot_dist,
+#                    ghost_dist, ghost_reach, danger, safe_moves, dots_left
+# dot_dist / ghost_dist / danger are dicts {move: value}, moves are "UP", "DOWN", "LEFT", "RIGHT".
+
+W_DOT = 1.0       # pull toward the nearest dot
+W_GHOST = 0.6     # push away from the nearest ghost ...
+GHOST_CAP = 5     # ... but only while it is closer than this
+W_REVERSE = 0.5   # penalty for turning back (stops dithering)
+
+def greedy_move(legal_moves, dot_dist, ghost_dist, last_move):
+    back = {"UP": "DOWN", "DOWN": "UP", "LEFT": "RIGHT", "RIGHT": "LEFT"}.get(last_move)
+
+    def score(m):
+        return (-W_DOT * dot_dist[m]
+                + W_GHOST * min(ghost_dist[m], GHOST_CAP)
+                - W_REVERSE * (m == back))
+
+    return max(legal_moves, key=score)
+'''
+
+
+def load_bot(code: str = DEFAULT_BOT_CODE):
+    """exec bot code and return its greedy_move function (raises on errors)."""
+    ns: dict = {}
+    exec(compile(code, "<bot>", "exec"), ns)  # noqa: S102 - user code runs in the visitor's own browser, under games/sandbox.py's guard
+    f = ns.get("greedy_move")
+    if not callable(f):
+        raise ValueError("the code must define a function named greedy_move")
+    return f
+
+
+def build_catalog(safety: bool = True, greedy=None):
+    cat = Catalog()
+
+    @cat.fn
+    def legal_moves(pac):
+        """moves that do not bump into a wall"""
+        return [m for m, _ in open_neighbors(pac)]
+
+    @cat.fn
+    def next_cells(pac, legal_moves):
+        return {m: step_cell(pac, m) for m in legal_moves}
+
+    @cat.fn
+    def ghost_reach(ghosts):
+        """cells a ghost occupies now or can step into this tick"""
+        cells = set(ghosts)
+        for g in ghosts:
+            cells.update(n for _, n in open_neighbors(g))
+        return sorted(cells)
+
+    @cat.fn
+    def dot_dist(dots, next_cells):
+        """per move: BFS distance from the next cell to the nearest dot (0 = eats a dot)"""
+        return {m: bfs_dist(c, dots) for m, c in next_cells.items()}
+
+    @cat.fn
+    def ghost_dist(ghosts, next_cells):
+        """per move: BFS distance from the next cell to the nearest ghost"""
+        return {m: bfs_dist(c, ghosts) for m, c in next_cells.items()}
+
+    @cat.fn
+    def danger(next_cells, ghost_reach):
+        """per move: True if a ghost can be on that cell this tick"""
+        reach = set(ghost_reach)
+        return {m: c in reach for m, c in next_cells.items()}
+
+    @cat.fn
+    def safe_moves(legal_moves, danger):
+        return [m for m in legal_moves if not danger[m]]
+
+    @cat.fn
+    def dots_left(dots):
+        return len(dots)
+
+    cat.fn(greedy or load_bot())
+
+    @cat.fn
+    def evade_move(safe_moves, legal_moves, dot_dist, ghost_dist):
+        """the best safe move: closest dot among safe moves, ties -> farther from ghosts; none safe -> farthest from ghosts"""
+        if safe_moves:
+            return min(safe_moves, key=lambda m: (dot_dist[m], -ghost_dist[m]))
+        return max(legal_moves, key=lambda m: ghost_dist[m])
+
+    if safety:
+        @cat.check(hard=True, then={"move": "EVADE"})
+        def greedy_is_safe(greedy_move, danger, safe_moves):
+            """hard: the scored move may step into ghost reach only if every move does"""
+            return not danger.get(greedy_move, False) or not safe_moves
+
+    @cat.rule("move")
+    def move(greedy_move):
+        return greedy_move
+
+    @cat.rule("fallback")
+    def fallback(evade_move):
+        return evade_move
+
+    return cat
+
+
+def build_system(safety: bool = True, greedy=None):
+    cat = build_catalog(safety, greedy)
+    qs = [Question("move", "Which way should Pac go?", Answer.choice(MOVES + ["EVADE"]),
+                   checkpoints=["greedy_is_safe"] if safety else []),
+          Question("fallback", "Safest good move if the scored move is refused", Answer.choice(MOVES))]
+    return cat, System(cat, qs)
+
+
+# --------------------------------------------------------------------------------------------------------------------
+# Game engine
+# --------------------------------------------------------------------------------------------------------------------
+
+@dataclass
+class Ghost:
+    name: str
+    color: str
+    corner: tuple
+    release: int
+    pos: tuple = GHOST_HOME
+    dir: str | None = None
+
+
+@dataclass
+class MazeGame:
+    seed: int = 0
+    pac: tuple = PAC_START
+    last_move: str | None = None
+    ghosts: list = field(default_factory=list)
+    dots: set = field(default_factory=lambda: set(ALL_DOTS))
+    score: int = 0
+    lives: int = LIVES
+    tick: int = 0
+    life_tick: int = 0
+    over: bool = False
+    won: bool = False
+    deaths: int = 0
+    forced: int = 0
+    log: list = field(default_factory=list)
+    rng: random.Random = field(default_factory=random.Random)
+
+    def state(self):
+        """init_state for the agent"""
+        return {"pac": self.pac, "ghosts": [g.pos for g in self.ghosts], "dots": sorted(self.dots),
+                "last_move": self.last_move}
+
+
+def new_game(seed: int = 0) -> MazeGame:
+    g = MazeGame(seed=seed, rng=random.Random(seed))
+    g.ghosts = [Ghost(n, col, corner, rel) for n, col, corner, rel in GHOSTS]
+    return g
+
+
+def _ghost_target(game, gh):
+    if game.life_tick % CYCLE < SCATTER:
+        return gh.corner
+    p = game.pac
+    if gh.name == "Pinky" and game.last_move:
+        dr, dc = DIRS[game.last_move]
+        return (p[0] + 2 * dr, p[1] + 2 * dc)
+    if gh.name == "Clyde" and abs(gh.pos[0] - p[0]) + abs(gh.pos[1] - p[1]) <= 4:
+        return gh.corner
+    return p
+
+
+def _move_ghosts(game):
+    for gh in game.ghosts:
+        if game.life_tick < gh.release or game.rng.random() > GHOST_SPEED:
+            continue
+        opts = [(m, c) for m, c in open_neighbors(gh.pos) if m != REVERSE[gh.dir]] or open_neighbors(gh.pos)
+        if game.rng.random() < GHOST_NOISE:
+            m, c = game.rng.choice(opts)
+        else:
+            t = _ghost_target(game, gh)
+            m, c = min(opts, key=lambda mc: (mc[1][0] - t[0]) ** 2 + (mc[1][1] - t[1]) ** 2)
+        gh.pos, gh.dir = c, m
+
+
+def _caught(game):
+    return any(gh.pos == game.pac for gh in game.ghosts)
+
+
+def _lose_life(game):
+    game.lives -= 1
+    game.deaths += 1
+    game.pac, game.last_move, game.life_tick = PAC_START, None, 0
+    for gh in game.ghosts:
+        gh.pos, gh.dir = GHOST_HOME, None
+    if game.lives <= 0:
+        game.over = True
+
+
+def agent_decide(system, game, safety=True):
+    """Ask the solvi agent. Returns (move, response, note) where note says whether the hard check fired."""
+    names = ["move", "fallback"] if safety else ["move"]
+    resp = system.ask(game.state(), names)
+    r = resp["move"]
+    if r.status == "forced":
+        return resp["fallback"].answer, resp, "forced"
+    if r.status == "abstain" or r.answer is None:
+        legal = [m for m, _ in open_neighbors(game.pac)]
+        return legal[0], resp, "abstain"
+    return r.answer, resp, "ok"
+
+
+def describe(move, resp, note):
+    """one log line: 'move LEFT — nearest dot 3 away, ghost 5 away (safe)'"""
+    v = resp.values
+    dd, gd, dg = v.get("dot_dist", {}), v.get("ghost_dist", {}), v.get("danger", {})
+    risky = dg[move] if move in dg else gd.get(move, 99) <= 1      # without the check, danger is not computed: same test
+    tail = f"nearest dot {dd.get(move, '?')} away, ghost {gd.get(move, '?')} away ({'DANGER' if risky else 'safe'})"
+    if note == "forced":
+        want = v.get("greedy_move")
+        return f"move {move} — hard check refused {want} (ghost could reach it); {tail}"
+    if note == "abstain":
+        return f"move {move} — rule abstained ({resp['move'].why[:60]}); {tail}"
+    return f"move {move} — {tail}"
+
+
+def step(game: MazeGame, move: str, note: str = "") -> str:
+    """Advance one tick with Pac playing `move`. Returns an event string ('' / 'dot' / 'caught' / 'won' / 'over')."""
+    if game.over:
+        return "over"
+    game.tick += 1
+    game.life_tick += 1
+    if note == "forced":
+        game.forced += 1
+    nxt = step_cell(game.pac, move)
+    if nxt not in WALLS:
+        game.pac = nxt
+        game.last_move = move
+    event = ""
+    if game.pac in game.dots:
+        game.dots.discard(game.pac)
+        game.score += DOT_POINTS
+        event = "dot"
+    if not game.dots:
+        game.score += CLEAR_BONUS
+        game.over = game.won = True
+        return "won"
+    if _caught(game):
+        _lose_life(game)
+        return "over" if game.over else "caught"
+    _move_ghosts(game)
+    if _caught(game):
+        _lose_life(game)
+        return "over" if game.over else "caught"
+    if game.tick >= MAX_TICKS:
+        game.over = True
+        return "over"
+    return event
+
+
+def run_game(system, seed, safety=True, max_ticks=MAX_TICKS):
+    g = new_game(seed)
+    while not g.over and g.tick < max_ticks:
+        mv, _, note = agent_decide(system, g, safety)
+        step(g, mv, note)
+    return {"won": g.won, "score": g.score, "dots": TOTAL_DOTS - len(g.dots), "deaths": g.deaths,
+            "ticks": g.tick, "forced": g.forced}
+
+
+def summarize(results):
+    n = len(results)
+    return {"games": n,
+            "win_rate": sum(r["won"] for r in results) / n,
+            "avg_score": sum(r["score"] for r in results) / n,
+            "avg_dots_pct": sum(r["dots"] for r in results) / n / TOTAL_DOTS,
+            "avg_deaths": sum(r["deaths"] for r in results) / n,
+            "avg_forced": sum(r["forced"] for r in results) / n}
+
+
+def benchmark(n=100, greedy=None, seeds_from=0):
+    """n seeded games with and without the hard safety check (same seeds, same scoring rule)."""
+    out = {}
+    for safety in (True, False):
+        _, sysm = build_system(safety, greedy)
+        out["with_check" if safety else "without_check"] = summarize(
+            [run_game(sysm, seeds_from + s, safety) for s in range(n)])
+    return out
+
+
+def snapshot(game):
+    return copy.deepcopy(game)

games/sandbox.py

@@ -0,0 +1,112 @@
+"""Run user bot code for the maze in-process, in the visitor's own browser (Pyodide has no subprocesses).
+
+The code is exec'd in a fresh namespace. A sys.settrace guard counts the lines executed in the user's code (the file
+"<bot>" only, so solvi and the game engine run at full speed) and stops the run when one call executes too many lines
+(an infinite loop) or the whole run passes a wall-clock deadline. The guard raises BotStopped, a BaseException, so solvi
+(which turns ordinary exceptions of a step into an abstain) cannot swallow it and the run ends at once.
+
+This protects against runaway Python loops in the bot. It is not a security sandbox, and it cannot interrupt a loop that
+runs inside C code (for example sum(itertools.count())); there the tab has to be reloaded."""
+from __future__ import annotations
+
+import builtins
+import functools
+import sys
+import time
+
+from . import maze
+
+MAX_CODE = 20_000
+N_GAMES = 20
+MAX_LINES_PER_CALL = 200_000     # lines of user code in one call of the bot (or in the module body)
+DEADLINE_S = 30.0                # the whole run of N_GAMES games (about 6 s on a laptop)
+
+
+class BotStopped(BaseException):
+    """Raised by the guard. BaseException on purpose: solvi catches Exception from a step, not this."""
+
+
+class Guard:
+    def __init__(self, max_lines=MAX_LINES_PER_CALL, deadline_s=DEADLINE_S):
+        self.max_lines, self.deadline_s = max_lines, deadline_s
+        self.t_end = time.perf_counter() + deadline_s
+        self.lines = 0
+
+    def _local(self, frame, event, arg):
+        if event == "line":
+            self.lines += 1
+            if self.lines > self.max_lines:
+                raise BotStopped(f"stopped: one call of your code ran more than {self.max_lines:,} lines "
+                                 f"(an infinite loop?), at line {frame.f_lineno}")
+            if not self.lines & 1023 and time.perf_counter() > self.t_end:
+                raise BotStopped(f"stopped: the run took longer than {self.deadline_s:.0f} s")
+        return self._local
+
+    def _global(self, frame, event, arg):
+        return self._local if frame.f_code.co_filename == "<bot>" else None
+
+    def call(self, f, *args, **kwargs):
+        if time.perf_counter() > self.t_end:
+            raise BotStopped(f"stopped: the run took longer than {self.deadline_s:.0f} s")
+        self.lines = 0
+        old = sys.gettrace()
+        sys.settrace(self._global)
+        try:
+            return f(*args, **kwargs)
+        finally:
+            sys.settrace(old)
+
+
+def load_guarded(code: str, guard: Guard):
+    """exec the code in a fresh namespace under the guard; return greedy_move wrapped so every call is guarded too."""
+    ns = {"__name__": "user_bot", "__builtins__": builtins}
+    guard.call(exec, compile(code, "<bot>", "exec"), ns)  # noqa: S102 - the visitor's own code, in their own browser
+    f = ns.get("greedy_move")
+    if not callable(f):
+        raise ValueError("the code must define a function named greedy_move")
+
+    @functools.wraps(f)          # keeps the name and the signature: solvi reads the argument names
+    def greedy_move(*args, **kwargs):
+        return guard.call(f, *args, **kwargs)
+    return greedy_move
+
+
+def _error_tail(e: BaseException) -> str:
+    """the traceback lines that point into the user's code, plus the error itself"""
+    import traceback
+    lines = traceback.format_exception(type(e), e, e.__traceback__)
+    at = next((i for i, ln in enumerate(lines) if 'File "<bot>"' in ln), None)
+    return "".join(lines[at:] if at is not None else lines[-1:]).strip()
+
+
+def run_bot(code: str, n: int = N_GAMES, safety: bool = True) -> dict:
+    """Returns {"ok": True, "summary": ..., "games": [...], "abstains": k, ...} or {"ok": False, "error": text, "kind": ...}."""
+    if len(code) > MAX_CODE:
+        return {"ok": False, "kind": "too long", "error": f"code is {len(code)} characters; the limit is {MAX_CODE}"}
+    guard = Guard()
+    try:
+        greedy = load_guarded(code, guard)
+        _, system = maze.build_system(safety, greedy)
+        games, abstains, first_error = [], 0, None
+        for seed in range(n):
+            g = maze.new_game(seed)
+            while not g.over:
+                mv, resp, note = maze.agent_decide(system, g, safety)
+                if note == "abstain":
+                    abstains += 1
+                    if abstains == 1:
+                        errs = [r.error for r in resp.trace.records if r.name == "greedy_move" and r.error]
+                        first_error = errs[0] if errs else resp["move"].why
+                maze.step(g, mv, note)
+            games.append({"won": g.won, "score": g.score, "dots": maze.TOTAL_DOTS - len(g.dots), "deaths": g.deaths,
+                          "ticks": g.tick, "forced": g.forced})
+    except BotStopped as e:
+        return {"ok": False, "kind": "stopped by the guard", "error": str(e)}
+    except (KeyboardInterrupt, SystemExit) as e:
+        return {"ok": False, "kind": "error", "error": f"{type(e).__name__}: {e}"}
+    except Exception as e:  # noqa: BLE001 - syntax errors, a missing greedy_move, errors in the module body
+        return {"ok": False, "kind": "error", "error": _error_tail(e)}
+    out = {"ok": True, "summary": maze.summarize(games), "games": games, "abstains": abstains}
+    if abstains:
+        out["first_error"] = first_error
+    return out

games/tictactoe.py

@@ -0,0 +1,131 @@
+"""Tic-tac-toe vs solvi. The catalog is a vendored copy of solvi/examples/05_tic_tac_toe.py (games/_ttt_catalog.py).
+We add one more rule to it, "reason", which names why the move was chosen (win, block, fork ...), so every agent move
+comes with a readable label on top of the rule inputs."""
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from solvi import Answer, Question, System
+
+from . import _ttt_catalog as _mod
+
+SOURCE = "solvi/examples/05_tic_tac_toe.py"
+cat = _mod.cat
+LINES = _mod.LINES
+winner_of = _mod._winner
+
+REASONS = {
+    "win": "completes a line and wins",
+    "block": "blocks your line",
+    "fork": "creates two threats at once (a fork)",
+    "block_fork": "takes your only fork cell",
+    "forcing": "makes a threat you must answer, so you cannot build your fork",
+    "center": "takes the center (nothing urgent on the board)",
+    "corner": "takes a corner (nothing urgent on the board)",
+    "edge": "takes an edge (nothing urgent on the board)",
+    "none": "no move",
+}
+
+
+@cat.rule("reason")
+def move_reason(winning_moves, blocking_moves, fork_moves, opponent_forks, forcing_moves, free_cells):
+    """mirrors pick_move's order and names the branch that decided"""
+    for label, group in (("win", winning_moves), ("block", blocking_moves), ("fork", fork_moves)):
+        if group:
+            return label
+    if len(opponent_forks) == 1:
+        return "block_fork"
+    if opponent_forks and forcing_moves:
+        return "forcing"
+    for c in (4, 0, 2, 6, 8, 1, 3, 5, 7):
+        if c in free_cells:
+            return "center" if c == 4 else "corner" if c in (0, 2, 6, 8) else "edge"
+    return "none"
+
+
+QUESTIONS = list(_mod.QUESTIONS) + [
+    Question("reason", "Why this move?", Answer.choice(list(REASONS)), checkpoints=["board_valid"])]
+system = System(cat, QUESTIONS)
+
+
+@dataclass
+class TTTGame:
+    human: str = "X"
+    board: str = "." * 9
+    over: bool = False
+    result: str = ""                 # "agent" | "human" | "draw"
+    last_agent_cell: int | None = None
+    counted: bool = False            # already added to the win/loss counters
+    history: list = field(default_factory=list)
+
+    @property
+    def agent(self):
+        return "O" if self.human == "X" else "X"
+
+    @property
+    def turn(self):
+        return "X" if self.board.count("X") == self.board.count("O") else "O"
+
+
+def _finish(game):
+    w = winner_of(game.board)
+    if w or "." not in game.board:
+        game.over = True
+        game.result = "draw" if not w else ("agent" if w == game.agent else "human")
+
+
+def agent_move(game):
+    """The agent plays one move. Returns the solvi Response (or None if it was not the agent's turn)."""
+    if game.over or game.turn != game.agent:
+        return None
+    resp = system.ask({"board": game.board, "me": game.agent}, ["move", "reason"])
+    ans = resp["move"].answer
+    if ans is None or ans == "none":
+        return resp
+    c = int(ans)
+    game.board = game.board[:c] + game.agent + game.board[c + 1:]
+    game.last_agent_cell = c
+    game.history.append((game.agent, c, resp["reason"].answer))
+    _finish(game)
+    return resp
+
+
+def human_move(game, cell):
+    """Returns an error text, or '' when the move was played."""
+    if game.over:
+        return "The game is over. Press New game."
+    if game.turn != game.human:
+        return "Wait for the agent."
+    if game.board[cell] != ".":
+        return "That cell is taken."
+    game.board = game.board[:cell] + game.human + game.board[cell + 1:]
+    game.history.append((game.human, cell, None))
+    _finish(game)
+    return ""
+
+
+def new_game(human="X"):
+    g = TTTGame(human=human)
+    resp = agent_move(g) if g.agent == "X" else None
+    return g, resp
+
+
+def explain_position(board, me):
+    """All facts for `me` on this board (the 'explain the position' view)."""
+    return system.ask({"board": board, "me": me})
+
+
+def vs_random(n=500, seed=0):
+    """n games against a uniformly random opponent, agent side alternating at random. Returns counts."""
+    rng = random.Random(seed)
+    out = {"agent": 0, "draw": 0, "human": 0}
+    for _ in range(n):
+        g, _ = new_game(rng.choice("XO"))
+        while not g.over:
+            if g.turn == g.human:
+                human_move(g, rng.choice([i for i in range(9) if g.board[i] == "."]))
+            else:
+                agent_move(g)
+        out[g.result] += 1
+    return out

index.html

@@ -1,19 +1,106 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>solvi arcade</title>
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22%3E%3Ctext y=%22.9em%22 font-size=%2290%22%3E🕹️%3C/text%3E%3C/svg%3E" />
+  <meta name="description" content="Game agents built with solvi from small Python functions, rules and hard checks. They explain every move and run entirely in your browser." />
+  <script>
+    // Package "time machine" for Gradio-Lite 5.45.0 (released 2025-09-10).
+    // Its Python worker installs gradio 5.45 with micropip, whose resolver is greedy: gradio_client asks for
+    // huggingface-hub>=0.19.3 and gets 1.x/2.x, and then gradio's huggingface-hub<1.0 pin (and anyio<5, ...) fails.
+    // Fix: inside the worker, PyPI's simple index is filtered to files uploaded before the Gradio-Lite release, so every
+    // package resolves to what existed when that release was built. solvi is exempt (it needs the current version).
+    (() => {
+      const prelude = `(() => {
+        const CUTOFF = Date.parse("2025-09-10T17:00:00Z");
+        const EXEMPT = new Set(["solvi"]);
+        const realFetch = self.fetch.bind(self);
+        self.fetch = async (input, init) => {
+          const url = typeof input === "string" ? input : (input && input.url) || String(input);
+          const m = /^https:\\/\\/pypi\\.org\\/simple\\/([^/?#]+)\\/?$/.exec(url);
+          const resp = await realFetch(input, init);
+          if (!m || EXEMPT.has(m[1].toLowerCase()) || !resp.ok) return resp;
+          try {
+            const data = await resp.clone().json();
+            if (!Array.isArray(data.files)) return resp;
+            const kept = data.files.filter(f => !f["upload-time"] || Date.parse(f["upload-time"]) <= CUTOFF);
+            if (!kept.length) return resp;
+            data.files = kept;
+            return new Response(JSON.stringify(data), { status: 200, headers: {
+              "Content-Type": resp.headers.get("Content-Type") || "application/vnd.pypi.simple.v1+json" } });
+          } catch (e) { return resp; }
+        };
+      })();`;
+      const RealWorker = window.Worker;
+      window.Worker = function (url, opts) {
+        const boot = new Blob([prelude, "\nimportScripts(" + JSON.stringify(new URL(String(url), location.href).href) + ");"], { type: "text/javascript" });
+        return new RealWorker(URL.createObjectURL(boot), opts);
+      };
+      window.Worker.prototype = RealWorker.prototype;
+    })();
+  </script>
+  <script type="module" crossorigin src="https://cdn.jsdelivr.net/npm/@gradio/lite@5.45.0/dist/lite.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@gradio/lite@5.45.0/dist/lite.css" />
+  <style>
+    :root { --sv-bg: #ffffff; --sv-fg: #1f2937; --sv-dim: #6b7280; --sv-card: #f6f3ff; --sv-border: #ddd6fe; --sv-accent: #7c3aed; }
+    @media (prefers-color-scheme: dark) {
+      :root:not([data-theme="light"]) { --sv-bg: #0b0f19; --sv-fg: #e5e7eb; --sv-dim: #9ca3af; --sv-card: #1a1530; --sv-border: #3b2f6b; --sv-accent: #a78bfa; }
+    }
+    :root[data-theme="dark"] { --sv-bg: #0b0f19; --sv-fg: #e5e7eb; --sv-dim: #9ca3af; --sv-card: #1a1530; --sv-border: #3b2f6b; --sv-accent: #a78bfa; }
+    html, body { margin: 0; background: var(--sv-bg); }
+    #sv-loading { max-width: 720px; margin: 24px auto 0; padding: 0 16px; box-sizing: border-box;
+      font-family: system-ui, -apple-system, "Segoe UI", sans-serif; color: var(--sv-fg); }
+    #sv-loading .card { background: var(--sv-card); border: 1px solid var(--sv-border); border-radius: 14px; padding: 16px 18px; }
+    #sv-loading h1 { font-size: 1.35rem; margin: 0 0 6px; }
+    #sv-loading p { margin: 6px 0; line-height: 1.45; font-size: 0.95rem; }
+    #sv-loading .dim { color: var(--sv-dim); font-size: 0.85rem; }
+    #sv-loading a { color: var(--sv-accent); }
+    #sv-loading .bar { height: 4px; border-radius: 2px; background: var(--sv-border); overflow: hidden; margin-top: 12px; }
+    #sv-loading .bar div { width: 30%; height: 100%; background: var(--sv-accent); border-radius: 2px; animation: sv-slide 1.4s ease-in-out infinite; }
+    @keyframes sv-slide { 0% { margin-left: -30%; } 100% { margin-left: 100%; } }
+    #sv-loading.gone { display: none; }
+  </style>
+</head>
+<body>
+  <div id="sv-loading" role="status">
+    <div class="card">
+      <h1>🕹️ solvi arcade is starting in your browser</h1>
+      <p>The game agents are Python, and they run on your machine, not on a server. The first visit downloads a Python
+        runtime (Pyodide) with numpy, scipy, Gradio and <a href="https://github.com/solvi-ai/solvi">solvi</a>:
+        about 20–30 MB, once. Later visits load it from the browser cache.</p>
+      <p class="dim">This usually takes 20–60 seconds on the first visit.</p>
+      <div class="bar"><div></div></div>
+    </div>
+  </div>
+
+  <gradio-lite>
+    <gradio-requirements>
+solvi>=0.1.1
+    </gradio-requirements>
+    <gradio-file name="app.py" url="app.py" entrypoint></gradio-file>
+    <gradio-file name="games/__init__.py" url="games/__init__.py"></gradio-file>
+    <gradio-file name="games/_ttt_catalog.py" url="games/_ttt_catalog.py"></gradio-file>
+    <gradio-file name="games/tictactoe.py" url="games/tictactoe.py"></gradio-file>
+    <gradio-file name="games/explain.py" url="games/explain.py"></gradio-file>
+    <gradio-file name="games/maze.py" url="games/maze.py"></gradio-file>
+    <gradio-file name="games/fusion.py" url="games/fusion.py"></gradio-file>
+    <gradio-file name="games/sandbox.py" url="games/sandbox.py"></gradio-file>
+  </gradio-lite>
+
+  <script>
+    // Gradio-Lite fetches file URLs from its web worker, where a relative URL would not resolve against this page.
+    // This classic script runs before the deferred lite.js module, so the URLs are absolute when it reads them.
+    for (const el of document.querySelectorAll("gradio-file[url]")) {
+      el.setAttribute("url", new URL(el.getAttribute("url"), document.baseURI).href);
+    }
+    // Hide the loading note once the app has rendered its header.
+    const note = document.getElementById("sv-loading");
+    const obs = new MutationObserver(() => {
+      if (document.getElementById("hero")) { note.classList.add("gone"); obs.disconnect(); }
+    });
+    obs.observe(document.body, { childList: true, subtree: true });
+  </script>
+</body>
 </html>