Skip to content

feat: offline tile prefetch scheduler with LRU eviction and predictive caching#93

Open
real-venus wants to merge 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/tile-prefetch-scheduler
Open

feat: offline tile prefetch scheduler with LRU eviction and predictive caching#93
real-venus wants to merge 1 commit into
Utility-Protocol:mainfrom
real-venus:feat/tile-prefetch-scheduler

Conversation

@real-venus

Copy link
Copy Markdown
Contributor

Offline Geospatial Tile Prefetch Scheduler with LRU Eviction & Predictive Caching (#48)

Closes #48

What's included

File Responsibility
src/types/tile.ts TileId/TileMeta/GeoSample/Viewport/BBox/PrefetchRequest and bounds (2,500 cap, 2,250 evict threshold, 3×3 × ±2-zoom = 45-tile burst, >2 m/s prefetch, 30° stale-heading cancel, 7-day/48-h TTL by zoom, eviction check every 10 writes).
src/utils/tileMath.ts Pure slippy-map math (lngLatToTile/tileBounds/tilesInBBox), trajectory prediction (predictCenter/burstTiles/predictBBox/zoomLevelsFor), heading/velocity gating (headingDelta/isStaleHeading/shouldPrefetch), and zoom-dependent TTL/isStale.
src/utils/lruEviction.ts Doubly-linked LRU list; eviction prefers stale tiles first, then the lowest access_count / age ratio, with LRU as the final tie-break. Tracks size + byte usage.
src/services/tileCache.ts IndexedDB tile-blob + metadata stores, in-memory LRU mirror for O(1) hit accounting, and an eviction pass triggered every 10 writes once the threshold is reached.
src/workers/tilePrefetch.worker.ts Expands bbox × zoomLevels into tiles, fetches off the main thread, writes blobs to IndexedDB, skips already-cached tiles, and cancels superseded bursts (a sharp heading change supersedes the in-flight request).
src/hooks/useGeoLocation.ts 1 Hz navigator.geolocation watch → GeoSample (heading, speed).
src/hooks/useMapViewport.ts Mapbox camera (center/zoom/bearing/pitch) as reactive state via a structural interface (no mapbox-gl dependency).
src/store/slices/tileCacheSlice.ts Hit/miss/eviction/byte/pending stats + selectHitRatio.
src/components/dashboard/TileCacheOverlay.tsx Feature-flagged debug overlay (hit ratio, fill %, bytes, evictions, pending).
tests/unit/* Tile math (coords/bounds/prediction/TTL), LRU eviction ordering + staleness precedence, and the stats store.

…e caching (Utility-Protocol#48)

Anticipates the operator's viewport trajectory (GPS heading/velocity/zoom) and
pre-warms the surrounding tile pyramid into IndexedDB with bounded LRU eviction,
so pinch-zoom and connectivity loss no longer fall back to grey squares.

- types/tile.ts: TileId/TileMeta/GeoSample/Viewport/BBox/PrefetchRequest and
  bounds (2500 cap / 2250 evict threshold, 3x3 x +/-2 zoom = 45-tile burst,
  >2 m/s prefetch, 30deg stale-heading cancel, 7d/48h TTL by zoom)
- utils/tileMath.ts: slippy-map tile math (lng/lat<->tile, bounds, tilesInBBox),
  trajectory prediction (predictCenter/burstTiles/predictBBox), heading/velocity
  gating, and zoom-dependent TTL/staleness
- utils/lruEviction.ts: doubly-linked LRU list; eviction prefers stale tiles
  then the lowest access_count/age ratio (LRU tie-break)
- services/tileCache.ts: IndexedDB tile-blob + metadata stores, hit accounting,
  and an eviction check every 10 writes past the threshold
- workers/tilePrefetch.worker.ts: expands bbox x zoom range to tiles, fetches
  off-thread, writes blobs to IndexedDB, skips fresh tiles, cancels superseded
  bursts
- hooks/useGeoLocation.ts (1 Hz GPS) + useMapViewport.ts (Mapbox camera)
- store/slices/tileCacheSlice.ts: hit/miss/eviction/byte/pending stats + hit
  ratio; components/dashboard/TileCacheOverlay.tsx debug overlay (feature-flagged)
- tests for tile math, LRU eviction ordering/staleness, and the stats store
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Offline Geospatial Tile Prefetch Scheduler with LRU Eviction and Predictive Heatmap Caching

1 participant