diff --git a/backend/graphhopper_encoded_values.md b/backend/graphhopper_encoded_values.md
new file mode 100644
index 0000000..0d72b67
--- /dev/null
+++ b/backend/graphhopper_encoded_values.md
@@ -0,0 +1,336 @@
+# GraphHopper encoded values for bicycle routing
+
+Reference for every built-in encoded value in `graphhopper-web-12.0` that is plausibly relevant for a city-bike profile in Berlin. Each section explains what the value means, how GraphHopper computes it from OSM tags at import time, and a verdict on whether to add it to `graph.encoded_values` in [graphhopper_config.yml](graphhopper_config.yml).
+
+Adding any new value below requires a graph reimport (`rm -rf data/osm/berlin/graphhopper && just preview`).
+
+The current set in this repo is:
+
+```
+country, road_class, roundabout, max_speed, road_environment,
+bike_access, foot_access, bike_average_speed, bike_priority,
+bike_road_access, bike_network,
+mtb_rating, hike_rating, average_slope, ferry_speed,
+road_access, get_off_bike, surface, smoothness, cycleway, crossing
+```
+
+Graph cache stays well below the prior `car`/`foot`/`bike` baseline
+despite the expanded bike-shaping set — dropping the `car_*` EVs and
+disabling CH preparation more than pay for the additions.
+
+Verdict legend:
+- ✅ already in — keep
+- ➕ add — concrete win for a Berlin bike profile
+- 🤔 maybe — situationally useful, low priority
+- ❌ skip — not relevant for bikes
+
+---
+
+## Bike-specific values
+
+### `bike_access` ✅ already in
+Boolean per direction. `true` if a bicycle is legally allowed to traverse the edge in the forward direction. `backward_bike_access` is the implicit opposite-direction sibling exposed in custom-model expressions.
+
+**Computed from:** `bicycle=*`, `access=*`, `highway=*` defaults (e.g. `highway=motorway` ⇒ no bike access; `highway=cycleway` ⇒ designated), plus country-specific defaults (Country.GERMANY enables bicycle on `highway=footway` only when `bicycle=yes`).
+
+**Why keep:** Hard prerequisite — the upstream `bike.json` zeroes priority for edges with no bike access in either direction.
+
+---
+
+### `bike_average_speed` ✅ already in
+Decimal (km/h). Realistic cycling speed for the edge type and surface, before slope and custom-model speed rules apply.
+
+**Computed from:** `highway=*` table (cycleway ≈ 18, residential ≈ 18, secondary ≈ 16, track ≈ 12, path ≈ 10), then reduced by `surface` and `smoothness` heuristics.
+
+**Why keep:** Drives ETA. `bike_elevation.json` modulates this further by `average_slope`.
+
+---
+
+### `bike_priority` ✅ already in
+Decimal in `[0, 1]`. GraphHopper's opinionated "how nice is this for a bike" score. Used as `multiply_by: bike_priority` on the first line of `graphhopper_profile.json`.
+
+**Computed from:** Internal `BikePriorityParser` mixing `road_class`, `cycleway:*`, `bicycle=designated`, `bicycle_road=yes`, `surface`, `smoothness`, `tracktype`, `motor_vehicle=*`. Result is bucketed into ~7 levels (`AVOID_AT_ALL_COSTS` … `BEST`).
+
+**Why keep:** Free baseline shaping. Caveat: opaque — you can layer penalties on top, but you can't *raise* an edge above the bucket GraphHopper assigned.
+
+---
+
+### `bike_road_access` ✅ already in
+Enum: `MISSING, YES, NO, PRIVATE, DESTINATION, DELIVERY, CUSTOMERS, MILITARY, DISMOUNT, USE_SIDEPATH, DESIGNATED`.
+
+**Computed from:** `bicycle=*` and `access=*` interpreted with bike-specific semantics. `DISMOUNT` ↔ `bicycle=dismount`; `USE_SIDEPATH` ↔ `bicycle=use_sidepath` (mandatory adjacent cycle path under StVO 2.3.4).
+
+**Why keep:** Lets us zero out roads with `bicycle=no`, penalise `PRIVATE` (already in our profile), and gives a hook to penalise `DISMOUNT`/`USE_SIDEPATH` later.
+
+---
+
+### `bike_network` ✅ already in
+Enum: `MISSING, OTHER, INTERNATIONAL, NATIONAL, REGIONAL, LOCAL` (shared `RouteNetwork` enum with `foot_network`, etc.).
+
+**Computed from:** OSM relations of `route=bicycle` with `network=icn|ncn|rcn|lcn`. Each edge inherits the highest-tier network it belongs to.
+
+**Why keep:** Berliner Mauerweg, Radfernweg Berlin–Kopenhagen, Leipzig, the regional RSV/Radschnellverbindungen all show up via this. Profile already gives ×1.4 / ×1.2.
+
+---
+
+### `bike_temporal_access` 🤔 maybe
+Captures conditional bike access — `bicycle:conditional=yes @ (Mo-Fr 08:00-18:00)`, etc.
+
+**Computed from:** `*:conditional=*` tags evaluated against route-time.
+
+**Why maybe:** Useful for Berlin's Sommer-fußgängerzonen and a handful of timed accesses (Tiergarten Lichtensteinallee, parts of the Mauerpark). Tiny coverage; not worth it until we add time-aware routing.
+
+---
+
+### `mtb_rating` ✅ already in
+Integer `0..6`. `0` = no rating; higher = harder mountain-bike trail.
+
+**Computed from:** `mtb:scale=0..6`.
+
+**Why keep:** Upstream `bike.json` zeroes anything `> 2`. Relevant in Grunewald/Spandauer Forst singletrack. Cheap.
+
+---
+
+### `mtb_network` ❌ skip
+Mirror of `bike_network` for `route=mtb` relations. Negligible coverage in the Berlin pbf and we already prefer `bike_network`. Skip.
+
+---
+
+### `get_off_bike` ✅ already in
+Boolean. `true` if a cyclist would typically have to dismount.
+
+**Computed from:** `bicycle=dismount`, `highway=steps`, `highway=footway` without `bicycle=yes`/`designated`, etc.
+
+**Why add:** Cleaner than checking individual conditions in the custom model — one `multiply_by: 0.1` rule covers all dismount cases. Slightly redundant with `bike_road_access == DISMOUNT`, but covers the steps/footway cases that aren't tagged `bicycle=dismount`.
+
+---
+
+## Road structure
+
+### `road_class` ✅ already in
+Enum: `OTHER, MOTORWAY, TRUNK, PRIMARY, SECONDARY, TERTIARY, RESIDENTIAL, UNCLASSIFIED, SERVICE, ROAD, TRACK, FOOTWAY, PEDESTRIAN, LIVING_STREET, BRIDLEWAY, STEPS, CYCLEWAY, PATH, CONSTRUCTION, PLATFORM, CORRIDOR, BUSWAY`.
+
+**Computed from:** `highway=*`.
+
+**Why keep:** Foundation for any future per-class shaping (e.g. boost `LIVING_STREET`, `CYCLEWAY`, penalise `PRIMARY`/`SECONDARY` not on a network).
+
+---
+
+### `road_class_link` 🤔 maybe
+Boolean. `true` for `*_link` highway types (motorway_link, primary_link, etc.).
+
+**Why maybe:** Useless on bikes — we don't ride motorway links. Skip.
+
+---
+
+### `road_environment` ✅ already in
+Enum: `OTHER, ROAD, FERRY, TUNNEL, BRIDGE, FORD`.
+
+**Computed from:** `tunnel=*`, `bridge=*`, `route=ferry`, `ford=*`.
+
+**Why keep:** Profile penalises ferries; useful for snap_preventions and for fording avoidance. Cheap.
+
+---
+
+### `road_access` ✅ already in
+Enum: `YES, DESTINATION, DELIVERY, CUSTOMERS, AGRICULTURAL, FORESTRY, PRIVATE, MILITARY, NO`.
+
+**Computed from:** `access=*` (general, vehicle-agnostic).
+
+**Why add:** Complements `bike_road_access` — picks up restrictions that affect all vehicles (gated forestry tracks in the Grunewald, military areas). Sometimes the cheaper signal when bike-specific tagging is missing. Small graph cost.
+
+---
+
+### `surface` ✅ already in
+Enum: `MISSING, OTHER, PAVED, ASPHALT, CONCRETE, PAVING_STONES, COBBLESTONE, UNPAVED, COMPACTED, FINE_GRAVEL, GRAVEL, GROUND, DIRT, GRASS, SAND, WOOD`.
+
+**Computed from:** `surface=*`. Berlin-specific note: `cobblestone` (rounded historic Kopfsteinpflaster) is much rougher than `paving_stones` (modern brick) — both common, both worth penalising at different strengths.
+
+**Why add:** Highest-impact addition for a Berlin profile. Side streets in Mitte/Prenzlauer Berg are full of `sett` and `cobblestone` (note: GH folds `sett` into… see caveat below). Cyclists strongly prefer asphalt detours.
+
+**Caveat:** GraphHopper does *not* expose `sett` as a separate enum value — it's mapped to `OTHER`. To penalise `sett` specifically, we'd need to also encode `paving_stones` separately and accept the loss of granularity, or write a custom parser. For a first pass, treating `COBBLESTONE` and `PAVING_STONES` as "rough" is enough.
+
+---
+
+### `smoothness` ✅ already in
+Enum: `MISSING, OTHER, EXCELLENT, GOOD, INTERMEDIATE, BAD, VERY_BAD, HORRIBLE, VERY_HORRIBLE, IMPASSABLE`.
+
+**Computed from:** `smoothness=*`.
+
+**Why add:** Sparse but high-signal in Berlin park paths. Where present, a cyclist would much rather take an `INTERMEDIATE`-rated road than the parallel `BAD` one. Pair with `surface`.
+
+---
+
+### `track_type` 🤔 maybe
+Enum: `MISSING, GRADE1, GRADE2, GRADE3, GRADE4, GRADE5`. Firmness of `highway=track`.
+
+**Computed from:** `tracktype=grade1..grade5`.
+
+**Why maybe:** Berlin city core has very few `highway=track`s. Useful around Grunewald/Müggelsee for casual riding, not worth the encoded-value slot until we add a "gravel" profile.
+
+---
+
+### `cycleway` ✅ already in
+Enum: `MISSING, OTHER, NO, LANE, TRACK, SHARED_LANE, SHOULDER, SEPARATE`.
+
+**Computed from:** `cycleway=*` and side-specific `cycleway:left|right=*` collapsed to a single per-edge value.
+
+**Why add:** Lets the profile prefer `LANE`/`TRACK` over `MISSING`. Particularly relevant for the many Berlin arterials where the cycleway is *part of* the road geometry (so `road_class != CYCLEWAY` even though there is a marked lane).
+
+**Caveat:** GH collapses left+right into one enum — biased toward whichever side it picks first. Acceptable for shaping; not for navigation instructions.
+
+---
+
+### `footway` ❌ skip
+Enum: `MISSING, SIDEWALK, CROSSING, ACCESS_AISLE, TRAFFIC_ISLAND, ALLEY, LINK`. Sub-category of `highway=footway`.
+
+**Why skip:** We're filtering footways via `bike_access`/`get_off_bike`. Per-sub-type shaping doesn't justify a graph-byte slot.
+
+---
+
+### `sidewalk` ❌ skip
+Enum: `MISSING, NO, YES, SEPARATE`. Whether a sidewalk runs alongside a road. Used in the foot profile.
+
+**Why skip:** Pedestrian concern, not bike.
+
+---
+
+### `crossing` ✅ already in
+Enum: `MISSING, NO, UNCONTROLLED, MARKED, UNMARKED, TRAFFIC_SIGNALS, RAILWAY, RAILWAY_BARRIER`.
+
+**Computed from:** `crossing=*` on `highway=crossing` nodes, propagated to adjacent edges.
+
+**Why keep:** Included to enable a future "prefer controlled crossings on big roads" rule. Visible in the debug overlay today.
+
+---
+
+### `roundabout` ✅ already in
+Boolean. `true` if the edge is part of a `junction=roundabout` or `junction=circular`.
+
+**Why keep:** `bike.json` uses it to forbid wrong-way entry on roundabouts. Tiny cost.
+
+---
+
+### `lanes` ❌ skip
+Integer count of lanes from `lanes=*`. Useful for cars, mostly redundant for bikes (we already have `road_class` and `max_speed`). Skip.
+
+---
+
+### `lit` 🤔 maybe
+Boolean. `true` if the way is lit (`lit=yes`).
+
+**Computed from:** `lit=*`.
+
+**Why maybe:** Worth adding the day we expose a "prefer lit at night" toggle. Coverage in Berlin parks is patchy — Tiergarten paths are well tagged, side streets often `lit=missing`. Defer.
+
+---
+
+## Speed and slope
+
+### `max_speed` ✅ already in
+Decimal (km/h). The legal speed limit on the edge in the forward direction (`max_speed_reverse` exists separately). For German edges with no `maxspeed` tag, GraphHopper falls back to legal defaults via the `country` value.
+
+**Computed from:** `maxspeed=*`, then fallbacks per `country` × `road_class` × `urban_density` (`legal_default_speeds.json`).
+
+**Why keep:** Strong proxy for "scary to ride" — `max_speed >= 50 km/h` without a separate cycleway is the classic Berlin Hauptverkehrsstraße. Profile rule waiting to be written.
+
+---
+
+### `country` ✅ already in
+Enum (3-letter ISO codes, e.g. `DEU`, `POL`).
+
+**Why keep:** Required at import time for legal default speed lookup, and for any country-specific custom rule (we won't need many in a Berlin-only deployment, but it's cheap).
+
+---
+
+### `urban_density` ❌ skip
+Enum: `RURAL, RESIDENTIAL, CITY`. Computed by GraphHopper post-import based on the density of the surrounding road network.
+
+**Computed from:** local way density via a sliding window — no OSM tag involved.
+
+**Why skip:** Berlin coverage is too coarse to be useful — the sliding-window heuristic flags virtually the entire ring-bahn area as `CITY`, leaving `RESIDENTIAL` only for a thin outer fringe. Not worth the encoded-value slot or the extra import time. GraphHopper still computes urban density internally for the `legal_default_speeds.json` `max_speed` fallback.
+
+---
+
+### `average_slope` ✅ already in
+Decimal (%). Average gradient of the edge from elevation samples.
+
+**Computed from:** SRTM elevation data sampled along the way geometry.
+
+**Why keep:** Used by `bike_elevation.json` to drop speed on climbs and bump it on descents. Berlin is ~flat, so it rarely fires, but cheap to keep.
+
+---
+
+### `max_slope` 🤔 maybe
+Decimal (%). Steepest section of the edge.
+
+**Why maybe:** More precise than `average_slope` for bridges/ramps (Warschauer/Oberbaum, etc.). Marginal in Berlin. Defer.
+
+---
+
+### `curvature` ❌ skip
+Decimal `[0, 1]`. Edge-length-divided-by-straight-line ratio.
+
+**Why skip:** Used for motorcycle "fun routing". Not relevant.
+
+---
+
+### `ferry_speed` ✅ already in
+Decimal (km/h). Speed at which to traverse a ferry edge.
+
+**Why keep:** `bike.json` references it. Cheap. (Almost no ferries inside the Berlin extract — Müggelsee, BVG-FähreF10–F23 — but still relevant.)
+
+---
+
+## Vehicle restrictions (mostly N/A)
+
+### `max_height`, `max_width`, `max_length`, `max_weight`, `max_axle_load` ❌ skip
+All physical restrictions for trucks/buses. Bikes don't care.
+
+### `hgv` ❌ skip
+Heavy goods vehicle access. N/A.
+
+### `toll` ❌ skip
+Enum: `MISSING, NO, ALL, HGV`. Tolls almost never apply to bikes.
+
+### `hazmat`, `hazmat_tunnel`, `hazmat_water` ❌ skip
+Hazardous-material restrictions. N/A.
+
+### `bus_access`, `hov_access` ❌ skip
+Bus/HOV-lane access. N/A.
+
+### `car_temporal_access`, `foot_temporal_access` ❌ skip
+We don't run those profiles.
+
+### `foot_*`, `horse_*`, `mtb_network` ❌ skip
+Other modes' values. We deleted the foot profile.
+
+### `orientation` ❌ skip
+Edge bearing. Only useful with `turn_costs` on profiles like `bike_tc`. Defer until we want turn-cost routing.
+
+---
+
+## Identifiers / debug
+
+### `osm_way_id` 🤔 maybe
+Long. The original OSM way ID. Useful for "show me the OSM tag for this edge" debugging via `?details=osm_way_id` in the response.
+
+**Why maybe:** Pure dev convenience. Adds 8 bytes per edge.
+
+---
+
+## Custom-model rule ideas (next steps)
+
+With the values above in the graph, the following rules can be added to
+[graphhopper_profile.json](graphhopper_profile.json) without another reimport:
+
+- penalise `cycleway == MISSING && max_speed >= 50` on `urban_density == CITY` arterials,
+- soft-block `surface ∈ {COBBLESTONE, GRAVEL, SAND, GROUND}`,
+- prefer `cycleway ∈ {LANE, TRACK, SEPARATE}` regardless of `road_class`,
+- hard-down-weight `get_off_bike == true` instead of relying on `bike_priority`'s opaque verdict,
+- penalise `crossing == NO || crossing == UNMARKED` on big roads.
+
+Validate visually first via the debug overlay (Preferences → "Debug: encoded
+value overlay" dropdown) before promoting rules into the profile.
+
+Sources: enum members extracted directly from `graphhopper-web-12.0-SNAPSHOT.jar` (`com/graphhopper/routing/ev/*.class`); semantics cross-referenced with [GraphHopper road attributes docs](https://docs.graphhopper.com/openapi/custom-model/road-attributes), the upstream `com/graphhopper/custom_models/bike.json`, and OSM wiki ([Key:cycleway](https://wiki.openstreetmap.org/wiki/Key:cycleway), [Key:smoothness](https://wiki.openstreetmap.org/wiki/Key:smoothness), [Key:surface](https://wiki.openstreetmap.org/wiki/Key:surface), [DE:Key:tracktype](https://wiki.openstreetmap.org/wiki/DE:Key:tracktype)).
diff --git a/backend/src/debug.rs b/backend/src/debug.rs
new file mode 100644
index 0000000..dc710e3
--- /dev/null
+++ b/backend/src/debug.rs
@@ -0,0 +1,58 @@
+use axum::{
+    body::Body,
+    extract::{Path, RawQuery, State},
+    http::{header, HeaderMap, StatusCode},
+    response::IntoResponse,
+};
+use std::sync::Arc;
+
+use crate::{errors::AppError, AppState};
+
+/// GET /api/debug/mvt/{z}/{x}/{y}
+///
+/// Proxies GraphHopper's `/mvt/{z}/{x}/{y}.mvt` so the browser can fetch
+/// per-edge encoded values as MapboxVectorTiles for the debug overlay.
+/// The raw query string is forwarded verbatim so repeated `details=` params
+/// (which GraphHopper expects as a `List<String>`) survive the proxy hop.
+/// Authentication is intentionally NOT required — this endpoint is dev-only
+/// and exposes the same data anyone with access to the routing API can infer.
+pub async fn mvt(
+    State(state): State<Arc<AppState>>,
+    Path((z, x, y)): Path<(u32, u32, u32)>,
+    RawQuery(query): RawQuery,
+) -> Result<impl IntoResponse, AppError> {
+    let mut url = format!("{}/mvt/{}/{}/{}.mvt", state.config.graphhopper_url, z, x, y);
+    if let Some(q) = query.as_deref().filter(|s| !s.is_empty()) {
+        url.push('?');
+        url.push_str(q);
+    }
+
+    let upstream = state
+        .http_client
+        .get(&url)
+        .send()
+        .await
+        .map_err(|e| AppError::Internal(format!("failed to reach GraphHopper MVT: {e}")))?;
+
+    let status = upstream.status();
+    let bytes = upstream
+        .bytes()
+        .await
+        .map_err(|e| AppError::Internal(format!("failed to read GraphHopper MVT body: {e}")))?;
+
+    if !status.is_success() {
+        let snippet = String::from_utf8_lossy(&bytes);
+        return Err(AppError::Internal(format!(
+            "GraphHopper MVT returned {status}: {snippet}"
+        )));
+    }
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        header::CONTENT_TYPE,
+        "application/x-protobuf".parse().unwrap(),
+    );
+    headers.insert(header::CACHE_CONTROL, "no-store".parse().unwrap());
+
+    Ok((StatusCode::OK, headers, Body::from(bytes)))
+}
diff --git a/backend/src/lib.rs b/backend/src/lib.rs
index 2197667..d687c80 100644
--- a/backend/src/lib.rs
+++ b/backend/src/lib.rs
@@ -1,6 +1,7 @@
 pub mod auth;
 pub mod bbox;
 pub mod config;
+pub mod debug;
 pub mod errors;
 pub mod geocode;
 pub mod locations;
@@ -54,6 +55,7 @@ pub fn build_router(state: Arc<AppState>) -> Router {
         .route("/api/route", post(routing::get_route))
         .route("/api/navigate", post(routing::get_navigation_route))
         .route("/api/geocode", get(geocode::geocode))
+        .route("/api/debug/mvt/{z}/{x}/{y}", get(debug::mvt))
         .route(
             "/.well-known/apple-app-site-association",
             get(apple_app_site_association),
diff --git a/compose.bouman.yml b/compose.bouman.yml
new file mode 100644
index 0000000..f62cd50
--- /dev/null
+++ b/compose.bouman.yml
@@ -0,0 +1,16 @@
+services:
+  db:
+    container_name: beebeebike-bouman-db
+    ports: !override ["5433:5432"]
+  graphhopper:
+    container_name: beebeebike-bouman-graphhopper
+    ports: !override ["18989:8989"]
+  tiles:
+    container_name: beebeebike-bouman-tiles
+    ports: !override ["18080:8080"]
+  backend:
+    container_name: beebeebike-bouman-backend
+    ports: !override ["3001:3000"]
+volumes:
+  pgdata:
+    name: beebeebike-bouman-pgdata
diff --git a/web/src/App.svelte b/web/src/App.svelte
index d2ca382..4805fee 100644
--- a/web/src/App.svelte
+++ b/web/src/App.svelte
@@ -11,6 +11,7 @@
   import { loadHomeLocation, locations } from './lib/locations.svelte.js';
   import { initOverlay } from './lib/overlay.js';
   import { initBrush, destroyBrush } from './lib/brush.svelte.js';
+  import { initDebugOverlay } from './lib/debugOverlay.svelte.js';
   import { applyStartAtHome, centerOnHome, clearRoute, initRouting, route, syncHomeMarker, syncRouteMarkers } from './lib/routing.svelte.js';
 
   let map = $state(null);
@@ -44,6 +45,7 @@
         initOverlay(map);
         initBrush(map);
         initRouting(map);
+        initDebugOverlay(map);
       });
       return () => destroyBrush();
     }
