AGENTS.md

Current status

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

Initial setup before Step 1:

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.

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.

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.

None yet.

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.

Implement Step 3.