CONTRIBUTING.md

# Contributing to Toaster

Thanks for helping! This is a small, focused project — the bar is simply:
**green checks, and the architecture stays clean.**

## Setup

```bash
uv venv && uv pip install -e ".[dev]"     # or: pip install -e ".[dev]"
pre-commit install                         # optional: ruff on every commit
```

## Before you push

```bash
make check     # ruff check + ruff format --check + pytest
```

CI runs exactly this on Python 3.11 and 3.12 for every push and PR. Please keep
it green and add a test for any behaviour change (the suite is headless and
fast — no GUI needed).

## Architecture rules (please keep these)

- `toaster.core` is **numpy-only and headless** — it must never import a GUI,
  a renderer, or a web framework. `tests/test_architecture.py` enforces this.
- Dependencies flow one way: `core` ← `io / segment / persistence` ←
  `interaction` ← `api / web`. The browser receives only numpy arrays and a flat
  snapshot, never colour buffers.
- The two public extension seams are `Segmenter` (`@register_segmenter`) and
  `Loader` (`register_loader`). New built-ins go through them; see the README for
  worked examples.

## Style

- `ruff` for lint **and** formatting (config in `pyproject.toml`).
- Type hints and `from __future__ import annotations` everywhere; docstrings with
  Args/Returns on public API.
- Code, comments and docs in English.