betza-visualizer

Visualizes fairy chess piece movements from their Betza notation.

The project contains:

• a reusable dependency-free Python package, importable as betza_visualizer
• a Python Textual TUI frontend
• a browser frontend using TypeScript, HTML, CSS, and SVG

Python library usage

The core parser and SVG renderer have no runtime dependencies:

from betza_visualizer import BetzaParser, BetzaSvgOptions, render_betza_svg

moves = BetzaParser().parse("BN", board_size=11)
svg = render_betza_svg("BN", BetzaSvgOptions(piece_label="A", title="Archbishop movement"))

The generated SVG string is intended to be embedded directly into documentation pages.

TypeScript library usage

The browser parser is also published as @pychess/betza. The visualizer and consumers such as premove generators use the same parsed movement model:

import { BetzaParser, createBetzaPremove, parseBetza } from "@pychess/betza";

const movement = parseBetza("fRffN");
const visualizerMoves = new BetzaParser().parse("fRffN", 8);
const premove = createBetzaPremove("fRffN");
const targets = premove({
  origin: [3, 3],
  color: "white",
  board: { width: 8, height: 8 },
});

Premove targets are intentionally conservative: current blockers, occupancy, capture modality, hopper screens, and check legality are ignored because the opponent may change the position first. The game server must validate the move when it is eventually submitted.

The parser remains permissive and reports unsupported fragments through the warnings property. This preserves the visualizer's best-effort behavior and allows broader original Betza and future XBetza support without adding separate consumer-specific parsers.

Try the web app

The browser frontend is available online:

https://betza-visualizer.vercel.app/

Run the TUI locally

The Textual TUI frontend currently lives in the repository-level main.py, so clone the repository frst:

git clone https://github.com/gbtami/betza-visualizer.git
cd betza-visualizer

Then install the optional TUI dependencies and start the app:

python -m venv .venv
source .venv/bin/activate
pip install -e '.[tui]'
python main.py

On Windows, activate the virtual environment with:

.venv\Scripts\Activate.ps1

If you use uv, the shorter equivalent is:

uv run --extra tui python main.py

Inside the TUI, type a Betza expression, pick a built-in piece from the list, change the board size from the selector, or click board squares to toggle blockers. Press F1 for the in-app help and Ctrl+L to load pieces from a local variants.ini file.

Development

pip install -e '.[dev]'
python -m pytest tests/python_unittests

Publishing

The package metadata is defined in pyproject.toml. A local wheel can be built with:

python -m build

Almost everything in this repository made by using Google and OpanAI tools.

Google AI Studio, gemini-cli, Google Labs Jules using gemini-2.5-pro, gemini2.5-flash

codex-cli using gpt-5.4-codex, gpt-5.5-codex