# AGENTS.md

## Current status

Step 2 completed and verified. Ready to start Step 3.

## Completed steps

Initial setup before Step 1:

- `uv` package metadata exists.
- Runtime dependency `dearpygui` is installed.
- Dev dependencies `pytest`, `ruff`, and `pyright` are installed.
- Required package skeleton exists under `src/dpg_gauges/`.
- `examples/`, `tests/`, and `docs/` directories exist.
- `pyproject.toml` is configured for Python 3.11+, Ruff, and Pyright.

Step 1 - Public API contract and pure core:

- Public API exports are defined in `src/dpg_gauges/__init__.py`.
- Public exceptions are defined in `src/dpg_gauges/exceptions.py`.
- Shared public dataclasses and type aliases are defined in `src/dpg_gauges/types.py`.
- Pure gauge configuration dataclasses are defined in `src/dpg_gauges/gauges.py`.
- Pure scale helpers are defined in `src/dpg_gauges/scales.py`.
- Lightweight theme/style presets are defined in `src/dpg_gauges/themes.py`.
- GUI-dependent public functions are import-safe stubs for Step 1.
- Step 1 tests cover public imports, dataclass construction, clamp/normalize math, tick generation, threshold validation, formatting, and missing-gauge stubs.

## Current step

Step 3 - Widget shell and renderer foundation.

Step 2 - State, sizing, animation, and smoothing model:

Implemented during Step 2:

- Added `DpgGaugesConfig`, `configure(...)` wiring, `GaugeState`, `DirtyFlags`, and the global gauge registry.
- Runtime API functions now mutate logical state for values, config updates, thresholds, markers, visibility, and deletion without Dear PyGui calls.
- Added pure sizing helpers for requested/measured size, last non-zero size preservation, square rects, and stretch rects.
- Added pure animation interpolation helpers and smoothing progression helpers.
- Added debug state reporting for registered gauges.
- Added Step 2 tests for registry behaviour, clamped/displayed separation, dirty flags, sizing, animation, smoothing, and invalid values.

## Design decisions

- Package is managed with uv.
- Public import is `import dpg_gauges as dpgg`.
- Package target is Python 3.11+.
- The package is Dear PyGui-only, but pure configuration/state helpers should avoid Dear PyGui imports where practical.
- Widget creation and Dear PyGui item operations are GUI-thread-only.
- Runtime value/configuration updates are intended to be called from the GUI thread.
- High-frequency updates should be smoothed/coalesced so gauges remain readable and flicker-free.
- Out-of-range values clamp to min/max and display the clamped value.
- Gauges are display-only for the first release.
- Thresholds and redline zones are visual only; they do not trigger events.
- The public API should feel like normal Dear PyGui context-manager usage.
- Each completed build step must be checked, documented in this file, and committed before starting the next step.

## Known issues

None yet.

## Commands used

- Read `codex-old/README.md`, `codex-old/FEATURES.md`, `codex-old/ARCHITECTURE.md`, `codex-old/STEPS.md`, and `codex-old/AGENTS.md`.
- Inspected `/home/hector/projects/dpg-map` package, examples, tests, docs, and pyproject structure.
- Created the initial `codex/` instruction documents for `dpg-gauges`.
- Read `codex/README.md`, `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md`.
- Completed missing pre-Step-1 skeleton files and directories.
- Ran `uv run python -c "import dpg_gauges; print(dpg_gauges.__name__)"`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format .`.
- Read all files under `codex/`.
- Implemented Step 1 public API exports and pure core modules.
- Added `tests/test_step1_core.py`.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 2 changes.
- Implemented Step 2 state, sizing, animation, smoothing, runtime API, diagnostics, tests, and README status update.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Updated instructions to require a commit after each completed step.

## Next action

Implement Step 3.