75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Current status
|
|
|
|
Step 4 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.
|
|
|
|
## Current step
|
|
|
|
Step 5 - Interaction: pan, zoom, and view commands.
|
|
|
|
## 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.
|
|
|
|
## Next action
|
|
|
|
Implement Step 5.
|