trails/openspec/specs/osm-tile-overlays/spec.md at 2b48e2a8e17250cef95bd6db59c4d9fddb881c8e

Ullrich Schäfer 47eb2615ec

Fix high-severity spec drift across 10 specs

- rate-limiting: correct BRouter limit to 300/hour (was 60); add Overpass
  rate-limit requirement (120/min per IP)
- security-hardening: BROUTER_AUTH_TOKEN lives in secrets.app.env, not infra.env
- account-management: email-change verification does not re-auth; existing
  session stays valid
- planner-journal-handoff: full rewrite — documents the actual JWT callback
  architecture (edit-in-planner → POST /api/sessions → callback endpoint),
  token claims, notes round-trip via GPX <metadata><desc>, session lifecycle
- route-drag-reshape: rewrite to describe permanent segment midpoint handles
  (not proximity hover ghost marker); click-to-insert + waypoint drag model
- route-splitting: rewrite to match midpoint handle model; notes geometric
  midpoint placement (not cursor-snapped)
- road-type-coloring: redirect to route-coloring (all requirements already
  covered there)
- osm-tile-overlays: mark profile-aware auto-enable as not yet implemented
  (profileOverlayDefaults exported but not wired)
- osm-poi-overlays: zoom threshold is 10 not 12; user override persistence
  marked as not yet implemented
- shared-packages: add all 7 missing packages (map-core, fit, api, db, jobs,
  sentry-config, correct map description); document map vs map-core boundary

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-24 11:07:03 +02:00

3.4 KiB

Raw Blame History

Purpose

Tile-based map overlays (hillshading, Waymarked Trails cycling/hiking/MTB routes) with support for multiple simultaneous overlays, proper attribution, and profile-aware auto-enabling.

Requirements

Requirement: Hillshading overlay

The Planner map SHALL offer a hillshading tile overlay that visualizes terrain relief.

Scenario: Enable hillshading

WHEN a user toggles "Hillshading" in the layer switcher
THEN semi-transparent terrain shading tiles are rendered on top of the base layer

Scenario: Hillshading with any base layer

WHEN hillshading is enabled and the user switches base layers
THEN hillshading remains visible on top of the new base layer

Requirement: Waymarked Trails cycling overlay

The Planner map SHALL offer a Waymarked Trails cycling overlay showing official cycle route networks.

Scenario: Enable cycling routes overlay

WHEN a user toggles "Cycling Routes" in the layer switcher
THEN official cycling routes (EuroVelo, national networks) are rendered as colored lines on the map from Waymarked Trails tiles

Scenario: Cycling overlay at different zoom levels

WHEN cycling routes overlay is enabled
THEN international routes are visible at low zoom and local routes appear at higher zoom levels

Requirement: Waymarked Trails hiking overlay

The Planner map SHALL offer a Waymarked Trails hiking overlay showing official hiking trail networks.

Scenario: Enable hiking routes overlay

WHEN a user toggles "Hiking Routes" in the layer switcher
THEN official hiking trails (GR routes, national trails) are rendered as colored lines on the map

Requirement: Waymarked Trails MTB overlay

The Planner map SHALL offer a Waymarked Trails MTB overlay showing official mountain bike trail networks.

Scenario: Enable MTB routes overlay

WHEN a user toggles "MTB Routes" in the layer switcher
THEN official MTB trails are rendered as colored lines on the map

Requirement: Multiple simultaneous overlays

The Planner map SHALL support enabling multiple tile overlays at the same time.

Scenario: Hillshading plus cycling routes

WHEN a user enables both "Hillshading" and "Cycling Routes"
THEN both overlays are visible simultaneously, with cycling routes rendered above hillshading

Requirement: Overlay tile attribution

Each tile overlay SHALL display proper attribution when enabled.

Scenario: Attribution updates

WHEN an overlay is toggled on
THEN its attribution text is added to the map attribution control
WHEN the overlay is toggled off
THEN its attribution text is removed

Requirement: Profile-aware overlay suggestions (not yet implemented)

profileOverlayDefaults is exported from @trails-cool/map-core but is not currently wired in the Planner app. The scenarios below describe the intended behaviour once wired.

Scenario: Switch to cycling profile

WHEN the routing profile is changed to a cycling variant
THEN the Waymarked Trails cycling overlay is automatically enabled

Scenario: Switch to hiking profile

WHEN the routing profile is changed to a hiking variant
THEN the Waymarked Trails hiking overlay is automatically enabled

Scenario: User can disable auto-enabled overlays

WHEN an overlay was auto-enabled by a profile change
THEN the user can manually disable it and it stays disabled until the next profile change

3.4 KiB Raw Blame History