# AGENTS.md

## Current status

Step 5 completed and verified with automated checks. Step 5 commit is pending.

## 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 6 - High-rate updates, animation, and stress examples.

Step 5 - Analog, segmented, compass, thermometer, battery, and multi-value gauges:

Implemented during Step 5:

- Added analog and compass dial rendering with arcs, ticks, tick labels, needles, redline bands, and markers.
- Added compass heading wraparound for runtime values.
- Added segmented gauge rendering with active segment calculation.
- Added thermometer and battery-specific drawlist rendering.
- Added multi-value gauge rendering.
- Added Step 5 examples and tests for angle math, tick generation, compass wraparound, segment activation, battery clamp, and multi-value rendering.

Step 4 - Digital, bar, level, and status gauges:

Implemented during Step 4:

- Added digital gauge drawlist rendering with formatted value text.
- Added bar and level gauge rendering with horizontal/vertical fill geometry.
- Added threshold band and marker drawing for bar/level gauges.
- Added status light rendering with configured status state colors and text.
- Added Dear PyGui item callback wiring for gauges with `callback=`.
- Added Step 4 examples and tests for geometry, runtime updates, thresholds, markers, and status states.

Step 3 - Widget shell and renderer foundation:

Implemented during Step 3:

- Added Dear PyGui widget shell creation for gauge context managers when a DPG context is active.
- Kept pure registration behavior when no DPG context has been created.
- Added a renderer foundation that measures drawlist size, redraws stable placeholder background/frame/value text, schedules animation frames, and exposes renderer debug fields.
- Added draw layer bookkeeping.
- Added lightweight `gauge_panel` and `gauge_grid` containers.
- Added Step 3 examples and smoke tests.

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 

Manual visual example checks for Steps 3, 4, and 5 were not run in this headless session.

## 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`.
- Committed Step 4 with `git commit -m "step 4: add digital bar level and status gauges"` before starting Step 5.
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 5 changes.
- Implemented Step 5 first catalogue rendering, compass wraparound, examples, README status update, and tests.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format .`.
- 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.
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 3 changes.
- Implemented Step 3 widget shells, renderer foundation, draw layer bookkeeping, layout helpers, examples, smoke tests, README status update, and diagnostics renderer fields.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.
- Committed Step 3 with `git commit -m "step 3: add widget shell and renderer foundation"` before starting Step 4.
- Read `codex/FEATURES.md`, `codex/ARCHITECTURE.md`, `codex/STEPS.md`, and `codex/AGENTS.md` before Step 4 changes.
- Implemented Step 4 digital, bar, level, and status rendering, threshold/marker drawing, callback wiring, examples, README status update, and tests.
- Ran `uv run pytest`.
- Ran `uv run ruff check .`.
- Ran `uv run ruff format --check .`.
- Ran `uv run pyright`.

## Next action 

Commit Step 5, then implement Step 6.