# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development

```bash
uv sync                    # Install dependencies
pytest                     # Run all tests (138 tests)
pytest tests/test_bbox.py  # Run a single test file
pytest -k "test_name"      # Run tests matching a pattern
uv build                   # Build distributions
```

Package manager is `uv` with `hatchling` build backend. Python 3.13+ required.

## Architecture

Coordinate transformation library for GUI agents — maps coordinates and bounding boxes between screen resolutions, handling letterbox and stretch transforms.

### Core Classes

All core classes are **frozen Pydantic BaseModel** instances (immutable). `ResizeMetadata` is a frozen dataclass.

- **Space** — width/height dimensions (both must be > 1)
- **Coordinate** — (x, y) point within a Space. `to_space()` remaps to a different Space using pixel-center ratio scaling: `round(old * (target-1) / (source-1))`
- **BBox** — bounding box (x, y, width, height) within a Space. Transforms via corner remapping. Supports `offset` parameter for window-to-screen coordinate translation in one step
- **Screenshot** — image bytes + Space metadata. `resize()` produces a new Screenshot with `resize_metadata` tracking the transformation
- **ResizeMetadata** — stores scale/offset from a resize. `transform_coordinate()` does inverse transform (detection space → original), `forward_transform_coordinate()` does forward
- **ResizeMode** — enum: `LETTERBOX` (aspect-preserving with black padding) or `STRETCH` (distorts to fill)

### Transformation Pipeline

```
Source screenshot (e.g. 1920x1080)
  → resize(target, mode) → resized Screenshot + ResizeMetadata
    → model detects BBox in resized space
      → bbox.to_space(original_space, resize_metadata, offset=window_bbox)
        → screen-space coordinates
```

### Key Patterns

- **Circular import avoidance**: `coordinate.py` and `bbox.py` import `ResizeMetadata` under `TYPE_CHECKING` only
- **Space consistency validation**: operations between Coordinate/BBox and ResizeMetadata verify matching spaces
- **BBox window offset**: `BBox.to_space(target, metadata, offset=window_bbox)` undoes resize and applies window position in one call

## Testing

Tests use **class-based grouping** by functionality (e.g., `TestCreationAndValidation`, `TestToSpace`). Shared fixtures for common screen resolutions live in `tests/conftest.py`. Integration tests in `test_integration.py` verify full roundtrip pipelines and pixel-level letterbox correctness.