diff --git a/web/src/components/PreferencesPanel.svelte b/web/src/components/PreferencesPanel.svelte
index e23f419..ba27a16 100644
--- a/web/src/components/PreferencesPanel.svelte
+++ b/web/src/components/PreferencesPanel.svelte
@@ -7,9 +7,20 @@
     setRatingWeight,
   } from '../lib/preferences.svelte.js';
   import { computeRoute, route } from '../lib/routing.svelte.js';
+  import {
+    ENCODED_VALUES,
+    debugState,
+    setEncodedValue,
+    toggleMember,
+    setAllMembersVisible,
+    setAllMembersHidden,
+    setHideFootways,
+  } from '../lib/debugOverlay.svelte.js';
 
   let recomputeTimer;
 
+  const sortedEncodedValues = [...ENCODED_VALUES].sort((a, b) => a.key.localeCompare(b.key));
+
   function queueRouteUpdate() {
     if (!route.origin || !route.destination) return;
 
@@ -79,6 +90,79 @@
     <span>Direct</span>
   </div>
 
+  <div class="debug-section">
+    <div class="preference-row">
+      <div class="preference-copy">
+        <label for="debug-ev">Debug: encoded value overlay</label>
+        <p>Internal tool. Visualises a GraphHopper edge attribute on the map.</p>
+      </div>
+    </div>
+    <select
+      id="debug-ev"
+      value={debugState.selectedKey ?? ''}
+      onchange={(e) => setEncodedValue(e.currentTarget.value || null)}
+    >
+      <option value="">Off</option>
+      {#each sortedEncodedValues as ev (ev.key)}
+        <option value={ev.key}>{ev.key}</option>
+      {/each}
+    </select>
+
+    {#if debugState.selected}
+      {@const ev = debugState.selected}
+      <div class="legend">
+        {#if ev.kind === 'enum'}
+          <div class="legend-actions">
+            <button type="button" onclick={setAllMembersVisible}>All</button>
+            <button type="button" onclick={setAllMembersHidden}>None</button>
+          </div>
+          {#each ev.members as m (m.value)}
+            {@const hidden = debugState.hidden.includes(m.value)}
+            <label class="legend-row legend-row-toggle" class:dimmed={hidden}>
+              <input
+                type="checkbox"
+                checked={!hidden}
+                onchange={() => toggleMember(m.value)}
+              />
+              <span class="swatch" style="background: {m.color}"></span>
+              <span class="legend-label">{m.label}</span>
+            </label>
+          {/each}
+        {:else if ev.kind === 'boolean'}
+          <div class="legend-row">
+            <span class="swatch" style="background: {ev.trueColor}"></span>
+            <span class="legend-label">true</span>
+          </div>
+          <div class="legend-row">
+            <span class="swatch" style="background: {ev.falseColor}"></span>
+            <span class="legend-label">false</span>
+          </div>
+        {:else if ev.kind === 'number'}
+          <div
+            class="legend-gradient"
+            style="background: linear-gradient(to right, {ev.stops.map(([, c]) => c).join(', ')})"
+          ></div>
+          <div class="legend-axis">
+            {#each ev.stops as [v] (v)}
+              <span class="legend-tick">{v}</span>
+            {/each}
+          </div>
+        {/if}
+        {#if ev.note}
+          <p class="legend-note">{@html ev.note}</p>
+        {/if}
+        <label class="legend-row legend-row-toggle global-toggle">
+          <input
+            type="checkbox"
+            checked={debugState.hideFootways}
+            onchange={(e) => setHideFootways(e.currentTarget.checked)}
+          />
+          <span class="legend-label">Hide <code>road_class=footway</code></span>
+        </label>
+      </div>
+    {/if}
+  </div>
+
   <div class="credits">
     <p>Legal</p>
     <div class="credit-links">
@@ -150,6 +234,105 @@
     color: var(--ink-faint);
     font: 500 12px/1.3 var(--font-sans);
   }
+  .debug-section {
+    margin-top: 18px;
+    padding-top: 12px;
+    border-top: 1px dashed var(--divider);
+  }
+  .debug-section select {
+    width: 100%;
+    padding: 6px 8px;
+    border: 1px solid var(--divider);
+    border-radius: var(--radius-ctrl, 6px);
+    font: 500 13px/1.3 var(--font-mono);
+    background: var(--panel);
+    color: var(--ink);
+  }
+  .legend {
+    margin-top: 10px;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    font: 500 12px/1.3 var(--font-mono);
+    color: var(--ink-muted);
+  }
+  .legend-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .legend-row-toggle {
+    cursor: pointer;
+    user-select: none;
+  }
+  .legend-row-toggle input[type='checkbox'] {
+    margin: 0;
+    accent-color: var(--brand);
+  }
+  .legend-row-toggle.dimmed .swatch,
+  .legend-row-toggle.dimmed .legend-label {
+    opacity: 0.4;
+  }
+  .legend-actions {
+    display: flex;
+    gap: 6px;
+    margin-bottom: 4px;
+  }
+  .legend-actions button {
+    padding: 2px 8px;
+    border: 1px solid var(--divider);
+    border-radius: var(--radius-ctrl, 6px);
+    background: var(--panel);
+    color: var(--ink);
+    font: 500 11px/1.3 var(--font-sans);
+    cursor: pointer;
+  }
+  .legend-actions button:hover {
+    background: var(--divider);
+  }
+  .global-toggle {
+    margin-top: 10px;
+    padding-top: 8px;
+    border-top: 1px dashed var(--divider);
+  }
+  .global-toggle code {
+    font-family: var(--font-mono);
+    font-size: 11px;
+  }
+  .swatch {
+    display: inline-block;
+    width: 14px;
+    height: 14px;
+    border: 1px solid var(--divider);
+    border-radius: 2px;
+    flex-shrink: 0;
+  }
+  .legend-label {
+    font-family: var(--font-mono);
+  }
+  .legend-gradient {
+    height: 12px;
+    border-radius: 2px;
+    border: 1px solid var(--divider);
+  }
+  .legend-axis {
+    display: flex;
+    justify-content: space-between;
+    color: var(--ink-faint);
+  }
+  .legend-note {
+    margin: 8px 0 0;
+    color: var(--ink-muted);
+    font: 400 12px/1.55 var(--font-sans);
+  }
+  .legend-note :global(strong) { font-weight: 600; }
+  .legend-note :global(code) {
+    font-family: var(--font-mono);
+    font-size: 11px;
+    background: var(--divider);
+    padding: 1px 3px;
+    border-radius: 3px;
+  }
   .credits {
     margin-top: 18px;
     padding-top: 12px;
diff --git a/web/src/lib/debugOverlay.svelte.js b/web/src/lib/debugOverlay.svelte.js
new file mode 100644
index 0000000..e634040
--- /dev/null
+++ b/web/src/lib/debugOverlay.svelte.js
@@ -0,0 +1,394 @@
+// Dev-only encoded-value visualizer. Adds an MVT source over the map showing
+// per-edge values for the selected GraphHopper encoded value, served by the
+// backend's /api/debug/mvt proxy.
+//
+// GraphHopper's MVTResource encodes per-edge feature properties as STRINGS:
+//   - enum values are lowercase ("footway", "asphalt")
+//   - directional values are pipe-separated, e.g. "true | true",
+//     "50.0 | 50.0", "missing | missing"
+// `paintExpression()` accepts both bare and `"X | X"` forms for the same key.
+
+const FALLBACK = '#888';
+
+const PALETTE = [
+  '#e6194b', '#3cb44b', '#ffe119', '#4363d8', '#f58231', '#911eb4',
+  '#46f0f0', '#f032e6', '#bcf60c', '#fabebe', '#008080', '#e6beff',
+];
+
+function enumMembers(values) {
+  return values.map((v, i) => ({
+    value: v,
+    color: PALETTE[i % PALETTE.length],
+    label: v,
+  }));
+}
+
+export const ENCODED_VALUES = [
+  // Bike-specific
+  {
+    key: 'bike_priority',
+    kind: 'number',
+    domain: [0, 1.5],
+    stops: [
+      [0.0, '#d73027'],
+      [0.3, '#fdae61'],
+      [0.6, '#fee08b'],
+      [0.9, '#a6d96a'],
+      [1.5, '#1a9850'],
+    ],
+    note: 'Decimal in [0, 1]. GraphHopper\'s opinionated "how nice is this for a bike" score. Used as <code>multiply_by: bike_priority</code> on the first line of <code>graphhopper_profile.json</code>.<br><br><strong>Computed from:</strong> Internal <code>BikePriorityParser</code> mixing <code>road_class</code>, <code>cycleway:*</code>, <code>bicycle=designated</code>, <code>bicycle_road=yes</code>, <code>surface</code>, <code>smoothness</code>, <code>tracktype</code>, <code>motor_vehicle=*</code>. Result is bucketed into ~7 levels (<code>AVOID_AT_ALL_COSTS</code> … <code>BEST</code>).<br><br><strong>Why keep:</strong> Free baseline shaping. Caveat: opaque — you can layer penalties on top, but you can\'t <em>raise</em> an edge above the bucket GraphHopper assigned.',
+  },
+  {
+    key: 'bike_average_speed',
+    kind: 'number',
+    domain: [0, 30],
+    stops: [
+      [0,  '#d73027'],
+      [10, '#fdae61'],
+      [20, '#a6d96a'],
+      [30, '#1a9850'],
+    ],
+    note: 'Decimal (km/h). Realistic cycling speed for the edge type and surface, before slope and custom-model speed rules apply.<br><br><strong>Computed from:</strong> <code>highway=*</code> table (cycleway ≈ 18, residential ≈ 18, secondary ≈ 16, track ≈ 12, path ≈ 10), then reduced by <code>surface</code> and <code>smoothness</code> heuristics.<br><br><strong>Why keep:</strong> Drives ETA. <code>bike_elevation.json</code> modulates this further by <code>average_slope</code>.',
+  },
+  {
+    key: 'bike_road_access',
+    kind: 'enum',
+    members: enumMembers(['missing', 'yes', 'no', 'private', 'destination', 'delivery', 'customers', 'military', 'dismount', 'use_sidepath', 'designated']),
+    note: 'Enum: <code>MISSING, YES, NO, PRIVATE, DESTINATION, DELIVERY, CUSTOMERS, MILITARY, DISMOUNT, USE_SIDEPATH, DESIGNATED</code>.<br><br><strong>Computed from:</strong> <code>bicycle=*</code> and <code>access=*</code> interpreted with bike-specific semantics. <code>DISMOUNT</code> ↔ <code>bicycle=dismount</code>; <code>USE_SIDEPATH</code> ↔ <code>bicycle=use_sidepath</code> (mandatory adjacent cycle path under StVO 2.3.4).<br><br><strong>Why keep:</strong> Lets us zero out roads with <code>bicycle=no</code>, penalise <code>PRIVATE</code> (already in our profile), and gives a hook to penalise <code>DISMOUNT</code>/<code>USE_SIDEPATH</code> later.',
+  },
+  {
+    key: 'bike_network',
+    kind: 'enum',
+    members: [
+      { value: 'missing',       color: '#666666', label: 'missing' },
+      { value: 'other',         color: '#bbbbbb', label: 'other' },
+      { value: 'local',         color: '#a6d96a', label: 'local' },
+      { value: 'regional',      color: '#1a9850', label: 'regional' },
+      { value: 'national',      color: '#4363d8', label: 'national' },
+      { value: 'international', color: '#911eb4', label: 'international' },
+    ],
+    note: 'Enum: <code>MISSING, OTHER, INTERNATIONAL, NATIONAL, REGIONAL, LOCAL</code> (shared <code>RouteNetwork</code> enum).<br><br><strong>Computed from:</strong> OSM relations of <code>route=bicycle</code> with <code>network=icn|ncn|rcn|lcn</code>. Each edge inherits the highest-tier network it belongs to.<br><br><strong>Why keep:</strong> Berliner Mauerweg, Radfernweg Berlin–Kopenhagen, Leipzig, the regional RSV/Radschnellverbindungen all show up via this. Profile already gives ×1.4 / ×1.2.',
+  },
+  {
+    key: 'mtb_rating',
+    kind: 'number',
+    domain: [0, 6],
+    stops: [[0,'#1a9850'],[2,'#fee08b'],[4,'#f46d43'],[6,'#a50026']],
+    note: 'Integer 0–6. 0 = no rating; higher = harder mountain-bike trail.<br><br><strong>Computed from:</strong> <code>mtb:scale=0..6</code>.<br><br><strong>Why keep:</strong> Upstream <code>bike.json</code> zeroes anything &gt; 2. Relevant in Grunewald/Spandauer Forst singletrack. Cheap.',
+  },
+  { key: 'hike_rating', kind: 'number', domain: [0, 6], stops: [[0,'#1a9850'],[2,'#fee08b'],[4,'#f46d43'],[6,'#a50026']] },
+  {
+    key: 'get_off_bike',
+    kind: 'boolean',
+    trueColor: '#d73027',
+    falseColor: '#1a9850',
+    directional: true,
+    note: 'Boolean. <code>true</code> if a cyclist would typically have to dismount.<br><br><strong>Computed from:</strong> <code>bicycle=dismount</code>, <code>highway=steps</code>, <code>highway=footway</code> without <code>bicycle=yes</code>/<code>designated</code>, etc.<br><br><strong>Why keep:</strong> Cleaner than checking individual conditions in the custom model — one <code>multiply_by: 0.1</code> rule covers all dismount cases. Slightly redundant with <code>bike_road_access == DISMOUNT</code>, but covers the steps/footway cases that aren\'t tagged <code>bicycle=dismount</code>.',
+  },
+
+  // Surface / smoothness / cycleway
+  {
+    key: 'surface',
+    kind: 'enum',
+    members: enumMembers(['missing','other','paved','asphalt','concrete','paving_stones','cobblestone','unpaved','compacted','fine_gravel','gravel','ground','dirt','grass','sand','wood']),
+    note: 'Enum: <code>MISSING, OTHER, PAVED, ASPHALT, CONCRETE, PAVING_STONES, COBBLESTONE, UNPAVED, COMPACTED, FINE_GRAVEL, GRAVEL, GROUND, DIRT, GRASS, SAND, WOOD</code>.<br><br><strong>Computed from:</strong> <code>surface=*</code>. Berlin note: <code>cobblestone</code> (rounded historic Kopfsteinpflaster) is much rougher than <code>paving_stones</code> (modern brick) — both common, both worth penalising at different strengths.<br><br><strong>Caveat:</strong> GraphHopper does not expose <code>sett</code> as a separate value — it\'s mapped to <code>OTHER</code>.',
+  },
+  {
+    key: 'smoothness',
+    kind: 'enum',
+    members: [
+      { value: 'impassable',    color: '#67000d', label: 'impassable' },
+      { value: 'very_horrible', color: '#a50026', label: 'very_horrible' },
+      { value: 'horrible',      color: '#d73027', label: 'horrible' },
+      { value: 'very_bad',      color: '#f46d43', label: 'very_bad' },
+      { value: 'bad',           color: '#fdae61', label: 'bad' },
+      { value: 'intermediate',  color: '#fee08b', label: 'intermediate' },
+      { value: 'good',          color: '#a6d96a', label: 'good' },
+      { value: 'excellent',     color: '#1a9850', label: 'excellent' },
+      { value: 'other',         color: '#bbbbbb', label: 'other' },
+      { value: 'missing',       color: '#666666', label: 'missing' },
+    ],
+    note: 'Enum: <code>MISSING, OTHER, EXCELLENT, GOOD, INTERMEDIATE, BAD, VERY_BAD, HORRIBLE, VERY_HORRIBLE, IMPASSABLE</code>.<br><br><strong>Computed from:</strong> <code>smoothness=*</code>.<br><br><strong>Why keep:</strong> Sparse but high-signal in Berlin park paths. Where present, a cyclist would much rather take an <code>INTERMEDIATE</code>-rated road than the parallel <code>BAD</code> one. Pair with <code>surface</code>.',
+  },
+  {
+    key: 'cycleway',
+    kind: 'enum',
+    directional: true,
+    members: [
+      { value: 'missing',     color: '#666666', label: 'missing' },
+      { value: 'other',       color: '#bbbbbb', label: 'other' },
+      { value: 'no',          color: '#d73027', label: 'no' },
+      { value: 'shoulder',    color: '#fdae61', label: 'shoulder' },
+      { value: 'shared_lane', color: '#fee08b', label: 'shared_lane' },
+      { value: 'lane',        color: '#a6d96a', label: 'lane' },
+      { value: 'track',       color: '#1a9850', label: 'track' },
+      { value: 'separate',    color: '#4363d8', label: 'separate' },
+    ],
+    note: 'Enum: <code>MISSING, OTHER, NO, LANE, TRACK, SHARED_LANE, SHOULDER, SEPARATE</code>.<br><br><strong>Computed from:</strong> <code>cycleway=*</code> and side-specific <code>cycleway:left|right=*</code> collapsed to a single per-edge value.<br><br><strong>Why keep:</strong> Lets the profile prefer <code>LANE</code>/<code>TRACK</code> over <code>MISSING</code>. Particularly relevant for Berlin arterials where the cycleway is part of the road geometry (so <code>road_class != CYCLEWAY</code> even though there is a marked lane).<br><br><strong>Caveat:</strong> GH collapses left+right into one enum — biased toward whichever side it picks first. Acceptable for shaping; not for navigation instructions.',
+  },
+  {
+    key: 'crossing',
+    kind: 'enum',
+    members: enumMembers(['missing','no','uncontrolled','marked','unmarked','traffic_signals','railway','railway_barrier']),
+    note: 'Enum: <code>MISSING, NO, UNCONTROLLED, MARKED, UNMARKED, TRAFFIC_SIGNALS, RAILWAY, RAILWAY_BARRIER</code>.<br><br><strong>Computed from:</strong> <code>crossing=*</code> on <code>highway=crossing</code> nodes, propagated to adjacent edges.<br><br><strong>Why keep:</strong> Enables a future "prefer controlled crossings on big roads" rule.',
+  },
+
+  // Road structure
+  {
+    key: 'road_class',
+    kind: 'enum',
+    members: enumMembers(['other','motorway','trunk','primary','secondary','tertiary','residential','unclassified','service','road','track','footway','pedestrian','living_street','bridleway','steps','cycleway','path','construction','platform','corridor','busway']),
+    note: 'Enum: <code>OTHER, MOTORWAY, TRUNK, PRIMARY, SECONDARY, TERTIARY, RESIDENTIAL, UNCLASSIFIED, SERVICE, ROAD, TRACK, FOOTWAY, PEDESTRIAN, LIVING_STREET, BRIDLEWAY, STEPS, CYCLEWAY, PATH, CONSTRUCTION, PLATFORM, CORRIDOR, BUSWAY</code>.<br><br><strong>Computed from:</strong> <code>highway=*</code>.<br><br><strong>Why keep:</strong> Foundation for per-class shaping — boost <code>LIVING_STREET</code>, <code>CYCLEWAY</code>; penalise <code>PRIMARY</code>/<code>SECONDARY</code> not on a network.',
+  },
+  {
+    key: 'road_environment',
+    kind: 'enum',
+    members: [
+      { value: 'road',   color: '#bbbbbb', label: 'road' },
+      { value: 'bridge', color: '#4363d8', label: 'bridge' },
+      { value: 'tunnel', color: '#911eb4', label: 'tunnel' },
+      { value: 'ferry',  color: '#46f0f0', label: 'ferry' },
+      { value: 'ford',   color: '#f58231', label: 'ford' },
+      { value: 'other',  color: '#666666', label: 'other' },
+    ],
+    note: 'Enum: <code>OTHER, ROAD, FERRY, TUNNEL, BRIDGE, FORD</code>.<br><br><strong>Computed from:</strong> <code>tunnel=*</code>, <code>bridge=*</code>, <code>route=ferry</code>, <code>ford=*</code>.<br><br><strong>Why keep:</strong> Profile penalises ferries; useful for snap_preventions and fording avoidance. Cheap.',
+  },
+  {
+    key: 'road_access',
+    kind: 'enum',
+    members: enumMembers(['yes','destination','delivery','customers','agricultural','forestry','private','military','no']),
+    note: 'Enum: <code>YES, DESTINATION, DELIVERY, CUSTOMERS, AGRICULTURAL, FORESTRY, PRIVATE, MILITARY, NO</code>.<br><br><strong>Computed from:</strong> <code>access=*</code> (general, vehicle-agnostic).<br><br><strong>Why keep:</strong> Complements <code>bike_road_access</code> — picks up restrictions affecting all vehicles (gated forestry tracks in the Grunewald, military areas). Sometimes the cheaper signal when bike-specific tagging is missing.',
+  },
+  {
+    key: 'roundabout',
+    kind: 'boolean',
+    trueColor: '#911eb4',
+    falseColor: '#bbbbbb',
+    note: 'Boolean. <code>true</code> if the edge is part of a <code>junction=roundabout</code> or <code>junction=circular</code>.<br><br><strong>Why keep:</strong> <code>bike.json</code> uses it to forbid wrong-way entry on roundabouts. Tiny cost.',
+  },
+
+  // Speed / slope (numeric, possibly directional → take forward side)
+  {
+    key: 'max_speed',
+    kind: 'number',
+    directional: true,
+    domain: [0, 130],
+    stops: [
+      [0,   '#999999'],
+      [30,  '#1a9850'],
+      [50,  '#fee08b'],
+      [70,  '#fdae61'],
+      [100, '#d73027'],
+      [130, '#67000d'],
+    ],
+    note: 'Decimal (km/h). The legal speed limit on the edge in the forward direction (<code>max_speed_reverse</code> exists separately). For German edges with no <code>maxspeed</code> tag, GraphHopper falls back to legal defaults via the <code>country</code> value.<br><br><strong>Computed from:</strong> <code>maxspeed=*</code>, then fallbacks per <code>country</code> × <code>road_class</code> × <code>urban_density</code> (<code>legal_default_speeds.json</code>).<br><br><strong>Why keep:</strong> Strong proxy for "scary to ride" — <code>max_speed &gt;= 50 km/h</code> without a separate cycleway is the classic Berlin Hauptverkehrsstraße. Profile rule waiting to be written.<br><br><em>"Infinity" (no legal limit) renders as 0/grey.</em>',
+  },
+  {
+    key: 'average_slope',
+    kind: 'number',
+    domain: [-15, 15],
+    stops: [
+      [-15, '#2166ac'],
+      [-5,  '#92c5de'],
+      [0,   '#f7f7f7'],
+      [5,   '#f4a582'],
+      [15,  '#b2182b'],
+    ],
+    note: 'Decimal (%). Average gradient of the edge from elevation samples.<br><br><strong>Computed from:</strong> SRTM elevation data sampled along the way geometry.<br><br><strong>Why keep:</strong> Used by <code>bike_elevation.json</code> to drop speed on climbs and bump it on descents. Berlin is ~flat, so it rarely fires, but cheap to keep.',
+  },
+  {
+    key: 'ferry_speed',
+    kind: 'number',
+    domain: [0, 30],
+    stops: [[0, '#d73027'], [15, '#fee08b'], [30, '#1a9850']],
+    note: 'Decimal (km/h). Speed at which to traverse a ferry edge.<br><br><strong>Why keep:</strong> <code>bike.json</code> references it. Cheap. (Almost no ferries inside the Berlin extract — Müggelsee, BVG-Fähre F10–F23 — but still relevant.)',
+  },
+];
+
+const BY_KEY = new Map(ENCODED_VALUES.map((ev) => [ev.key, ev]));
+
+export function getEncodedValue(key) {
+  return BY_KEY.get(key);
+}
+
+// MapLibre expression that takes a property like "50.0 | 50.0" and returns
+// the forward (left-of-pipe) substring. For non-directional values where the
+// raw string has no pipe, returns the raw value.
+function forwardPart(getExpr) {
+  return [
+    'let', 'raw', getExpr,
+    [
+      'case',
+      ['>=', ['index-of', '|', ['var', 'raw']], 0],
+      ['slice', ['var', 'raw'], 0, ['-', ['index-of', '|', ['var', 'raw']], 1]],
+      ['var', 'raw'],
+    ],
+  ];
+}
+
+const TRANSPARENT = 'rgba(0,0,0,0)';
+
+export function paintExpression(ev, hidden = []) {
+  if (!ev) return FALLBACK;
+  const get = ['get', ev.key];
+
+  if (ev.kind === 'enum') {
+    // Match both "value" and "value | value" (directional pairs where forward
+    // == backward, which covers the common case). Hidden members render
+    // transparent so toggling acts as a per-value visibility filter.
+    const expr = ['match', get];
+    for (const m of ev.members) {
+      const color = hidden.includes(m.value) ? TRANSPARENT : m.color;
+      expr.push([m.value, `${m.value} | ${m.value}`], color);
+    }
+    expr.push(FALLBACK);
+    return expr;
+  }
+
+  if (ev.kind === 'boolean') {
+    const truths = ev.directional
+      ? ['true', 'true | true', 'true | false', 'false | true']
+      : ['true'];
+    return ['match', get, truths, ev.trueColor, ev.falseColor];
+  }
+
+  if (ev.kind === 'number') {
+    const valueExpr = ev.directional ? forwardPart(get) : get;
+    const expr = ['interpolate', ['linear'], ['to-number', valueExpr, ev.domain[0]]];
+    for (const [v, c] of ev.stops) expr.push(v, c);
+    return expr;
+  }
+
+  return FALLBACK;
+}
+
+// ---------- Map source/layer wiring ----------
+
+const SOURCE_ID = 'gh-debug-mvt';
+const LAYER_ID = 'gh-debug-edges';
+const MIN_ZOOM = 12;
+// MVTResource in graphhopper-web encodes one layer named "roads" containing
+// every routable edge.
+const SOURCE_LAYER = 'roads';
+
+export const debugState = $state({
+  /** null = overlay disabled */
+  selectedKey: null,
+  /** for the legend */
+  selected: null,
+  /** member values currently toggled off for the active enum overlay */
+  hidden: [],
+  /** global filter: hide road_class=footway across every overlay */
+  hideFootways: false,
+});
+
+let currentMap = null;
+
+function tileUrl(key) {
+  // MapLibre fills {z}/{x}/{y}; we just need to keep `details` literal.
+  // `road_class` is always requested so the global "hide footways" filter
+  // can read it regardless of which encoded value is currently visualized.
+  const extra = key === 'road_class' ? '' : '&details=road_class';
+  return `/api/debug/mvt/{z}/{x}/{y}?details=${encodeURIComponent(key)}${extra}`;
+}
+
+function currentFilter() {
+  return debugState.hideFootways
+    ? ['!=', ['get', 'road_class'], 'footway']
+    : ['literal', true];
+}
+
+function ensureSource(map, key) {
+  // Tile URLs are baked in at addSource time, so we re-create the source
+  // whenever the encoded value changes (and `details` along with it).
+  removeSource(map);
+  map.addSource(SOURCE_ID, {
+    type: 'vector',
+    tiles: [`${window.location.origin}${tileUrl(key)}`],
+    minzoom: MIN_ZOOM,
+    maxzoom: 22,
+  });
+}
+
+function removeSource(map) {
+  if (map.getLayer(LAYER_ID)) map.removeLayer(LAYER_ID);
+  if (map.getSource(SOURCE_ID)) map.removeSource(SOURCE_ID);
+}
+
+function applyLayer(map, ev) {
+  if (map.getLayer(LAYER_ID)) map.removeLayer(LAYER_ID);
+  map.addLayer({
+    id: LAYER_ID,
+    type: 'line',
+    source: SOURCE_ID,
+    'source-layer': SOURCE_LAYER,
+    minzoom: MIN_ZOOM,
+    filter: currentFilter(),
+    paint: {
+      'line-color': paintExpression(ev, debugState.hidden),
+      'line-width': ['interpolate', ['linear'], ['zoom'], 12, 1, 16, 3, 20, 6],
+      'line-opacity': 0.85,
+    },
+  });
+}
+
+export function setHideFootways(value) {
+  debugState.hideFootways = !!value;
+  if (currentMap?.getLayer(LAYER_ID)) {
+    currentMap.setFilter(LAYER_ID, currentFilter());
+  }
+}
+
+function refreshPaint() {
+  if (!currentMap || !debugState.selected) return;
+  if (!currentMap.getLayer(LAYER_ID)) return;
+  currentMap.setPaintProperty(
+    LAYER_ID,
+    'line-color',
+    paintExpression(debugState.selected, debugState.hidden),
+  );
+}
+
+export function toggleMember(value) {
+  const idx = debugState.hidden.indexOf(value);
+  if (idx >= 0) debugState.hidden.splice(idx, 1);
+  else debugState.hidden.push(value);
+  refreshPaint();
+}
+
+export function setAllMembersVisible() {
+  debugState.hidden.length = 0;
+  refreshPaint();
+}
+
+export function setAllMembersHidden() {
+  const ev = debugState.selected;
+  if (!ev || ev.kind !== 'enum') return;
+  debugState.hidden.splice(0, debugState.hidden.length, ...ev.members.map((m) => m.value));
+  refreshPaint();
+}
+
+export function initDebugOverlay(map) {
+  currentMap = map;
+}
+
+export function setEncodedValue(key) {
+  debugState.hidden.length = 0;
+  if (!currentMap) {
+    debugState.selectedKey = key;
+    debugState.selected = key ? getEncodedValue(key) : null;
+    return;
+  }
+  if (!key) {
+    removeSource(currentMap);
+    debugState.selectedKey = null;
+    debugState.selected = null;
+    return;
+  }
+  const ev = getEncodedValue(key);
+  if (!ev) return;
+  ensureSource(currentMap, key);
+  applyLayer(currentMap, ev);
+  debugState.selectedKey = key;
+  debugState.selected = ev;
+}
diff --git a/web/src/lib/debugOverlay.test.js b/web/src/lib/debugOverlay.test.js
new file mode 100644
index 0000000..6092053
--- /dev/null
+++ b/web/src/lib/debugOverlay.test.js
@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { ENCODED_VALUES, paintExpression, getEncodedValue } from './debugOverlay.svelte.js';
+
+describe('debugOverlay metadata', () => {
+  it('every entry has a unique key', () => {
+    const keys = ENCODED_VALUES.map((ev) => ev.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('enum entries have at least one member', () => {
+    for (const ev of ENCODED_VALUES) {
+      if (ev.kind === 'enum') {
+        expect(ev.members.length).toBeGreaterThan(0);
+        for (const m of ev.members) {
+          expect(typeof m.value).toBe('string');
+          expect(m.color).toMatch(/^#[0-9a-f]{6}$/i);
+        }
+      }
+    }
+  });
+
+  it('number entries have monotonically increasing stop domains', () => {
+    for (const ev of ENCODED_VALUES) {
+      if (ev.kind !== 'number') continue;
+      const xs = ev.stops.map(([v]) => v);
+      for (let i = 1; i < xs.length; i++) {
+        expect(xs[i]).toBeGreaterThan(xs[i - 1]);
+      }
+    }
+  });
+});
+
+describe('paintExpression', () => {
+  it('returns a fallback color for unknown encoded values', () => {
+    expect(paintExpression(undefined)).toBe('#888');
+  });
+
+  it('builds a match expression covering bare and "X | X" pair forms for enums', () => {
+    const ev = getEncodedValue('road_class');
+    const expr = paintExpression(ev);
+    expect(expr[0]).toBe('match');
+    expect(expr[1]).toEqual(['get', 'road_class']);
+    // Each member contributes one [bare, "v | v"] / color pair.
+    for (const m of ev.members) {
+      const idx = expr.findIndex(
+        (v) => Array.isArray(v) && v[0] === m.value && v[1] === `${m.value} | ${m.value}`
+      );
+      expect(idx, `member ${m.value} missing from match`).toBeGreaterThan(-1);
+      expect(expr[idx + 1]).toBe(m.color);
+    }
+    // Final element is the fallback color.
+    expect(expr[expr.length - 1]).toBe('#888');
+  });
+
+  it('builds a directional boolean expression that accepts mixed pairs', () => {
+    const ev = getEncodedValue('get_off_bike');
+    const expr = paintExpression(ev);
+    expect(expr[0]).toBe('match');
+    expect(expr[2]).toEqual(['true', 'true | true', 'true | false', 'false | true']);
+    expect(expr[3]).toBe(ev.trueColor);
+    expect(expr[4]).toBe(ev.falseColor);
+  });
+
+  it('non-directional boolean only matches "true"', () => {
+    const ev = getEncodedValue('roundabout');
+    const expr = paintExpression(ev);
+    expect(expr[2]).toEqual(['true']);
+  });
+
+  it('directional number expression slices forward part before to-number', () => {
+    const ev = getEncodedValue('max_speed');
+    const expr = paintExpression(ev);
+    // ["interpolate", ["linear"], <inputExpr>, stop1, color1, ...]
+    expect(expr[0]).toBe('interpolate');
+    const valueExpr = expr[2];
+    expect(valueExpr[0]).toBe('to-number');
+    expect(JSON.stringify(valueExpr)).toContain('index-of');
+    expect(JSON.stringify(valueExpr)).toContain('slice');
+  });
+
+  it('non-directional number reads the property directly', () => {
+    const ev = getEncodedValue('average_slope');
+    const expr = paintExpression(ev);
+    expect(expr[2]).toEqual(['to-number', ['get', 'average_slope'], -15]);
+  });
+});