Release v1.0.0

This is the first releas of dpg-map, an AI coded dearpygui map widget
built due to a lack of time to build it myself.

It features multi-widget abilities, with layers, overlays etc

docs/EXAMPLES.md

@@ -0,0 +1,146 @@
+# Examples
+
+The `examples/` directory contains runnable Dear PyGui programs:
+
+```bash
+uv run python examples/basic_map.py
+uv run python examples/custom_provider.py
+uv run python examples/cache_stress.py
+uv run python examples/markers_live_thread.py
+uv run python examples/trajectory_live_thread.py
+uv run python examples/sizing_window.py
+uv run python examples/sizing_child.py
+uv run python examples/sizing_table.py
+uv run python examples/hidden_tab.py
+```
+
+## Basic Map
+
+Creates one map and one marker.
+
+```python
+with dpg.window(label="Map", width=-1, height=-1):
+    with dpgm.map_widget(tag="map", center=(47.9029, 1.9093), zoom=15, width=-1, height=-1):
+        dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093)
+```
+
+Run:
+
+```bash
+uv run python examples/basic_map.py
+```
+
+## Live Marker Updates
+
+Use explicit `map_tag` from background threads or callbacks.
+
+```python
+dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, map_tag="map")
+
+def update_from_telemetry(lat: float, lon: float) -> None:
+    dpgm.update_marker("vehicle", lat=lat, lon=lon, map_tag="map")
+```
+
+Run a threaded stress example:
+
+```bash
+uv run python examples/markers_live_thread.py
+```
+
+## Live Trajectory
+
+Keep an application-owned point buffer and pass immutable snapshots to `update_trajectory(...)`.
+
+```python
+points: list[tuple[float, float]] = []
+dpgm.add_trajectory("track", points=[], show_points=True, point_stride=12, map_tag="map")
+
+def push_point(lat: float, lon: float) -> None:
+    points.append((lat, lon))
+    dpgm.update_trajectory("track", points=tuple(points), map_tag="map")
+```
+
+Run:
+
+```bash
+uv run python examples/trajectory_live_thread.py
+```
+
+## Multiple Maps
+
+Each map is independent. Reusing overlay tags across different maps is valid, but runtime updates
+should pass `map_tag` to avoid ambiguity.
+
+```python
+with dpgm.map_widget(tag="live-map", center=(47.9, 1.9), zoom=15, width=-1, height=300):
+    dpgm.add_marker("vehicle", lat=47.9, lon=1.9)
+
+with dpgm.map_widget(tag="recap-map", center=(47.9, 1.9), zoom=13, width=-1, height=300):
+    dpgm.add_trajectory("vehicle", points=[])
+
+dpgm.update_marker("vehicle", lat=47.901, lon=1.902, map_tag="live-map")
+dpgm.update_trajectory("vehicle", points=lap_points, map_tag="recap-map")
+```
+
+## Custom Provider Switch
+
+Register a provider, create the map with it, and switch at runtime.
+
+```python
+carto = dpgm.TileProvider(
+    name="carto-light",
+    url_template="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png",
+    subdomains=("a", "b", "c", "d"),
+    attribution="(c) OpenStreetMap contributors (c) CARTO",
+)
+
+dpgm.register_provider(carto)
+dpgm.set_provider("carto-light", map_tag="map")
+dpgm.set_provider("osm", map_tag="map")
+```
+
+Run:
+
+```bash
+uv run python examples/custom_provider.py
+```
+
+## Cache Controls
+
+Configure a local cache and expose buttons in your UI.
+
+```python
+dpgm.configure(cache_dir=".tile-cache", memory_cache_max_tiles=128)
+
+def clear_memory() -> None:
+    dpgm.clear_memory_cache(map_tag="map")
+
+def clear_disk() -> None:
+    dpgm.clear_disk_cache(map_tag="map")
+
+def refresh_stats() -> str:
+    stats = dpgm.get_cache_stats(map_tag="map")
+    return f"{stats.memory_tiles} memory tiles, {stats.disk_bytes} disk bytes"
+```
+
+Run:
+
+```bash
+uv run python examples/cache_stress.py
+```
+
+## Layout And Sizing
+
+The widget works inside windows, child windows, tables, and hidden tabs.
+
+```python
+with dpg.child_window(width=-1, height=420):
+    with dpgm.map_widget(tag="map-child", width=-1, height=-1):
+        dpgm.add_marker("inside-child", lat=47.0, lon=2.0)
+```
+
+Run:
+
+```bash
+uv run python examples/sizing_child.py
+```