109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Current status
|
|
|
|
Step 3 completed and verified with automated checks. Ready to start Step 4.
|
|
|
|
## 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 4 - Digital, bar, level, and status gauges.
|
|
|
|
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 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`.
|
|
- 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`.
|
|
|
|
## Next action
|
|
|
|
Implement Step 4.
|