step 2: add gauge state sizing and animation model

codex/AGENTS.md

@@ -2,15 +2,44 @@
 
 ## Current status
 
-Project instruction set initialized.
+Step 2 completed and verified. Ready to start Step 3.
 
 ## Completed steps
 
-None yet.
+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 1 - Public API contract and pure core.
+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
 
@@ -25,6 +54,7 @@ Step 1 - Public API contract and pure core.
 - 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
 
@@ -35,7 +65,26 @@ 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.
 
 ## Next action
 
-Implement Step 1.
+Implement Step 3.