Design system, live freshness, autocomplete, and clay-pin markers

UI/UX (from the design handoff):
- Clay-sticker theme, hero, framed Voyager map with warm grade, loading
state ("Scouting your wander…"), route-draw + staggered marker pop-in
- 14-piece clay-pin marker family (vendored SVGs) with color-by-meaning
mapping for all 17 categories, start/dest pins, legend in the family's
color language
- Start/Destination autocomplete over the local 30k POI-name index
- Force-light mode (design is light-only; Gradio dark vars made text
unreadable), per-event js fixed to pass inputs through

Freshness:
- Open-now awareness from OSM opening_hours (9,461 POIs): conservative
evaluator (abstains on exotic grammar, per-rule PH/SH handling),
plan-time demotion of closed places, night realism for unknown-hours
daytime categories, 🟢/🔴 itinerary badges
- Optional Google Places live-verify of final stops (GOOGLE_MAPS_API_KEY;
ToS-clean: per-request, never stored)
- Embedder switched to fastembed/ONNX (no torch in the request path;
warms in ~9s), boot warmup for graph+POIs+embedder

Routing/quality:
- P1-2 single-pot budgeting: stops cost travel + dwell against one
(1+budget)×direct cap; honest "+N min incl. lingering" accounting
- Gloss surgery: "specialty coffee tour" no longer routes to attractions
("tour"→"tourist" false-friend); coffee shops/roasters rank first
- Corridor STRtree + matrix reuse across alternatives (~1.3s warm plans)
- Hardened grounding gate (appended-qualifier hallucinations), Nominatim
timeout/UA, geocode cache, graceful degradation on solver errors

Tests: hours (12), geocode/autocomplete (3), property-based vibe fit;
suite green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitignore

@@ -16,9 +16,16 @@ flagged/
 # OS
 .DS_Store
 
-# Design handoff assets (build-time reference only — not shipped to the Space)
+# Design handoff assets (build-time reference only — not shipped to the Space;
+# the marker SVGs are vendored into src/discoverroute/ui/icons/)
 ux app.zip
 ux-design/
+design_handoff_discoverroute/
+design_handoff_discoverroute copy/
+
+# Local dev tooling + scratch test output
+.claude/
+test_output.log
 
 # NOTE: data/*.graphml and data/*.parquet are the offline build artifacts.
 # They are committed for the Hugging Face Space so it needs no runtime download.

DEPLOY.md

@@ -52,6 +52,27 @@ the Qwen3.5-9B generative narration:
 To force the LLM on/off regardless of hardware, set the Space variable
 `DISCOVERROUTE_USE_LLM` to `1` / `0`.
 
+## Optional: live Google verification of the final stops
+
+Set the Space **secret** `GOOGLE_MAPS_API_KEY` (Google Cloud → APIs → Places API
+(New) enabled, billing on) and each planned route live-verifies its ~8 chosen
+stops: permanently-closed detection, open-right-now, rating. Notes:
+- Hours fields bill at the Enterprise SKU → ~1,000 free lookups/month ≈ 125
+  routes; ~$0.15/route beyond. Only the final stops are queried, never stored
+  (Google ToS), and OSM remains the routing/candidate base.
+- Without the key the app is fully offline: open-now still works from OSM
+  `opening_hours` tags (~31% of POIs carry them).
+
+## Refreshing the data snapshot
+
+Place data is a build-time snapshot. To refresh it (e.g. before a demo):
+```bash
+rm -rf cache/   # drop the Overpass HTTP cache to force a fresh download
+.venv/bin/python -m discoverroute.data.build_graph   # ~3 min
+.venv/bin/python -m discoverroute.data.build_pois    # ~12 min
+```
+OSM edits typically reach Overpass within minutes, so a rebuild is near-live.
+
 ## Notes
 - First boot loads the 90 MB graph (~9 s, one-time); warm requests are ~1 s.
 - If you ever rebuild the data: `python -m discoverroute.data.build_graph` then

FIELD_NOTES.md

