dpg-map/AGENTS.md

AGENTS.md

Current status

Step 6 complete.

Completed steps

Step 1 - Public API contract and pure core. Step 2 - Thread-safe state, commands, overlays, and cache model. Step 3 - Widget shell, sizing system, and GUI-thread frame pump. Step 4 - Tile manager, persistent cache, and asynchronous loading. Step 5 - Interaction: pan, zoom, and view commands. Step 6 - Overlay rendering and runtime update stress tests.

Current step

Step 7 - Layers, provider switching, and clearing APIs.

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.
• Implemented map_widget(...) as a Dear PyGui child-window plus drawlist shell.
• Implemented GUI-thread renderer frame pump that schedules frame callbacks, drains command queues, measures size, resizes the drawlist, and draws a placeholder background/attribution.
• Implemented sizing helpers for measured size, last non-zero size preservation, visibility transitions, effective draw size, and resize dirty flags.
• Implemented map interaction hit-rectangle calculation.
• Implemented TileID, TileStatus, Tile, visible tile calculation, and TileManager.
• Implemented asynchronous tile worker queue for disk reads, HTTP fetches, and image decoding.
• Implemented provider-namespaced persistent cache writes, access metadata updates, clearing, and LRU pruning.
• Implemented memory tile cache with visible-tile protection and deferred GUI-thread texture deletion.
• Integrated tile result processing, stale generation/provider rejection, texture creation, and tile drawing into the GUI-thread renderer.
• Added OpenStreetMap User-Agent warning/fallback and configured examples with example user agents.
• Added Step 3 examples for basic map, window sizing, child-window sizing, table sizing, and hidden-tab sizing.
• Added Step 4 cache stress example.
• Added Step 3 tests for sizing transitions, zero-size preservation, resize dirty flags, command drain ordering, and hit rectangles.
• Added Step 4 tests for visible tile calculation, stale result rejection, protected memory eviction, and tile image decoding.
• Ran a Dear PyGui context smoke check for map_widget child-window/drawlist creation.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.
• Ran a Dear PyGui context smoke check for map_widget child-window/drawlist/texture-registry creation.
• Implemented left mouse drag panning using the measured drawlist rectangle.
• Implemented mouse wheel zoom around the cursor.
• Implemented projection-backed screen_to_latlon, latlon_to_screen, and zoom-fitting fit_bounds.
• Attached Dear PyGui mouse handlers through the map handler registry.
• Added interaction debug state for active drag and last mouse position.
• Added Step 5 tests for pan, cursor zoom, view conversion, bounds fitting, and overlay/view isolation.
• Added Pyright virtualenv settings so uv run pyright resolves installed dependencies.
• Ran uv run pytest.
• Ran uv run ruff check ..
• Ran uv run ruff format --check ..
• Ran uv run pyright.
• Ran a Dear PyGui context smoke check for map_widget child-window/drawlist/texture-registry/handler-registry creation.
• Implemented Dear PyGui draw-layer bookkeeping for background, tiles, overlays, and attribution.
• Rendered markers, polylines, and trajectories from GUI-thread overlay snapshots.
• Isolated overlay redraws so they clear only the overlay draw layer and do not clear tile draw commands or textures.
• Added live background-thread marker and trajectory stress examples.
• Added Step 6 tests for overlay draw-layer isolation, overlay-only dirty flags, threaded update coalescing, and view/drag-state isolation.
• Updated README.md with Step 6 overlay rendering behavior and examples.
• Ran uv run ruff format ..
• Ran uv run pytest.
• Ran uv run pyright.
• Ran uv run ruff check ..
• Ran uv run ruff format --check ..
• Ran a Dear PyGui context smoke check for map_widget with marker, polyline, and trajectory overlays.

Next action

Implement Step 7.