dpg-map/AGENTS.md

AGENTS.md

Current status

Step 2 complete.

Completed steps

Step 1 - Public API contract and pure core. Step 2 - Thread-safe state, commands, overlays, and cache model.

Current step

Step 3 - Widget shell, sizing system, and GUI-thread frame pump.

Design decisions

• Package is managed with uv.
• Public import is import dpg_map as dpgm.
• Dear PyGui calls are GUI-thread-only.
• Runtime public calls enqueue commands or update logical state.
• Overlay updates must not reset center/zoom.
• The widget uses child_window + measured-size drawlist.
• Tiles use a memory cache and persistent disk cache.
• Tile providers are interchangeable.

Known issues

None yet.

Commands used

• Read STEPS.md, FEATURES.md, and ARCHITECTURE.md.
• Created initial package, examples, tests, and agent-log structure.
• Implemented public exports, exceptions, common types, tile provider registry, projection helpers, cache dataclasses, and GUI-dependent API stubs.
• Added Step 1 tests for imports, providers, projection, and cache dataclasses.
• Implemented global configuration, logical MapState, map registry, and current map context stack.
• Implemented DirtyFlags, MapCommand, CommandKind, and coalescing MapCommandQueue.
• Implemented logical marker, polyline, trajectory, and layer state models.
• Implemented public runtime overlay/view/layer/provider/cache/debug wrappers against logical state without Dear PyGui calls.
• Implemented memory cache metadata, disk cache path generation, metadata read/write, disk size scanning, and prune planning.
• Added Step 2 tests for command coalescing, overlay/view isolation, copied trajectory inputs, coordinate length validation, layer state, disk path generation, and prune ordering.
• 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 3.