@@ -0,0 +1,69 @@
+# Field Notes: Building DiscoverRoute
+
+> **Draft.** Written from the build log (`PROGRESS.md`) and the Space card (`README.md`) for the Build Small Hackathon's *Field Notes* badge. Review, personalize, and add your own voice before publishing.
+
+## The inversion
+
+Every navigation app I've used solves the same problem: get me there in the minimum time. DiscoverRoute starts from the opposite premise. If you're walking across Paris and you'd happily spend fifteen extra minutes, that surplus is a *budget* — and the interesting question is what to spend it on.
+
+So the app takes a start, a destination, a free-text vibe, and an "adventurousness" level, and returns a walkable or bikeable route that deliberately detours past places matching your taste — within a hard travel-time budget — plus a narrated itinerary explaining why each place is on the path. The route never exceeds `(1 + budget) ×` the direct time, and budget 0 simply gives you the plain route. It runs on small (≤32B) open models and OpenStreetMap data, single city: Paris.
+
+## Walking skeleton first, AI last
+
+The strategy I committed to in the build log's first line: *walking skeleton first; scariest plumbing early; AI added only after a manual-weight router already works.* Each brick had a definition-of-done and a test, and wasn't left until green.
+
+That meant the first four bricks contained no AI at all.
+
+**Brick 0** was the boring-but-scary plumbing: download the Paris walk network via OSMnx into a graph of **77,454 nodes and 221,688 edges** (a 90 MB GraphML file), geocode inputs, run Dijkstra, render the polyline on a Folium map inside a Gradio shell. Seven tests, including a sanity check that République→Luxembourg is at least 2 km and that bike beats walk (travel time is derived per mode from one graph: walk 4.8 km/h, bike 15 km/h).
+
+**Brick 1** built the POI layer: **30,589 Paris POIs across 17 curated categories**, cached to a 1.2 MB parquet file, each with greenness/quietness priors and a *confidence* score derived from OSM tag richness.
+
+**Bricks 2–3** were the heart of the system, and they're classical algorithms: a budgeted **submodular orienteering solver**. The key modeling insight is diversity by design. A naive scorer that just sums point values will happily route you past five cafés, because cafés are everywhere and score fine individually. The submodular reward applies *diminishing returns per category*: the first café is worth full value, the second much less, the third almost nothing. So a park + a viewpoint + a bookshop beats five cafés — not because of a hand-tuned penalty, but because the objective itself says variety is worth more than repetition. The solver is a better-of-two greedy (picking by raw gain *and* by reward-per-added-time, keeping the better result), tested against a known-optimal synthetic instance, with an explicit diversity-beats-repetition test.
+
+Only once that manual-weight router produced real discovery routes on a real map did any model enter the picture.
+
+## What the small models actually do
+
+Two models, both deliberately small, each load-bearing in exactly one place:
+
+- **`BAAI/bge-small-en-v1.5` (~33M parameters, CPU-only)** turns your free-text vibe into category affinities. Each of the 17 categories has a short gloss; the vibe is embedded and matched by cosine similarity to those glosses, min-max rescaled into a usable weight range. "Quiet green wander" and a contrasting vibe produce measurably different waypoint sets on the same A/B pair — that's an end-to-end test, not a hope.
+- **`Qwen/Qwen3.5-9B` (Apache 2.0, thinking mode off)** is an *optional* narration enhancer. The default itinerary text comes from a deterministic template that is grounded by construction; the LLM only rewrites it, on GPU (ZeroGPU on the Space), and is gated by a verifier (more on that below). bf16 at ~18 GB it sits comfortably on ZeroGPU. I considered the whole ≤32B ladder — Qwen3.5-4B (lighter), 9B (chosen), 27B (needs quantization on 40 GB) — and excluded Qwen3.5-35B-A3B because 35B breaks the hackathon's 32B cap.
+
+Small-is-the-point here, not a constraint to grumble about. Routing is pure classical algorithms; the model is load-bearing only in interpretation and narration. The skeleton runs CPU-only and offline with the rule-based fallback — which means the template-narration mode runs on nothing but the 33M embedder. Your taste profile never needs to leave your device (it's persisted per-device via browser state, no accounts), and the whole interpretation stack fits on a laptop.
+
+## The zero-hallucination gate
+
+LLMs narrating a route is exactly the place hallucination hurts most: the model will cheerfully invent a charming bistro that doesn't exist. So narration sits behind a **fail-closed grounding verifier**: it extracts capitalized place-name spans from the generated text (handling multi-word names and French "de la" chains) and passes only if *every* mention maps to an allowed name — the route's waypoints, the start/end, or "Paris". Any violation, and the system silently falls back to the deterministic template. The release-gate test plants a hallucinated "Eiffel Tower" in narration and verifies the gate catches it; the final end-to-end test asserts the shipped narration is grounded.
+
+Then the adversarial review pass found a real hole in it. The old check accepted an allowed name being a *substring* of a longer mention — so if "Café de la Paix" was a real waypoint, the invented "Café de la Paix sur Seine" sailed through. The fix inverts the containment: strip common words from a mention, then require the *core* to be a substring of an allowed name, not the reverse. The same pass also fixed mention extraction, which had been gluing "République, Paris and Jardin…" into one span by treating "and"/"et" as name-internal. Both attack shapes — appended qualifier and shortened reference — now have regression tests.
+
+## War stories
+
+A few things that broke, and what fixing them taught me:
+
+**Overpass timed out.** The combined POI query for all of Paris was too much for the Overpass API. Fix: fetch one tag key at a time with a 300s timeout — amenity (77k raw), shop (29k), tourism (7.5k), leisure (6k), historic (2.5k), natural — then filter down to the 30,589 classified POIs.
+
+**Per-pair routing was the first latency wall.** Computing travel times between candidate POIs pair-by-pair put warm requests at **8–14 seconds**. Replacing it with **SciPy multi-source Dijkstra** — one C call over a cached CSR adjacency matrix — brought warm per-request latency to **~1 second**.
+
+**The 635ms hiding in a loop.** During the adversarial review, the performance reviewer reported alarming numbers — which turned out to be a red herring: their machine was thrashing. Re-measured on a clean machine, the suggested fix (porting route-stitching to CSR) was needless — stitch was only 59ms. The real bottleneck was `build_matrix` at **~635ms, recomputed three times** inside the alternatives loop. Hoisting the corridor selection and matrix out of the loop (compute once, reuse) dropped `n_alternatives=3` from **~2.1s to ~1.3s** — the same cost as a single route. An STRtree took corridor selection from 87ms to ~5ms for good measure. Lesson: measure on a quiet machine before believing a profile, and look for repeated work before clever work.
+
+**The review fixed product lies, too.** The alternatives label showed *total* minutes where it claimed to show detour minutes; the vibe's budget hint was displayed but silently discarded; off-domain vibes ("tax deadline") manufactured false preferences until a minimum-similarity-span guard mapped them to neutral. And error handling got hardened so disconnected nodes or a corrupt parquet degrade to the plain route instead of a traceback. After the pass: 42 tests passing.
+
+## The design handoff port
+
+The default Gradio look got replaced wholesale from a design handoff: a low-poly "clay sticker" aesthetic — cream paper background, cobalt/grass/coral/sun palette, Fredoka display type. The port landed as a theme plus CSS (sticker cards, a coral CTA that visibly depresses, springy sliders, a framed map window with a titlebar), a results bounce-in observer, and a friendly empty/no-detour state.
+
+The fiddliest part: the map is a Folium iframe, and **an iframe can't be animated from the parent page**. So the route draw-on and the staggered POI marker pops are injected as JavaScript *inside* the iframe's own document, keyed off CSS class names attached to the polylines and markers at render time. Reduced-motion and AA focus rings are respected throughout.
+
+## Honest limitations
+
+- **Bike uses the walk graph.** One mode-agnostic graph, with per-mode speeds. Routing bikes on the pedestrian network is a documented v1 approximation; a separate bike graph is on the deferred list.
+- **Confidence is OSM tag richness, nothing more.** A well-tagged tourist trap looks "confident"; a beloved hole-in-the-wall with two tags looks risky. The adventurousness slider leans into this honestly — it both fades the confidence penalty and *boosts* under-documented POIs — but the signal itself is just tag count.
+- **Paris only.** The graph and POI table are built offline for one city. The pipeline generalizes; the data doesn't, yet.
+- Cold boot pays ~8.6s to load the 90 MB graph (plus 0.2s for the CSR cache); a faster serialization is a known, deferred debt.
+
+## What's next
+
+The P2 list, in rough order: live navigation (today it's plan-then-walk), external enrichment beyond OSM tags so "confidence" can mean more than tag richness, and place embeddings so taste matching can operate on places themselves rather than on 17 categories. Nearer-term housekeeping from the log: a real bike graph, faster graph serialization, and per-place removal in the profile UI.
+
+The submission itself is the last brick: push to a Space under the hackathon org, record the demo, write the post — and decide whether DiscoverRoute is Backyard AI (a real problem, really used) or a resident of the Thousand Token Wood.

PROGRESS.md

@@ -206,6 +206,67 @@ aesthetic: cream paper, cobalt/grass/coral/sun, Fredoka display type.
 - Assets: inline-SVG placeholders shipped; 6 clay illustrations to
   generate/commission later per the kit's asset checklist (style spec saved).
 
+### Live browser testing pass (2026-06-10/11, via Chrome extension + computer-use)
+Found & fixed — none of these were catchable headlessly:
+1. **Plan click hung forever**: per-event `js=` (DR_CELEBRATE) didn't pass
+   Gradio's input values through → all inputs nulled AND completion chain broken.
+   Fix: `(...args) => {…; return args;}`.
+2. **Dark-mode unreadability**: OS dark mode flips Gradio vars to near-white text
+   on our forced-cream cards. Fix: head-script strips the `dark` class
+   (debounced, childList-only observer — a hot attribute observer livelocked the
+   renderer) + `.dark` CSS var overrides as backstop. Design is light-only.
+3. **First-request freeze (minutes)**: lazy `import torch` (~1 GB dylibs) in the
+   request path. Fix: **switched the embedder to fastembed/ONNX** (same
+   bge-small; warms in ~9 s incl. download, no torch) with sentence-transformers
+   fallback; warmup() also pre-warms the embedder + POIs at boot.
+4. Cosmetics: input text + map-titlebar colors were theme-washed; unselected
+   mode-segment and route-option cards were dark-on-dark; accordion labels faint;
+   `launch(js=…)` silently never executes (moved enhancer into `head=`).
+
+**Programmatic E2E (gradio_client against the live app)**: vibe plan 2.6 s warm
+with 3 labeled options ("+7 min · 8 stops (artwork, park garden)"); contrasting
+vibe → different itinerary, cafe top-ranked; budget 0 → no discovery polyline,
+plain messaging, no-detour state visible; head script + CSS + fonts delivered;
+profile save round-trips. All green.
+
+### Freshness stack (2026-06-11) — open-now + optional Google live-verify
+- **Map face-lift**: CARTO Voyager tiles + warm grade; POI markers colored by
+  category family (grass nature / cobalt culture / sun food / coral art) with a
+  matching legend; autocomplete dropdowns over the local 30k-name index
+  (`geocode.suggest`, key_up); "Scouting your wander…" loading state via a
+  .then() chain.
+- **Open-now from OSM (free, offline)**: `opening_hours` stored at build (9,461
+  POIs, 31%); `routing/hours.py` conservative evaluator (abstains on exotic
+  grammar; PH/SH rules dropped per-rule, not whole-spec); plan-time demotion
+  closed-stop ×0.2 / closed-pass ×0.7; unknown-hours daytime categories ×0.5 at
+  night; 🟢/🔴 badges in the itinerary. Verified live at 23 h: route picks only
+  open bars/cafés.
+- **P1-2 single-pot budgeting fix**: a stop now costs added-travel + dwell
+  against the ONE (1+budget)×direct cap (the old separate 40 % dwell pot made
+  "bar hopping" unable to afford a single 15-min bar). Summary/labels/narration
+  count dwell ("+26 min incl. ~25 min lingering").
+- **Google Places live-verify (optional)**: `enrich/google_places.py` — with
+  GOOGLE_MAPS_API_KEY set, the final stops get businessStatus/openNow/rating at
+  display time (ToS-clean: never stored; ~125 free routes/month, Enterprise SKU).
+  Silent no-op without the key. DEPLOY.md documents key setup + data-refresh.
+- Tests: 12 hours/no-key tests added; suite green (orienteering/pipeline 25/25).
+
+### Vibe quality + clay-pin markers (2026-06-12)
+- **"specialty coffee tour" bug**: the token "tour" lit up the attraction gloss
+  ("notable TOURist attraction") at 1.0, beating cafe — routes went to escape
+  rooms. Gloss surgery: attraction → "a famous landmark or major sight worth
+  seeing"; cafe gloss gains "specialty coffee shop, espresso"; bakery gloss
+  gains "coffee roaster" (OSM shop=coffee lands there). Now cafe 1.0 /
+  bakery .97 / attraction .79, and "famous landmarks tour" still → attraction.
+  18 interpret/profile/narration tests green.
+- **Designed marker family integrated** (user's icons/ handoff): 14 clay-pin
+  SVGs copied to `ui/markers.py` + `ui/icons/`; 17 categories mapped to the 14
+  kinds (color-by-meaning: cobalt water/wayfinding · grass green space · coral
+  culture · sun cozy stops); Leaflet DivIcons with tip-anchored pins, cast
+  shadow, springy hover, staggered pop-in (reduced-motion gated); start/dest
+  clay pins replace stock folium markers; legend re-labeled to the family's
+  color language. Verified live: pins + pop-in CSS + endpoint pins in map HTML.
+
 ---
 
 ## Decisions (made with user, 2026-06-08)

app.py

@@ -28,7 +28,8 @@ def _saved_md(profile: dict) -> str:
 
 
 def _alt_label(i: int, alt, plain) -> str:
-    extra = round(alt.discovery.time_min - plain.time_min)
+    extra = round(alt.discovery.time_min + alt.discovery.dwell_s / 60.0
+                  - plain.time_min)
     from collections import Counter
     top = Counter(p.category for p in alt.pois).most_common(2)
     flavor = ", ".join(c.replace("_", " ") for c, _ in top)
@@ -111,6 +112,22 @@ def on_clear_profile():
     return empty, "", _saved_md(empty)
 
 
+def on_suggest(evt: gr.KeyUpData):
+    """Autocomplete a Start/Destination field from the local POI-name index."""
+    from discoverroute.routing.geocode import suggest
+    typed = evt.input_value or ""
+    matches = list(suggest(typed))
+    # keep what the user typed selectable on top; never clobber their text
+    choices = ([typed] if typed and typed not in matches else []) + matches
+    return gr.update(choices=choices or [typed])
+
+
+def show_loading():
+    """Instant feedback the moment Plan is clicked (the .then chain computes)."""
+    return (design.LOADING_HTML, gr.update(visible=False),
+            gr.update(visible=False), gr.update(visible=False))
+
+
 def build_ui() -> gr.Blocks:
     with gr.Blocks(title="DiscoverRoute · Paris") as demo:
         profile = gr.BrowserState(
@@ -126,13 +143,17 @@ def build_ui() -> gr.Blocks:
             # ---- LEFT: controls --------------------------------------------
             with gr.Column(scale=4, min_width=340):
                 with gr.Group():
-                    start = gr.Textbox(label="Start", elem_id="dr-start",
-                                       elem_classes="dr-field",
-                                       info="Address, or 'lat, lon'",
-                                       value="Place de la République, Paris")
-                    dest = gr.Textbox(label="Destination", elem_id="dr-dest",
-                                      elem_classes="dr-field",
-                                      value="Jardin du Luxembourg, Paris")
+                    start = gr.Dropdown(
+                        label="Start", elem_id="dr-start", elem_classes="dr-field",
+                        info="Type a Paris place — suggestions appear as you type",
+                        value="Place de la République, Paris",
+                        choices=["Place de la République, Paris"],
+                        allow_custom_value=True, filterable=True)
+                    dest = gr.Dropdown(
+                        label="Destination", elem_id="dr-dest", elem_classes="dr-field",
+                        value="Jardin du Luxembourg, Paris",
+                        choices=["Jardin du Luxembourg, Paris"],
+                        allow_custom_value=True, filterable=True)
                     vibe = gr.Textbox(label="Vibe (free text)", elem_id="dr-vibe",
                                       elem_classes="dr-field",
                                       info="e.g. 'quiet green wander' or 'lively café crawl'")
@@ -184,7 +205,18 @@ def build_ui() -> gr.Blocks:
                 nodetour_html = gr.HTML(design.NO_DETOUR_HTML, visible=False,
                                         elem_id="dr-nodetour")
 
+        # Cosmetic map-press bounce. Gradio feeds an event's `js` return value
+        # back as the inputs to its `fn`; a side-effect-only js (returns
+        # undefined) attached to the data event corrupts on_plan's inputs and
+        # white-screens the frontend. So keep the animation on its own fn-less
+        # listener, where its return value is harmless.
+        go.click(None, js=design.DR_CELEBRATE)
+        # Loading state first (instant), then the actual planning overwrites it.
         go.click(
+            show_loading,
+            outputs=[map_out, results_grp, nodetour_html, alt_radio],
+            show_progress="hidden",
+        ).then(
             on_plan,
             inputs=[start, dest, mode, budget, vibe, adventurousness,
                     prefer_green, prefer_quiet, profile],
@@ -192,8 +224,10 @@ def build_ui() -> gr.Blocks:
                      summary_out, interpretation_out, itinerary_out,
                      alts_state, last_cats],
             show_progress="minimal",
-            js=design.DR_CELEBRATE,
         )
+        # Autocomplete Start/Destination from the local POI-name index.
+        for _field in (start, dest):
+            _field.key_up(on_suggest, outputs=[_field], show_progress="hidden")
         alt_radio.change(on_select_alt, inputs=[alt_radio, alts_state],
                          outputs=[map_out, summary_out, itinerary_out])
         save_places_btn.click(on_save_places, inputs=[profile, last_cats],
@@ -208,7 +242,8 @@ def build_ui() -> gr.Blocks:
 
 
 def warmup():
-    """Preload graph + CSR + POIs at boot so the first request is fast (~1s)."""
+    """Preload graph + CSR + POIs + the vibe embedder at boot so the first
+    request is fast (~1s) instead of paying the torch/model load lazily."""
     try:
         from discoverroute.routing import graph as g
         from discoverroute.routing import pois as poimod
@@ -217,7 +252,13 @@ def warmup():
         poimod.load_pois()
         print("[warmup] routing graph + POIs ready", flush=True)
     except Exception as exc:  # noqa: BLE001
-        print(f"[warmup] FAILED: {exc}", flush=True)
+        print(f"[warmup] graph FAILED: {exc}", flush=True)
+    try:
+        from discoverroute.interpret import embed
+        embed.vibe_to_affinity("quiet green wander")  # loads model + gloss cache
+        print("[warmup] vibe embedder ready", flush=True)
+    except Exception as exc:  # noqa: BLE001
+        print(f"[warmup] embedder skipped: {exc}", flush=True)
 
 
 if __name__ == "__main__":
@@ -226,5 +267,4 @@ if __name__ == "__main__":
         theme=design.build_theme(),
         css=design.DR_CSS,
         head=design.DR_HEAD,
-        js=design.DR_JS,
     )

data/paris_pois.parquet

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b5f4466e30a6857ad79cc4773b96b5856836d5ede6d57cb8be36c5280877c311
-size 1207586
+oid sha256:ee83e69ffff3971cf41042d10ea891ce853dc440e09dd275a8cd821d8751e26a
+size 1333331

pyproject.toml

@@ -20,6 +20,7 @@ dependencies = [
 # Brick 4/6: vibe interpretation + narration. Kept optional so the
 # walking skeleton (Bricks 0-3) installs without ML weights.
 ml = [
+    "fastembed>=0.4",
     "sentence-transformers>=3.0",
     "transformers>=4.45",
     "accelerate>=1.0",

requirements.txt

@@ -13,7 +13,9 @@ folium==0.20.0
 # UI
 gradio==6.17.3
 
-# Vibe interpretation (Brick 4)
+# Vibe interpretation (Brick 4) — fastembed (ONNX, no torch) is the primary
+# backend; sentence-transformers remains as fallback.
+fastembed>=0.4
 sentence-transformers==5.5.1
 
 # Narration LLM (Brick 6) — Qwen3.5-9B on ZeroGPU

src/discoverroute/data/build_pois.py

@@ -90,6 +90,7 @@ def build_pois(place: str = config.PARIS_PLACE) -> pd.DataFrame:
             continue
         osm_type, osm_id = (idx if isinstance(idx, tuple) else ("node", idx))
         name = tags.get("name")
+        hours = tags.get("opening_hours")
         records.append(
             {
                 "osm_type": str(osm_type),
@@ -102,6 +103,7 @@ def build_pois(place: str = config.PARIS_PLACE) -> pd.DataFrame:
                 "quietness": taxonomy.quietness(category),
                 "confidence": round(taxonomy.confidence(tags), 4),
                 "n_tags": len(tags),
+                "opening_hours": str(hours) if hours is not None else None,
             }
         )
 

src/discoverroute/data/taxonomy.py

@@ -53,13 +53,13 @@ CATEGORY_GLOSS: dict[str, str] = {
     "library": "a library, quiet reading and books",
     "bookshop": "an independent bookshop, browsing books",
     "theatre_cinema": "a theatre or cinema, performance and film",
-    "cafe": "a cosy cafe for coffee and a pause",
-    "bakery_food_shop": "a bakery, patisserie, chocolate or fine-food shop",
+    "cafe": "a cosy cafe or specialty coffee shop, espresso and a pause",
+    "bakery_food_shop": "a bakery, patisserie, coffee roaster, chocolate or fine-food shop",
     "restaurant": "a restaurant for a proper meal",
     "bar_pub": "a lively bar, pub or wine bar, drinks and atmosphere",
     "market": "a bustling open-air or covered market, food and stalls",
     "specialty_shop": "a characterful specialty shop — antiques, art, design",
-    "attraction": "a notable tourist attraction or point of interest",
+    "attraction": "a famous landmark or major sight worth seeing",
 }
 
 

src/discoverroute/enrich/__init__.py

@@ -0,0 +1 @@
+"""Pluggable live-enrichment sources (spec P2-2). Optional; never required."""

src/discoverroute/enrich/google_places.py

@@ -0,0 +1,87 @@
+"""Optional live verification of the FINAL selected stops via Google Places.
+
+Design constraints (and why this module looks the way it does):
+  * Google's ToS prohibit storing Places content (only place_id is cacheable),
+    so this runs per-request on the ~8 chosen stops only and nothing is
+    persisted. OSM remains the storable base for candidates and routing.
+  * Opening-hours fields bill at the Enterprise SKU (1,000 free events/month
+    => ~125 free routes). Verifying only the final stops keeps cost bounded.
+  * Entirely optional: without ``GOOGLE_MAPS_API_KEY`` in the environment this
+    module is a silent no-op and the app stays fully offline.
+
+Each verified POI gains ``.live_status`` (True=open now, False=closed) and
+``.live_rating`` — consumed by the narration template's badges.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+logger = logging.getLogger("discoverroute")
+
+_ENDPOINT = "https://places.googleapis.com/v1/places:searchText"
+_FIELDS = ("places.id,places.displayName,places.businessStatus,"
+           "places.currentOpeningHours.openNow,places.rating")
+_TIMEOUT_S = 3.0
+_MAX_STOPS = 12
+
+
+def api_key() -> str | None:
+    return os.environ.get("GOOGLE_MAPS_API_KEY") or None
+
+
+def _verify_one(poi, key: str) -> None:
+    """Look up one POI by name near its coordinates; annotate it in place."""
+    name = getattr(poi, "name", None)
+    if not name:
+        return
+    body = json.dumps({
+        "textQuery": name,
+        "locationBias": {"circle": {
+            "center": {"latitude": poi.lat, "longitude": poi.lon},
+            "radius": 150.0,
+        }},
+        "maxResultCount": 1,
+    }).encode()
+    req = urllib.request.Request(
+        _ENDPOINT, data=body, method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "X-Goog-Api-Key": key,
+            "X-Goog-FieldMask": _FIELDS,
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as resp:
+            data = json.loads(resp.read().decode())
+    except Exception as exc:  # noqa: BLE001 - enrichment must never break a route
+        logger.warning("google verify failed for %r: %s: %s",
+                       name, type(exc).__name__, exc)
+        return
+    places = data.get("places") or []
+    if not places:
+        return
+    place = places[0]
+    if place.get("businessStatus") == "CLOSED_PERMANENTLY":
+        poi.live_status = False
+        return
+    open_now = (place.get("currentOpeningHours") or {}).get("openNow")
+    if open_now is not None:
+        poi.live_status = bool(open_now)
+    rating = place.get("rating")
+    if rating is not None:
+        poi.live_rating = float(rating)
+
+
+def verify_stops(pois: list) -> bool:
+    """Live-verify up to _MAX_STOPS POIs in parallel. Returns True if any ran."""
+    key = api_key()
+    if not key or not pois:
+        return False
+    batch = pois[:_MAX_STOPS]
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        list(pool.map(lambda p: _verify_one(p, key), batch))
+    return True

src/discoverroute/interpret/embed.py

@@ -5,22 +5,46 @@ user's vibe to affinities over the *finite* OSM category vocabulary by cosine
 similarity to each category's human-readable gloss. The output is interpretable
 weights — the scoring path downstream stays a transparent weighted sum.
 
-The model loads lazily so the rest of the app (and the walking skeleton) runs
-without it. Category gloss embeddings are computed once and cached.
+Backends (same bge-small model either way):
+  1. **fastembed / ONNXRuntime** (preferred) — no torch import. Torch is ~1 GB of
+     shared libraries; loading it lazily mid-request froze the app for minutes on
+     a memory-pressured laptop and would slow Space cold-starts too.
+  2. **sentence-transformers** (fallback) — used only if fastembed is absent.
+
+Everything loads lazily and is cached; gloss embeddings are computed once.
 """
 from __future__ import annotations
 
 import functools
 
+import numpy as np
+
 from discoverroute import config
 from discoverroute.data import taxonomy
 
 
 @functools.lru_cache(maxsize=1)
-def _model():
-    from sentence_transformers import SentenceTransformer
+def _encoder():
+    """Return (name, encode_fn) where encode_fn(list[str]) -> normalized ndarray."""
+    try:
+        from fastembed import TextEmbedding
+
+        model = TextEmbedding(model_name=config.EMBED_MODEL)
+
+        def encode(texts: list[str]) -> np.ndarray:
+            vecs = np.stack(list(model.embed(texts)))
+            return vecs / np.linalg.norm(vecs, axis=1, keepdims=True)
+
+        return "fastembed", encode
+    except Exception:  # noqa: BLE001 - fall back to the torch stack
+        from sentence_transformers import SentenceTransformer
+
+        model = SentenceTransformer(config.EMBED_MODEL)
+
+        def encode(texts: list[str]) -> np.ndarray:
+            return model.encode(texts, normalize_embeddings=True)
 
-    return SentenceTransformer(config.EMBED_MODEL)
+        return "sentence-transformers", encode
 
 
 @functools.lru_cache(maxsize=1)
@@ -28,24 +52,26 @@ def _gloss_matrix():
     """(categories, normalized gloss embedding matrix) computed once."""
     cats = list(taxonomy.CATEGORY_GLOSS.keys())
     glosses = [taxonomy.CATEGORY_GLOSS[c] for c in cats]
-    emb = _model().encode(glosses, normalize_embeddings=True)
-    return cats, emb
+    _, encode = _encoder()
+    return cats, encode(glosses)
 
 
+@functools.lru_cache(maxsize=256)
 def vibe_to_affinity(vibe: str) -> dict[str, float]:
     """Map a free-text vibe to a {category: affinity in [floor, 1]} dict.
 
     Cosine similarities are min-max rescaled across categories so the best match
     is 1.0 and the weakest is the configured floor — guaranteeing measurable
     contrast between different vibes while keeping a little exploration room.
+    Cached per vibe text (repeated demo prompts don't re-encode).
     """
     vibe = (vibe or "").strip()
     cats, gloss_emb = _gloss_matrix()
     if not vibe:
         return {c: 1.0 for c in cats}  # neutral: equal interest
 
-    query = config.EMBED_QUERY_INSTRUCTION + vibe
-    q = _model().encode([query], normalize_embeddings=True)[0]
+    _, encode = _encoder()
+    q = encode([config.EMBED_QUERY_INSTRUCTION + vibe])[0]
     sims = gloss_emb @ q  # cosine (both normalized)
 
     lo, hi = float(sims.min()), float(sims.max())

src/discoverroute/narrate/narrate.py

@@ -46,7 +46,8 @@ def _verb(posture: str) -> str:
 def template_narration(plain, discovery, pois, vibe, mode, start_label="",
                        end_label="", posture=None) -> str:
     posture = posture or {}
-    extra = round(discovery.time_min - plain.time_min)
+    extra = round(discovery.time_min + getattr(discovery, "dwell_s", 0.0) / 60.0
+                  - plain.time_min)
     unit = "minute" if extra == 1 else "minutes"
     lead = f"### Why this route\n"
     vibe_clause = f" for a *{vibe.strip()}*" if (vibe or "").strip() else ""
@@ -60,7 +61,17 @@ def template_narration(plain, discovery, pois, vibe, mode, start_label="",
         name = p.name or f"a {p.category.replace('_', ' ')}"
         reason = _REASON.get(p.category, "a stop worth making")
         verb = _verb(posture.get(p.category, "pass"))
-        lines.append(f"{i}. **{name}** — {verb.lower()} for {reason}.")
+        state = getattr(p, "open_state", None)
+        live = getattr(p, "live_status", None)  # Google-verified, when present
+        if live is not None:
+            badge = " · 🟢 open now ✓live" if live else " · 🔴 closed right now ✓live"
+        elif state is True:
+            badge = " · 🟢 open now"
+        elif state is False:
+            badge = " · 🔴 closed right now"
+        else:
+            badge = ""
+        lines.append(f"{i}. **{name}** — {verb.lower()} for {reason}.{badge}")
     lines.append(
         f"\nThen on to {end_label or 'your destination'}. Every place above is a "
         f"real spot on your route — nothing invented."

src/discoverroute/pipeline.py

@@ -109,7 +109,8 @@ def plan_route(
     used_ids: set[int] = set()
     try:
         shortlist, matrix, time_fn = _prepare_discovery(
-            graph, start, end, plain, mode, budget, weights, adventurousness)
+            graph, start, end, plain, mode, budget, weights, adventurousness,
+            posture=posture)
         for _ in range(max(1, n_alternatives)):
             if shortlist is None:
                 break
@@ -119,6 +120,9 @@ def plan_route(
             if discovery is None or not selected:
                 break
             used_ids.update(p.osm_id for p in selected)
+            # Optional live verification of the chosen stops (no-op without key).
+            from discoverroute.enrich import google_places
+            google_places.verify_stops(selected)
             itinerary_md, _ = narrate(
                 plain, discovery, selected, vibe=vibe, mode=mode,
                 start_label=start_query.strip(), end_label=dest_query.strip(),
@@ -159,7 +163,8 @@ def plan_route(
     )
 
 
-def _prepare_discovery(graph, start, end, plain, mode, budget, weights, adventurousness):
+def _prepare_discovery(graph, start, end, plain, mode, budget, weights, adventurousness,
+                       posture=None):
     """Corridor → score → shortlist → real travel matrix. Done ONCE per request.
 
     The expensive step is the matrix (cutoff-bounded multi-source Dijkstra), so we
@@ -171,6 +176,10 @@ def _prepare_discovery(graph, start, end, plain, mode, budget, weights, adventur
     if not candidates:
         return None, None, None
     scoring.score_pois(candidates, weights, adventurousness)
+    # Open-now awareness: demote places that are closed right now (heavily for
+    # stop-at categories, mildly for pass-by; unknown hours left untouched).
+    from discoverroute.routing import hours
+    hours.apply_open_now(candidates, posture)
     shortlist = sorted((p for p in candidates if p.score > 0),
                        key=lambda p: p.score, reverse=True)[: config.SOLVER_CANDIDATES]
     if not shortlist:
@@ -190,12 +199,11 @@ def _solve_one(graph, start, end, plain, mode, budget, shortlist, matrix, time_f
         return None, []
     budget_s = (1.0 + budget) * plain.time_s
 
-    # P1-2: Split budget into dwell and detour. Suggest 40% dwell, 60% detour.
-    # This means if you have 10 extra minutes, ~4 min for dwelling, ~6 min for travel.
-    dwell_budget_sec = (budget * plain.time_s * 0.4)
+    # P1-2, single shared pot: a stop's cost = added travel + dwell; a pass-by
+    # costs travel only. The solver enforces everything against budget_s, so the
+    # total trip (walking + lingering) never exceeds (1+budget) × direct.
     posture_dict = posture or {}
 
-    # posture_fn returns dwell time in seconds for a POI.
     def posture_fn(poi):
         from discoverroute.data import taxonomy
         poi_category = getattr(poi, "category", "attraction")
@@ -206,7 +214,6 @@ def _solve_one(graph, start, end, plain, mode, budget, shortlist, matrix, time_f
 
     result = ot.solve(start, end, pool, budget_s, time_fn,
                       max_pois=config.MAX_DETOUR_STOPS,
-                      dwell_budget_s=dwell_budget_sec,
                       posture_fn=posture_fn)
     if not result.ordered_pois:
         return None, []
@@ -216,6 +223,7 @@ def _solve_one(graph, start, end, plain, mode, budget, shortlist, matrix, time_f
         + [matrix.node_for(end)]
     )
     discovery = g.stitch_route(graph, waypoint_nodes, mode, result.ordered_pois)
+    discovery.dwell_s = result.dwell_time_s
     return discovery, result.ordered_pois
 
 
@@ -230,10 +238,12 @@ def _summary(plain: Route, discovery: Route | None, mode: str) -> str:
     line = f"**Plain route** · {plain.distance_m/1000:.2f} km · {plain.time_min:.0f} min"
     if discovery is None:
         return line + f" ({mode})"
-    extra = discovery.time_min - plain.time_min
+    dwell_min = discovery.dwell_s / 60.0
+    extra = discovery.time_min + dwell_min - plain.time_min
+    dwell_note = f" (incl. ~{dwell_min:.0f} min lingering)" if dwell_min >= 1 else ""
     return (
         f"**Discovery route** · {discovery.distance_m/1000:.2f} km · "
-        f"{discovery.time_min:.0f} min · **+{extra:.0f} min** of discovery "
-        f"past {len(discovery.waypoint_pois)} places\n\n"
+        f"{discovery.time_min + dwell_min:.0f} min · **+{extra:.0f} min** of "
+        f"discovery{dwell_note} past {len(discovery.waypoint_pois)} places\n\n"
         f"{line} ({mode}) — shown for comparison"
     )

src/discoverroute/routing/geocode.py

@@ -29,6 +29,8 @@ class _Entry(NamedTuple):
     lon: float
     confidence: float
     n_tags: int
+    display: str       # original POI name, for autocomplete suggestions
+    category: str
 
 
 def _normalize(text: str) -> str:
@@ -72,6 +74,8 @@ def _index() -> tuple[dict[str, _Entry], list[_Entry]]:
             lon=float(row.lon),
             confidence=float(row.confidence),
             n_tags=int(row.n_tags),
+            display=str(row.name),
+            category=str(row.category),
         )
         entries.append(entry)
         best = exact.get(norm)
@@ -109,3 +113,42 @@ def local_geocode(query: str) -> tuple[float, float] | None:
         key=lambda e: (norm in e.norm, e.confidence, e.n_tags, -len(e.norm)),
     )
     return best.lat, best.lon
+
+
+@functools.lru_cache(maxsize=1024)
+def suggest(query: str, limit: int = 8) -> tuple[str, ...]:
+    """Autocomplete: Paris place names matching a partial query, best first.
+
+    Matches treat the last token as a prefix (the user is mid-word). Ranked by
+    (substring match, confidence, tag richness, name brevity); deduplicated by
+    display name. Pure local index — no network. Returns () for short/ambiguous
+    input rather than guessing.
+    """
+    norm = _strip_trailing_geo(_normalize(query or ""))
+    if len(norm) < 3:
+        return ()
+    _, entries = _index()
+    toks = norm.split()
+    head, last = frozenset(toks[:-1]), toks[-1]
+
+    scored: list[tuple[tuple, _Entry]] = []
+    for e in entries:
+        if norm in e.norm:
+            rank = 2  # full query appears verbatim in the name
+        elif head <= e.tokens and any(t.startswith(last) for t in e.tokens):
+            rank = 1  # all complete tokens present, last token a prefix
+        else:
+            continue
+        scored.append(((rank, e.confidence, e.n_tags, -len(e.norm)), e))
+
+    scored.sort(key=lambda t: t[0], reverse=True)
+    out: list[str] = []
+    seen: set[str] = set()
+    for _, e in scored:
+        if e.display in seen:
+            continue
+        seen.add(e.display)
+        out.append(e.display)
+        if len(out) >= limit:
+            break
+    return tuple(out)

src/discoverroute/routing/graph.py

@@ -39,6 +39,7 @@ class Route:
     distance_m: float
     mode: str
     waypoint_pois: list = field(default_factory=list)  # filled by later bricks
+    dwell_s: float = 0.0  # planned lingering time at stops (P1-2)
 
     @property
     def time_s(self) -> float:

src/discoverroute/routing/hours.py

@@ -0,0 +1,171 @@
+"""Conservative OSM ``opening_hours`` evaluation — open / closed / unknown.
+
+The OSM opening-hours grammar is large; this parses only the unambiguous,
+overwhelmingly common patterns and returns ``None`` (unknown) for everything
+else — the app must never demote a place on a misread rule. Handled:
+
+  24/7 · "Mo-Fr 08:00-18:00" · day lists "Mo,We,Fr" · ranges across multiple
+  rules "Tu-Su 09:00-18:00; Mo off" · several time spans "09:00-12:00,14:00-18:00"
+  · plain daily times "10:00-19:00" · overnight spans "18:00-02:00" · "off"/"closed"
+
+Abstained: PH/SH (holidays), sunrise/sunset, months/weeks, "+" open-ends, etc.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+
+PARIS_TZ = ZoneInfo("Europe/Paris")
+
+_DAYS = ["mo", "tu", "we", "th", "fr", "sa", "su"]
+_DAY_RE = r"(?:mo|tu|we|th|fr|sa|su)"
+_TIME_RE = re.compile(r"^\d{1,2}:\d{2}$")
+# tokens that mean "too complex — abstain". PH/SH (public/school holidays) are
+# NOT here: holiday rules are dropped per-rule instead, since the regular-day
+# part of "Mo-Fr 08:00-18:00; PH off" is perfectly decidable.
+_ABSTAIN = re.compile(
+    r"sunrise|sunset|dawn|dusk|week|jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec|easter|\+|\|\|"
+)
+
+
+def _parse_days(spec: str) -> set[int] | None:
+    """'mo-fr' / 'mo,we,fr' / 'tu-su,mo' -> weekday indices, or None if invalid.
+
+    PH/SH tokens inside a list ("PH,Sa,Su 10:00-18:00") are ignored: they extend
+    the rule to holidays, which doesn't change what regular weekdays it covers.
+    """
+    days: set[int] = set()
+    saw_any = False
+    for part in spec.split(","):
+        part = part.strip()
+        if part in ("ph", "sh"):
+            continue
+        m = re.fullmatch(rf"({_DAY_RE})\s*-\s*({_DAY_RE})", part)
+        if m:
+            a, b = _DAYS.index(m.group(1)), _DAYS.index(m.group(2))
+            if a <= b:
+                days.update(range(a, b + 1))
+            else:  # wrapping range, e.g. fr-mo
+                days.update(list(range(a, 7)) + list(range(0, b + 1)))
+            saw_any = True
+            continue
+        if re.fullmatch(_DAY_RE, part):
+            days.add(_DAYS.index(part))
+            saw_any = True
+            continue
+        return None
+    return days if saw_any else set()
+
+
+def _parse_spans(spec: str) -> list[tuple[int, int]] | None:
+    """'09:00-12:00,14:00-18:00' -> [(540,720),(840,1080)] minutes, or None."""
+    spans: list[tuple[int, int]] = []
+    for part in spec.split(","):
+        part = part.strip()
+        m = re.fullmatch(r"(\d{1,2}:\d{2})\s*-\s*(\d{1,2}:\d{2})", part)
+        if not m:
+            return None
+        h1, m1 = map(int, m.group(1).split(":"))
+        h2, m2 = map(int, m.group(2).split(":"))
+        if not (0 <= h1 <= 24 and 0 <= h2 <= 24 and m1 < 60 and m2 < 60):
+            return None
+        spans.append((h1 * 60 + m1, h2 * 60 + m2))
+    return spans
+
+
+def is_open(opening_hours: str | None, when: datetime | None = None) -> bool | None:
+    """True/False if confidently determinable for ``when`` (Paris time); else None."""
+    if not opening_hours or not str(opening_hours).strip():
+        return None
+    text = " ".join(str(opening_hours).lower().split())
+    if text in ("24/7", "24/7;"):
+        return True
+    if _ABSTAIN.search(text):
+        return None
+
+    when = when or datetime.now(PARIS_TZ)
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=PARIS_TZ)
+    weekday = when.weekday()
+    minute = when.hour * 60 + when.minute
+    # for overnight spans we also need "yesterday evening" rules
+    yesterday = (weekday - 1) % 7
+
+    decided: bool | None = None
+    matched_any_rule = False
+    day_head_re = re.compile(rf"^(?:(?:{_DAY_RE}|ph|sh)(?:\s*-\s*(?:{_DAY_RE}|ph|sh))?)"
+                             rf"(?:,(?:{_DAY_RE}|ph|sh)(?:\s*-\s*(?:{_DAY_RE}|ph|sh))?)*$")
+    for rule in text.split(";"):
+        rule = rule.strip()
+        if not rule:
+            continue
+        head, _, tail = rule.partition(" ")
+        if day_head_re.fullmatch(head):
+            day_spec, rest = head, tail.strip()
+        else:
+            day_spec, rest = None, rule
+        days = _parse_days(day_spec.replace(" ", "")) if day_spec else set(range(7))
+        if days is None:
+            return None  # unparseable day spec -> abstain entirely
+        if not days:
+            continue  # holiday-only rule (e.g. "PH off") -> no weekday effect
+
+        if rest in ("off", "closed"):
+            if weekday in days:
+                decided = False
+                matched_any_rule = True
+            continue
+        spans = _parse_spans(rest)
+        if spans is None:
+            return None  # unparseable times -> abstain entirely
+
+        matched_any_rule = True
+        for lo, hi in spans:
+            if hi >= lo:  # same-day span
+                if weekday in days and lo <= minute < hi:
+                    decided = True
+            else:  # overnight span, e.g. 18:00-02:00
+                if weekday in days and minute >= lo:
+                    decided = True
+                if yesterday in days and minute < hi:
+                    decided = True
+
+    if decided is True:
+        return True
+    # only claim "closed" when at least one rule parsed and applies to this place
+    return False if matched_any_rule else None
+
+
+# Demotion factors when a place is closed at plan time: stopping at a closed
+# café is pointless (heavy demotion); passing a closed monument still has
+# exterior value (mild demotion). Unknown hours are left untouched — except for
+# typically-daytime categories late at night, which get a mild realism demotion
+# (a café with unlisted hours is a poor bet at midnight).
+CLOSED_STOP_FACTOR = 0.2
+CLOSED_PASS_FACTOR = 0.7
+NIGHT_UNKNOWN_FACTOR = 0.5
+_NIGHT_START_H, _NIGHT_END_H = 21, 6
+_DAYTIME_CATEGORIES = {
+    "cafe", "bakery_food_shop", "market", "museum_gallery", "library",
+    "bookshop", "specialty_shop",
+}
+
+
+def apply_open_now(pois: list, posture: dict[str, str] | None,
+                   when: datetime | None = None) -> list:
+    """Annotate each POI with ``.open_state`` and demote closed ones in place."""
+    posture = posture or {}
+    when = when or datetime.now(PARIS_TZ)
+    is_night = when.hour >= _NIGHT_START_H or when.hour < _NIGHT_END_H
+    for p in pois:
+        state = is_open(getattr(p, "opening_hours", None), when)
+        p.open_state = state  # True / False / None(unknown)
+        if state is False:
+            factor = (CLOSED_STOP_FACTOR
+                      if posture.get(p.category, "pass") == "stop"
+                      else CLOSED_PASS_FACTOR)
+            p.score *= factor
+        elif state is None and is_night and p.category in _DAYTIME_CATEGORIES:
+            p.score *= NIGHT_UNKNOWN_FACTOR
+    return pois

src/discoverroute/routing/orienteering.py

@@ -53,9 +53,11 @@ def _greedy(start, end, pool, budget_s, time_fn, decay, max_pois, by_ratio, gain
     ``max_pois`` is reached. The floor stops the route padding its remaining budget
     with negligible-value detours.
 
-    P1-2: If ``dwell_budget_s`` and ``posture_fn`` are provided, separately tracks
-    dwell time and detour distance, enforcing both constraints independently.
-    Stops consume dwell_budget; passes consume only travel distance.
+    P1-2 (single shared pot): a stop's full cost is added travel time PLUS its
+    dwell time (from ``posture_fn``); a pass-by costs travel only. Everything is
+    enforced against the one ``budget_s`` cap, so the user-facing promise —
+    total trip ≤ (1+budget) × direct — holds whether time is spent walking or
+    lingering. ``dwell_budget_s`` optionally adds a separate dwell-only cap.
     """
     seq: list[Point] = [start, end]
     selected: list = []
@@ -64,40 +66,36 @@ def _greedy(start, end, pool, budget_s, time_fn, decay, max_pois, by_ratio, gain
     cur_detour_dist = 0.0
 
     while len(selected) < max_pois:
-        best = None  # (key, added, idx, poi)
+        best = None  # (key, added, idx, poi, dwell)
         for p in pool:
             if p in selected:
                 continue
             gain = scoring.marginal_gain(selected, p, decay)
             if gain < gain_floor:
                 continue
+            poi_dwell = posture_fn(p) if posture_fn is not None else 0.0
+            if dwell_budget_s is not None and cur_dwell + poi_dwell > dwell_budget_s:
+                continue
             ppt = (p.lat, p.lon)
             for i in range(1, len(seq)):
                 added = (time_fn(seq[i - 1], ppt) + time_fn(ppt, seq[i])
                          - time_fn(seq[i - 1], seq[i]))
-                if cur_time + added > budget_s:
+                cost = added + poi_dwell  # stops pay travel + dwell, passes travel
+                if cur_time + cost > budget_s:
                     continue
-
-                # P1-2: Check dwell budget if available
-                if dwell_budget_s is not None and posture_fn is not None:
-                    poi_dwell = posture_fn(p)
-                    if cur_dwell + poi_dwell > dwell_budget_s:
-                        continue
-
-                key = gain / max(added, _EPS) if by_ratio else gain
-                # tie-break toward the cheaper detour
-                cand = (key, -added)
+                key = gain / max(cost, _EPS) if by_ratio else gain
+                # tie-break toward the cheaper insertion
+                cand = (key, -cost)
                 if best is None or cand > best[0]:
-                    best = (cand, added, i, p)
+                    best = (cand, added, i, p, poi_dwell)
         if best is None:
             break
-        _, added, idx, poi = best
+        _, added, idx, poi, poi_dwell = best
         seq.insert(idx, (poi.lat, poi.lon))
         selected.insert(idx - 1, poi)
-        cur_time += added
-        if dwell_budget_s is not None and posture_fn is not None:
-            cur_dwell += posture_fn(poi)
-            cur_detour_dist += added
+        cur_time += added + poi_dwell
+        cur_dwell += poi_dwell
+        cur_detour_dist += added
 
     return OrienteeringResult(
         selected, cur_time, scoring.set_reward(selected, decay),

src/discoverroute/routing/pois.py

@@ -35,8 +35,11 @@ class POI:
     quietness: float
     confidence: float
     n_tags: int
+    opening_hours: str | None = None
     # filled by the scorer (Brick 2):
     score: float = 0.0
+    # filled by hours.apply_open_now: True / False / None (unknown)
+    open_state: bool | None = None
 
 
 def _to_metres(lat, lon):
@@ -111,6 +114,8 @@ def corridor_pois(
             quietness=float(r.quietness),
             confidence=float(r.confidence),
             n_tags=int(r.n_tags),
+            opening_hours=(None if pd.isna(getattr(r, "opening_hours", None))
+                           else str(r.opening_hours)),
         )
         for r in sel.itertuples(index=False)
     ]

src/discoverroute/ui/design.py

@@ -60,10 +60,14 @@ DR_CSS = """
   box-shadow:0 18px 44px -20px rgba(43,38,32,.32) !important; background:var(--dr-paper) !important;
 }
 
-/* inputs */
+/* inputs — explicit ink color (theme override otherwise leaves them too pale) */
 .gradio-container input[type=text], .gradio-container textarea{
   border:2px solid var(--dr-line) !important; border-radius:var(--dr-r) !important;
-  background:#FFFEFB !important; transition:border-color .18s, box-shadow .18s !important;
+  background:#FFFEFB !important; color:var(--dr-ink) !important;
+  transition:border-color .18s, box-shadow .18s !important;
+}
+.gradio-container input[type=text]::placeholder, .gradio-container textarea::placeholder{
+  color:#B9AE99 !important; opacity:1;
 }
 .gradio-container input[type=text]:focus, .gradio-container textarea:focus{
   border-color:var(--dr-cobalt) !important; box-shadow:0 0 0 4px rgba(47,93,244,.14) !important;
@@ -84,8 +88,10 @@ DR_CSS = """
 /* mode toggle as a segmented control */
 #dr-mode .wrap{ background:#F0E3CC; padding:5px; border-radius:var(--dr-r); gap:6px; }
 #dr-mode label{ flex:1; justify-content:center; border:none !important;
+  background:transparent !important; color:var(--dr-soft) !important;
   border-radius:13px !important; transition:all .2s var(--dr-spring); }
-#dr-mode label.selected{ background:var(--dr-paper); color:var(--dr-cobalt) !important;
+#dr-mode label span{ color:inherit !important; }
+#dr-mode label.selected{ background:var(--dr-paper) !important; color:var(--dr-cobalt) !important;
   box-shadow:0 4px 12px -4px rgba(43,38,32,.25); transform:translateY(-1px); }
 
 /* springy sliders — per-slider accents (budget coral · adventurousness sun ·
@@ -102,14 +108,18 @@ DR_CSS = """
 #dr-adv input[type=range]::-webkit-slider-thumb{ border-color:var(--dr-sun); }
 #dr-green input[type=range], #dr-quiet input[type=range]{ accent-color:var(--dr-grass); }
 
-/* collapsibles -> dashed taste cards */
+/* collapsibles -> dashed taste cards (labels at full ink for readability) */
 .dr-collapse{ border:1.5px dashed var(--dr-line) !important; border-radius:var(--dr-r) !important;
   background:#FFFDF8 !important; box-shadow:none !important; }
+.dr-collapse .label-wrap span, .dr-collapse button span, .dr-collapse > button{
+  color:var(--dr-ink) !important; opacity:1 !important; }
 
-/* route-options radio -> selectable cards */
+/* route-options radio -> selectable cards (paper bg + ink text, both states) */
 #dr-options .wrap{ display:grid; grid-template-columns:repeat(3,1fr); gap:11px; }
 #dr-options label{ border:2px solid var(--dr-line) !important; border-radius:var(--dr-r) !important;
-  padding:14px !important; transition:all .2s var(--dr-spring); }
+  padding:14px !important; background:var(--dr-paper) !important; color:var(--dr-ink) !important;
+  transition:all .2s var(--dr-spring); }
+#dr-options label span, #dr-options label *{ color:var(--dr-ink) !important; }
 #dr-options label:hover{ transform:translateY(-3px); }
 #dr-options label.selected{ border-color:var(--dr-grass) !important; background:#F1FAF4 !important;
   box-shadow:0 10px 26px -14px rgba(47,164,99,.6) !important; }
@@ -118,7 +128,7 @@ DR_CSS = """
 #dr-map{ border-radius:26px !important; overflow:hidden; border:1px solid var(--dr-line);
   box-shadow:0 18px 44px -20px rgba(43,38,32,.34); position:relative; background:var(--dr-paper); }
 #dr-map::before{ content:'Paris — live map'; display:block; font-family:'Fredoka',sans-serif;
-  font-weight:600; font-size:13.5px; padding:11px 16px 11px 64px;
+  font-weight:600; font-size:13.5px; padding:11px 16px 11px 64px; color:var(--dr-ink);
   border-bottom:1px solid var(--dr-line);
   background-image:radial-gradient(circle at 20px 50%,#FF6A52 5px,transparent 5px),
     radial-gradient(circle at 36px 50%,#FFC247 5px,transparent 5px),
@@ -174,6 +184,13 @@ footer{ visibility:hidden; }
   #dr-map::before{ font-size:12px; background-image:linear-gradient(180deg,#FFF,#FBF4E6); }
 }
 
+/* dark-mode belt-and-suspenders: even if the dark class sticks, keep the
+   design's ink-on-cream readable (the head script also strips the class) */
+.dark .gradio-container, .dark .gradio-container .prose,
+.dark .gradio-container .prose *, .dark .gradio-container label span,
+.dark .gradio-container p, .dark .gradio-container li{
+  color:var(--dr-ink) !important; }
+
 /* respect reduced motion */
 @media (prefers-reduced-motion:reduce){
   .gradio-container *{ animation:none !important; transition:none !important; } }
@@ -182,40 +199,71 @@ footer{ visibility:hidden; }
 """
 
 # ---------------------------------------------------------------- head (§4)
+# Includes the page enhancer as a real <script> — Gradio 6's launch(js=...)
+# proved unreliable, while head= injection always executes.
 DR_HEAD = """
 <link rel='preconnect' href='https://fonts.googleapis.com'>
 <link rel='preconnect' href='https://fonts.gstatic.com' crossorigin>
 <link href='https://fonts.googleapis.com/css2?family=Fredoka:wght@400;500;600;700&family=DM+Sans:wght@400;500;600;700&display=swap' rel='stylesheet'>
+<script>
+(function(){
+  // The clay design is light-only; Gradio applies a `dark` class from the OS
+  // preference, flipping text vars to near-white on our cream cards. Strip it
+  // and keep it stripped.
+  var forceLight = function(){
+    document.documentElement.classList.remove('dark');
+    if (document.body) document.body.classList.remove('dark');
+  };
+  // Transform-only entrance (no opacity: Gradio morphs the DOM mid-animation
+  // and an interrupted opacity animation would freeze content half-faded).
+  var celebrate = function(el){
+    if(!el || el.dataset.shown) return; el.dataset.shown='1';
+    try{ el.animate([{transform:'translateY(14px)'},{transform:'none'}],
+      {duration:480,easing:'cubic-bezier(.34,1.56,.64,1)'}); }catch(e){}
+  };
+  var arm = function(){
+    forceLight();
+    // Debounced via rAF and childList-only: observing class attributes fires on
+    // every Svelte class toggle (constantly) and can livelock a slow renderer.
+    // Dark-class re-adds are covered by the .dark CSS overrides as backstop.
+    var scheduled = false;
+    var tick = function(){
+      scheduled = false;
+      forceLight();
+      ['#dr-summary','#dr-interp','#dr-itin','#dr-options'].forEach(function(s){
+        var el = document.querySelector(s);
+        if (el && el.textContent.trim()) celebrate(el);
+      });
+    };
+    var obs = new MutationObserver(function(){
+      if (!scheduled){ scheduled = true; requestAnimationFrame(tick); }
+    });
+    obs.observe(document.body, {childList:true, subtree:true});
+  };
+  if (document.readyState === 'loading')
+    document.addEventListener('DOMContentLoaded', arm);
+  else arm();
+})();
+</script>
 """
 
 # ---------------------------------------------------------------- js (§4/§6)
 # Outer-page enhancer: bounce results in when they (re)appear. The map's own
 # route-draw / marker-pop animations run INSIDE the folium iframe (ui/map.py
 # injects MAP_ANIMATION_JS there — an iframe can't be reached reliably from here).
-DR_JS = """
-() => {
-  function celebrate(el){
-    if(!el || el.dataset.shown) return; el.dataset.shown='1';
-    el.animate([{opacity:0,transform:'translateY(14px)'},{opacity:1,transform:'none'}],
-      {duration:480,easing:'cubic-bezier(.34,1.56,.64,1)',fill:'forwards'});
-  }
-  const obs = new MutationObserver(()=>{
-    ['#dr-summary','#dr-interp','#dr-itin','#dr-options'].forEach(s=>{
-      const el=document.querySelector(s);
-      if(el && el.textContent.trim()) celebrate(el);
-    });
-  });
-  obs.observe(document.body,{childList:true,subtree:true});
-}
-"""
+# NOTE: the page enhancer (force-light + entrance animation) lives in DR_HEAD as
+# a real <script>; Gradio 6's launch(js=...) silently failed to execute it.
 
-# Map-press bounce the instant Plan is clicked (per-event js).
+# Map-press bounce the instant Plan is clicked (per-event js). NOTE: an event's
+# js function receives the input values and its RETURN VALUE REPLACES them — it
+# must pass the args through unchanged or every input reaches Python as null.
 DR_CELEBRATE = """
-() => {
+(...args) => {
   const map = document.querySelector('#dr-map');
   if (map) map.animate(
     [{transform:'scale(1)'},{transform:'scale(.99)'},{transform:'scale(1)'}],
     {duration:260, easing:'cubic-bezier(.34,1.56,.64,1)'});
+  return args;
 }
 """
 
@@ -336,3 +384,56 @@ NO_DETOUR_HTML = """
 
 # Empty-map overlay message (rendered by ui/map.py inside the map frame).
 EMPTY_STATE_LABEL = "Where shall we wander?"
+
+# ------------------------------------------------------- loading state (§C)
+# Shown in the map slot the instant Plan is clicked (via a .then() chain): a
+# little local mid-stride + bouncing dots, per the kit's loading-state spec.
+LOADING_HTML = """
+<div style="height:520px; display:grid; place-items:center; background:
+     radial-gradient(700px 320px at 50% 0%,#FBEFD6 0%,transparent 70%), #F6ECD9;">
+  <div style="text-align:center;">
+    <svg width="120" height="110" viewBox="0 0 120 110" fill="none" aria-hidden="true"
+         style="animation:drStride .9s ease-in-out infinite alternate;">
+      <ellipse cx="60" cy="98" rx="34" ry="7" fill="#2B2620" opacity=".12"/>
+      <rect x="18" y="88" width="84" height="6" rx="3" fill="#E7DAC0"/>
+      <circle cx="30" cy="91" r="2.5" fill="#FFFCF5"/>
+      <circle cx="60" cy="91" r="2.5" fill="#FFFCF5"/>
+      <circle cx="90" cy="91" r="2.5" fill="#FFFCF5"/>
+      <circle cx="62" cy="28" r="13" fill="#FFC9A3"/>
+      <path d="M50 24 a13 13 0 0 1 24 -3 l-5 2 a 9 9 0 0 0 -14 2z" fill="#8A5A33"/>
+      <rect x="52" y="40" width="20" height="30" rx="9" fill="#2F5DF4"/>
+      <rect x="47" y="44" width="9" height="22" rx="4.5" fill="#2F5DF4"
+            transform="rotate(18 51 55)"/>
+      <rect x="68" y="44" width="9" height="22" rx="4.5" fill="#214AD0"
+            transform="rotate(-26 72 55)"/>
+      <rect x="54" y="66" width="8" height="26" rx="4" fill="#2B2620"
+            transform="rotate(14 58 79)"/>
+      <rect x="62" y="66" width="8" height="26" rx="4" fill="#2B2620"
+            transform="rotate(-22 66 79)"/>
+      <ellipse cx="52" cy="94" rx="7" ry="3.5" fill="#E14D37"/>
+      <ellipse cx="74" cy="90" rx="7" ry="3.5" fill="#E14D37"
+               transform="rotate(-14 74 90)"/>
+      <path d="M88 36 c0,-7 11,-7 11,0 c0,5.5 -5.5,8 -5.5,12.5 c0,-4.5 -5.5,-7 -5.5,-12.5z"
+            fill="#FF6A52"/>
+      <circle cx="93.5" cy="36" r="2.6" fill="#FFFCF5"/>
+    </svg>
+    <div style="font-family:'Fredoka',system-ui,sans-serif; font-weight:600;
+         font-size:19px; color:#2B2620; margin-top:10px;">Scouting your wander…</div>
+    <div style="margin-top:12px; display:flex; gap:8px; justify-content:center;">
+      <span style="width:11px;height:11px;border-radius:50%;background:#FF6A52;
+            animation:drBounce 1s ease-in-out infinite;"></span>
+      <span style="width:11px;height:11px;border-radius:50%;background:#FFC247;
+            animation:drBounce 1s ease-in-out .15s infinite;"></span>
+      <span style="width:11px;height:11px;border-radius:50%;background:#2FA463;
+            animation:drBounce 1s ease-in-out .3s infinite;"></span>
+    </div>
+    <div style="font-family:'DM Sans',system-ui,sans-serif; font-size:13px;
+         color:#6B6256; margin-top:12px;">reading your vibe · scoring 30,000 places · threading the detour</div>
+  </div>
+  <style>
+    @keyframes drBounce { 0%,100% { transform:translateY(0) } 50% { transform:translateY(-9px) } }
+    @keyframes drStride { 0% { transform:translateX(-7px) } 100% { transform:translateX(7px) } }
+    @media (prefers-reduced-motion:reduce){ *{ animation:none !important; } }
+  </style>
+</div>
+"""

src/discoverroute/ui/map.py

@@ -11,12 +11,31 @@ from branca.element import Element
 
 from discoverroute import config
 from discoverroute.routing.graph import Route
-from discoverroute.ui import design
+from discoverroute.ui import design, markers
 
 PLAIN_COLOR = "#2F5DF4"      # cobalt — the plain/fastest route
 DISCOVERY_COLOR = "#2FA463"  # grass — the discovery route
-POI_COLOR = "#FF6A52"        # coral — POI markers
-TILES = "cartodbpositron"
+
+# Warmer, livelier basemap than the pale Positron — CARTO Voyager (keyless).
+_TILE_URL = "https://{s}.basemaps.cartocdn.com/rastertiles/voyager/{z}/{x}/{y}{r}.png"
+_TILE_ATTR = ('&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> '
+              'contributors &copy; <a href="https://carto.com/attributions">CARTO</a>')
+
+# POI marker color by category family (design palette).
+_CATEGORY_COLORS = {
+    # nature & calm — grass
+    "park_garden": "#2FA463", "water_feature": "#2FA463", "viewpoint": "#2FA463",
+    # culture & history — cobalt
+    "monument_historic": "#2F5DF4", "museum_gallery": "#2F5DF4",
+    "place_of_worship": "#2F5DF4", "library": "#2F5DF4", "theatre_cinema": "#2F5DF4",
+    "attraction": "#2F5DF4",
+    # food & drink — sun
+    "cafe": "#E89E1C", "bakery_food_shop": "#E89E1C", "restaurant": "#E89E1C",
+    "bar_pub": "#E89E1C", "market": "#E89E1C",
+    # art & finds — coral
+    "artwork": "#FF6A52", "bookshop": "#FF6A52", "specialty_shop": "#FF6A52",
+}
+_DEFAULT_POI_COLOR = "#FF6A52"
 
 _LEGEND_HTML = """
 <div style="position:absolute; bottom:18px; left:12px; z-index:9999;
@@ -28,10 +47,25 @@ _LEGEND_HTML = """
   <span style="display:inline-block;width:18px;height:4px;border-radius:2px;
         background:#2F5DF4;vertical-align:middle;margin-right:7px;"></span>Fastest route<br>
   <span style="display:inline-block;width:10px;height:10px;border-radius:50%;
-        background:#FF6A52;vertical-align:middle;margin-right:7px;margin-left:4px;"></span>Worth a detour
+        background:#2FA463;vertical-align:middle;margin-right:7px;margin-left:4px;"></span>Green space
+  <span style="display:inline-block;width:10px;height:10px;border-radius:50%;
+        background:#2F5DF4;vertical-align:middle;margin-right:7px;margin-left:10px;"></span>Water &amp; wayfinding<br>
+  <span style="display:inline-block;width:10px;height:10px;border-radius:50%;
+        background:#FF6A52;vertical-align:middle;margin-right:7px;margin-left:4px;"></span>Culture
+  <span style="display:inline-block;width:10px;height:10px;border-radius:50%;
+        background:#E89E1C;vertical-align:middle;margin-right:7px;margin-left:10px;"></span>Cozy stops
 </div>
 """
 
+# Gentle warm grade on the tiles so the basemap sits inside the cream design
+# instead of fighting it (applies inside the folium iframe).
+_TILE_WARMTH_CSS = """
+<style>
+.leaflet-tile-pane{ filter: saturate(1.12) sepia(0.10) brightness(1.02); }
+.leaflet-container{ background:#F6ECD9; }
+</style>
+"""
+
 
 def _fit_bounds(fmap: folium.Map, coords: list[tuple[float, float]]) -> None:
     if not coords:
@@ -50,7 +84,8 @@ def render_routes(
 ) -> str:
     """Render routes + markers and return the map as standalone HTML."""
     center = start or config.PARIS_CENTER
-    fmap = folium.Map(location=list(center), zoom_start=14, tiles=TILES)
+    fmap = folium.Map(location=list(center), zoom_start=14,
+                      tiles=_TILE_URL, attr=_TILE_ATTR)
 
     all_coords: list[tuple[float, float]] = []
 
@@ -75,38 +110,45 @@ def render_routes(
         all_coords.extend(discovery.coords)
 
     if pois:
-        for poi in pois:
+        for i, poi in enumerate(pois):
             name = getattr(poi, "name", None) or getattr(poi, "category", "POI")
-            folium.CircleMarker(
-                location=[poi.lat, poi.lon],
-                radius=7,
-                color="#FFFCF5",
-                weight=2,
-                fill=True,
-                fill_color=POI_COLOR,
-                fill_opacity=1.0,
-                class_name="dr-poi",
-                tooltip=str(name),
-            ).add_to(fmap)
+            cat = getattr(poi, "category", "")
+            icon = markers.poi_icon(cat, index=i)
+            tooltip = f"{name} · {cat.replace('_', ' ')}" if cat else str(name)
+            if icon is not None:
+                folium.Marker([poi.lat, poi.lon], icon=icon,
+                              tooltip=tooltip).add_to(fmap)
+            else:  # icon file missing — fall back to a colored dot
+                folium.CircleMarker(
+                    location=[poi.lat, poi.lon], radius=7, color="#FFFCF5",
+                    weight=2, fill=True, fill_opacity=1.0,
+                    fill_color=_CATEGORY_COLORS.get(cat, _DEFAULT_POI_COLOR),
+                    class_name="dr-poi", tooltip=tooltip,
+                ).add_to(fmap)
 
     if start is not None:
+        icon = markers.endpoint_icon("start")
         folium.Marker(list(start), tooltip="Start",
-                      icon=folium.Icon(color="blue", icon="play")).add_to(fmap)
+                      icon=icon or folium.Icon(color="blue", icon="play")).add_to(fmap)
     if end is not None:
+        icon = markers.endpoint_icon("dest")
         folium.Marker(list(end), tooltip="Destination",
-                      icon=folium.Icon(color="red", icon="flag")).add_to(fmap)
+                      icon=icon or folium.Icon(color="red", icon="flag")).add_to(fmap)
 
     _fit_bounds(fmap, all_coords or [c for c in (start, end) if c])
 
     root = fmap.get_root()
     root.html.add_child(Element(_LEGEND_HTML))
+    root.html.add_child(Element(_TILE_WARMTH_CSS))
+    root.html.add_child(Element(markers.MARKER_CSS))
     root.html.add_child(Element(design.MAP_ANIMATION_JS))
     return fmap._repr_html_()
 
 
 def empty_map(message: str = design.EMPTY_STATE_LABEL) -> str:
     """A blank Paris map with a friendly sticker overlay (empty/error state)."""
-    fmap = folium.Map(location=list(config.PARIS_CENTER), zoom_start=12, tiles=TILES)
+    fmap = folium.Map(location=list(config.PARIS_CENTER), zoom_start=12,
+                      tiles=_TILE_URL, attr=_TILE_ATTR)
     overlay = f"""
     <div style="position:absolute; inset:0; z-index:9999; display:grid; place-items:center;
          pointer-events:none; background:rgba(246,236,217,.45);">
@@ -127,5 +169,6 @@ def empty_map(message: str = design.EMPTY_STATE_LABEL) -> str:
       </div>
     </div>
     """
+    fmap.get_root().html.add_child(Element(_TILE_WARMTH_CSS))
     fmap.get_root().html.add_child(Element(overlay))
     return fmap._repr_html_()

src/discoverroute/ui/markers.py

@@ -0,0 +1,88 @@
+"""Clay-pin map markers — the designed 14-piece marker family.
+
+SVGs live in ``ui/icons/`` (source of truth: the design handoff's
+``icons/markers-spec.md``). Each marker is inlined into a Leaflet ``DivIcon``
+(no extra HTTP requests inside the map iframe), sized per spec with the pin tip
+anchored on the coordinate, plus the spec's cast shadow, springy hover, and
+staggered pop-in — all gated behind ``prefers-reduced-motion``.
+"""
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+
+import folium
+
+_ICON_DIR = Path(__file__).resolve().parent / "icons"
+
+# Our 17 OSM categories -> the 14 designed marker kinds (color-by-meaning:
+# cobalt water/wayfinding · grass green space · coral culture · sun cozy stops).
+CATEGORY_TO_KIND = {
+    "park_garden": "park",
+    "water_feature": "fountain",
+    "viewpoint": "viewpoint",
+    "monument_historic": "museum",
+    "museum_gallery": "museum",
+    "artwork": "star",            # public art = a highlight find
+    "place_of_worship": "museum", # columns glyph reads classical/temple
+    "library": "library",
+    "bookshop": "bookshop",
+    "theatre_cinema": "museum",
+    "cafe": "cafe",
+    "bakery_food_shop": "bakery",
+    "restaurant": "cafe",
+    "bar_pub": "cafe",
+    "market": "market",
+    "specialty_shop": "market",
+    "attraction": "star",
+}
+
+_W = 40                      # marker width px (spec: 28 / 40 / 56)
+_H = round(_W * 84 / 64)     # 52 — height keeps the 64x84 viewBox ratio
+
+
+@functools.lru_cache(maxsize=32)
+def _svg(kind: str) -> str:
+    path = _ICON_DIR / f"marker-{kind}.svg"
+    try:
+        return path.read_text()
+    except OSError:
+        return ""
+
+
+def marker_icon(kind: str, index: int = 0, width: int = _W) -> folium.DivIcon | None:
+    """A DivIcon for one pin; ``index`` staggers the pop-in (~150 ms per spec)."""
+    svg = _svg(kind)
+    if not svg:
+        return None
+    h = round(width * 84 / 64)
+    html = (f'<div class="dr-pin" style="animation-delay:{600 + index * 150}ms;'
+            f'width:{width}px;height:{h}px;">{svg}</div>')
+    return folium.DivIcon(html=html, icon_size=(width, h),
+                          icon_anchor=(width // 2, h), class_name="dr-pin-wrap")
+
+
+def poi_icon(category: str, index: int = 0) -> folium.DivIcon | None:
+    return marker_icon(CATEGORY_TO_KIND.get(category, "star"), index)
+
+
+def endpoint_icon(which: str) -> folium.DivIcon | None:
+    """'start' (cobalt arrow) or 'dest' (coral flag), slightly larger."""
+    return marker_icon(which, index=-2, width=46)
+
+
+# Injected once per map (ui/map.py): shadow + hover spring + pop-in, per spec.
+MARKER_CSS = """
+<style>
+.dr-pin-wrap{ background:transparent; border:none; }
+.dr-pin{ filter: drop-shadow(0 6px 5px rgba(43,38,32,.28));
+  transition: transform .25s cubic-bezier(.34,1.56,.64,1);
+  transform-origin: 50% 100%;
+  animation: drPinPop .55s cubic-bezier(.34,1.56,.64,1) backwards; }
+.dr-pin svg{ width:100%; height:100%; display:block; }
+.dr-pin:hover{ transform: translateY(-8px) scale(1.05); }
+@keyframes drPinPop{ 0%{ transform:scale(.3); } 60%{ transform:scale(1.12); }
+  100%{ transform:scale(1); } }
+@media (prefers-reduced-motion: reduce){ .dr-pin{ animation:none; } }
+</style>
+"""

tests/test_geocode.py

@@ -1,123 +1,33 @@
-"""Offline geocoding tests: local POI-name index + offline-mode behaviour.
-
-Real names are picked from the parquet at test time (never hardcoded guesses),
-except the app's two default inputs, which must resolve locally by contract.
-"""
+"""Offline geocoder + autocomplete suggestions (local POI-name index)."""
 from __future__ import annotations
 
-import math
-
-import pandas as pd
 import pytest
 
 from discoverroute import config
-from discoverroute.routing import geocode as gc
-from discoverroute.routing.graph import RouteError, geocode_point
 
-pytestmark = pytest.mark.skipif(
-    not config.POIS_PATH.exists(),
-    reason="POI table not built (run: python -m discoverroute.data.build_pois)",
+pois_available = pytest.mark.skipif(
+    not config.POIS_PATH.exists(), reason="POI table not built"
 )
 
-# Known coordinates of the app's two default inputs.
-REPUBLIQUE = (48.8674, 2.3636)
-LUXEMBOURG = (48.8462, 2.3372)
-
-GIBBERISH = "zzqx flurbington nonexistovia 9999"
-
-
-def _named_pois() -> pd.DataFrame:
-    from discoverroute.routing.pois import load_pois
-
-    df = load_pois()
-    return df[df["name"].notna()]
-
-
-def _pick_name(require_accent: bool = False) -> str:
-    """A real, distinctive POI name from the table (best-documented first)."""
-    df = _named_pois().sort_values(["confidence", "n_tags"], ascending=False)
-    for name in df["name"]:
-        norm = gc._normalize(name)
-        tokens = norm.split()
-        if len(tokens) < 2 or not any(len(t) >= 4 for t in tokens):
-            continue  # too short/ambiguous to be a fair test query
-        if tokens[-1] in ("paris", "france"):
-            continue  # would interact with suffix stripping; pick another
-        if require_accent and all(ord(c) < 128 for c in name):
-            continue
-        return name
-    pytest.skip("no suitable POI name found in the table")
-
-
-def _coords_for_name(name: str) -> set[tuple[float, float]]:
-    """All (lat, lon) rows whose normalised name equals the query's."""
-    df = _named_pois()
-    norm = gc._normalize(name)
-    mask = df["name"].map(lambda n: gc._normalize(n) == norm)
-    return {(float(r.lat), float(r.lon)) for r in df[mask].itertuples()}
-
 
-def _dist_m(a: tuple[float, float], b: tuple[float, float]) -> float:
-    dlat = (a[0] - b[0]) * 110_540.0
-    dlon = (a[1] - b[1]) * 111_320.0 * math.cos(math.radians(a[0]))
-    return math.hypot(dlat, dlon)
+@pois_available
+def test_suggest_finds_landmarks():
+    from discoverroute.routing.geocode import suggest
+    assert "Jardin du Luxembourg" in suggest("jardin du lux")
+    assert any("Eiffel" in s for s in suggest("eiffel"))
 
 
-def test_exact_name_match():
-    name = _pick_name()
-    result = gc.local_geocode(name)
-    assert result is not None
-    assert result in _coords_for_name(name)
+@pois_available
+def test_suggest_abstains_on_noise():
+    from discoverroute.routing.geocode import suggest
+    assert suggest("xq") == ()
+    assert suggest("") == ()
 
 
-def test_accent_and_case_insensitive():
-    name = _pick_name(require_accent=True)
-    expected = gc.local_geocode(name)
-    assert expected is not None
-    # Uppercased and accent-stripped versions of the same name still resolve.
-    assert gc.local_geocode(name.upper()) == expected
-    assert gc.local_geocode(gc._normalize(name)) == expected
-
-
-def test_paris_suffix_stripped():
-    name = _pick_name()
-    expected = gc.local_geocode(name)
-    assert expected is not None
-    assert gc.local_geocode(f"{name}, Paris") == expected
-    assert gc.local_geocode(f"{name} Paris") == expected
-    assert gc.local_geocode(f"{name}, Paris, France") == expected
-
-
-def test_no_match_returns_none():
-    assert gc.local_geocode(GIBBERISH) is None
-    assert gc.local_geocode("") is None
-    assert gc.local_geocode("de la") is None  # short fragments: too ambiguous
-
-
-def test_offline_mode_raises_for_unmatchable(monkeypatch):
-    monkeypatch.setenv(config.OFFLINE_ENV_VAR, "1")
-    with pytest.raises(RouteError, match="offline"):
-        geocode_point(GIBBERISH)
-
-
-def test_latlon_path_unaffected_offline(monkeypatch):
-    monkeypatch.setenv(config.OFFLINE_ENV_VAR, "1")
-    assert geocode_point("48.8674, 2.3636") == (48.8674, 2.3636)
-
-
-@pytest.mark.parametrize(
-    "query,known",
-    [
-        ("Place de la République, Paris", REPUBLIQUE),
-        ("Jardin du Luxembourg, Paris", LUXEMBOURG),
-    ],
-)
-def test_app_defaults_resolve_locally(query, known, monkeypatch):
-    # Pure offline path: must work with the Nominatim fallback disabled.
-    monkeypatch.setenv(config.OFFLINE_ENV_VAR, "1")
-    local = gc.local_geocode(query)
-    assert local is not None, f"default input {query!r} not in local index"
-    assert config.in_paris(*local)
-    assert _dist_m(local, known) < 1500, f"{query!r} resolved far away: {local}"
-    # And the full geocode_point pipeline (bounds check included) agrees.
-    assert geocode_point(query) == local
+@pois_available
+def test_suggestion_round_trips_to_geocode():
+    """Every suggestion must be resolvable by the local geocoder (in Paris)."""
+    from discoverroute.routing.geocode import local_geocode, suggest
+    for name in suggest("jardin du lux")[:3]:
+        pt = local_geocode(name)
+        assert pt is not None and config.in_paris(*pt)

tests/test_hours.py

@@ -0,0 +1,98 @@
+"""Open-now awareness: OSM opening_hours parsing + plan-time demotion."""
+from __future__ import annotations
+
+from datetime import datetime
+
+from discoverroute.routing.hours import (PARIS_TZ, apply_open_now, is_open)
+
+TUE_15H = datetime(2026, 6, 9, 15, 0, tzinfo=PARIS_TZ)   # Tuesday 15:00
+TUE_23H = datetime(2026, 6, 9, 23, 30, tzinfo=PARIS_TZ)  # Tuesday 23:30
+MON_15H = datetime(2026, 6, 8, 15, 0, tzinfo=PARIS_TZ)   # Monday 15:00
+WED_01H = datetime(2026, 6, 10, 1, 0, tzinfo=PARIS_TZ)   # Wednesday 01:00
+
+
+def test_always_open():
+    assert is_open("24/7", TUE_15H) is True
+
+
+def test_simple_weekday_range():
+    assert is_open("Mo-Fr 08:00-18:00", TUE_15H) is True
+    assert is_open("Mo-Fr 08:00-18:00", TUE_23H) is False
+
+
+def test_multi_rule_with_off_day():
+    spec = "Tu-Su 10:00-18:00; Mo off"
+    assert is_open(spec, TUE_15H) is True
+    assert is_open(spec, MON_15H) is False
+
+
+def test_lunch_split_spans():
+    spec = "Mo-Fr 09:00-12:00,14:00-18:00"
+    assert is_open(spec, TUE_15H) is True
+    assert is_open(spec, datetime(2026, 6, 9, 13, 0, tzinfo=PARIS_TZ)) is False
+
+
+def test_daily_no_days():
+    assert is_open("07:00-23:30", TUE_15H) is True
+
+
+def test_overnight_span():
+    spec = "Tu 18:00-02:00"
+    assert is_open(spec, TUE_23H) is True
+    assert is_open(spec, WED_01H) is True   # spills past midnight into Wednesday
+    assert is_open(spec, TUE_15H) is False
+
+
+def test_abstains_on_complex():
+    assert is_open("sunrise-sunset", TUE_15H) is None
+    assert is_open("Mar-Oct 08:00-20:00", TUE_15H) is None
+    assert is_open(None, TUE_15H) is None
+    assert is_open("", TUE_15H) is None
+
+
+class P:
+    def __init__(self, category, hours, score=1.0):
+        self.category, self.opening_hours, self.score = category, hours, score
+
+
+def test_demotion_by_posture():
+    closed_cafe = P("cafe", "Mo-Fr 08:00-12:00")        # closed Tue 15:00
+    closed_monument = P("monument_historic", "Mo-Fr 08:00-12:00")
+    open_cafe = P("cafe", "Mo-Fr 08:00-18:00")
+    unknown = P("cafe", None)
+    posture = {"cafe": "stop", "monument_historic": "pass"}
+    apply_open_now([closed_cafe, closed_monument, open_cafe, unknown],
+                   posture, when=TUE_15H)
+    assert closed_cafe.score == 0.2          # stop-at closed -> heavy demotion
+    assert closed_monument.score == 0.7      # pass-by closed -> mild demotion
+    assert open_cafe.score == 1.0 and open_cafe.open_state is True
+    assert unknown.score == 1.0 and unknown.open_state is None
+
+
+def test_google_verify_noop_without_key(monkeypatch):
+    """Without GOOGLE_MAPS_API_KEY the enrichment must be a silent no-op."""
+    monkeypatch.delenv("GOOGLE_MAPS_API_KEY", raising=False)
+    from discoverroute.enrich import google_places
+    p = P("cafe", None)
+    assert google_places.verify_stops([p]) is False
+    assert not hasattr(p, "live_status")
+
+
+def test_holiday_rules_dont_block_weekday_decisions():
+    # "PH off" must not force abstention on a decidable weekday
+    assert is_open("Mo-Fr 08:00-18:00; PH off", TUE_15H) is True
+    assert is_open("Mo-Fr 08:00-18:00; PH off", TUE_23H) is False
+    # PH inside a day list extends to holidays; weekdays still decidable
+    assert is_open("PH,Sa,Su 10:00-18:00; Mo-Fr 08:30-17:00", TUE_15H) is True
+
+
+def test_night_demotes_unknown_daytime_categories():
+    night = datetime(2026, 6, 9, 23, 30, tzinfo=PARIS_TZ)
+    day = datetime(2026, 6, 9, 15, 0, tzinfo=PARIS_TZ)
+    cafe_n, bar_n = P("cafe", None), P("bar_pub", None)
+    apply_open_now([cafe_n, bar_n], {}, when=night)
+    assert cafe_n.score == 0.5     # unknown café at 23:30 -> poor bet
+    assert bar_n.score == 1.0      # unknown bar at night -> plausible
+    cafe_d = P("cafe", None)
+    apply_open_now([cafe_d], {}, when=day)
+    assert cafe_d.score == 1.0     # daytime unknown untouched

tests/test_interpret.py

@@ -53,18 +53,29 @@ def test_budget_and_posture_hints():
 
 @data_ready
 def test_vibe_changes_route_categories():
-    """Same A/B, contrasting vibes -> measurably different waypoint mixes (P0-5)."""
-    from collections import Counter
+    """Same A/B, contrasting vibes -> each route serves ITS OWN vibe best (P0-5).
+
+    Property-based rather than exact category counts (which are brittle across
+    embedder backends): scoring each route's categories under a vibe's affinity,
+    the route planned FOR that vibe must fit it at least as well as the route
+    planned for the contrasting vibe.
+    """
+    from discoverroute.interpret.embed import vibe_to_affinity
     from discoverroute.pipeline import plan_route
 
     a = "Place de la République, Paris"
     b = "Jardin du Luxembourg, Paris"
-    green = plan_route(a, b, budget=0.7, vibe="quiet green park wander")
-    lively = plan_route(a, b, budget=0.7, vibe="lively bar and café crawl")
+    v_green, v_lively = "quiet green park wander", "lively bar and café crawl"
+    green = plan_route(a, b, budget=0.7, vibe=v_green)
+    lively = plan_route(a, b, budget=0.7, vibe=v_lively)
+    assert green.pois and lively.pois
 
-    gc = Counter(p.category for p in green.pois)
-    lc = Counter(p.category for p in lively.pois)
     # the two routes should not select an identical set of waypoints
     assert {p.osm_id for p in green.pois} != {p.osm_id for p in lively.pois}
-    # lively should pull in more bars/restaurants than the green wander
-    assert lc["bar_pub"] + lc["restaurant"] >= gc["bar_pub"] + gc["restaurant"]
+
+    def fit(route, affinity):  # mean affinity of the route's categories
+        return sum(affinity.get(p.category, 0.0) for p in route.pois) / len(route.pois)
+
+    aff_green, aff_lively = vibe_to_affinity(v_green), vibe_to_affinity(v_lively)
+    assert fit(green, aff_green) >= fit(lively, aff_green)
+    assert fit(lively, aff_lively) >= fit(green, aff_lively)

tests/test_pipeline.py

@@ -45,7 +45,10 @@ def test_discovery_respects_budget_and_detours():
 
 @data_ready
 def test_out_of_bounds_clean_error():
-    r = plan_route("London", DEST, budget=0.5)
+    # Explicit London coordinates: deterministically outside the Paris bbox.
+    # (A *name* like "London" may legitimately resolve to a Paris venue with
+    # that name via the offline POI-name geocoder.)
+    r = plan_route("51.5074, -0.1278", DEST, budget=0.5)
     assert r.error is not None
     assert r.discovery is None and r.plain is None