Repository navigation
Description
Status: approved
TL;DR
Goal: The web route planner shows less text, its controls look like controls, the night picker follows the rider's choice of where to sleep, and route alternatives no longer exist in the web planner, the iOS app or the route server.
Problem: The owner used the planner for a multi-day trip and listed twelve faults. The review page shows each one, the planner as it is, and the chosen fix: https://claude.ai/artifact/2u9BKtTCAwYo7wi69jsfvr
Decision: For each fault, the option that the owner chose on the review page. The sub-issues below hold them.
Rejected:
- A tinted pill with a border for the search chips: it stays a different shape from the other controls of the planner.
- Map symbols only for the access notes, or no notes: a rider must see a private road or a permit before the ride.
- The trip settings stay in the elevation drawer: they are settings of the trip, not of the elevation.
- A search field that stops at 80 characters: a pasted address can be longer. A longer text already uses ordinary place search.
- To delete "Compare versions" as well: that screen compares two saved plans and shares no code with alternatives, so it stays.
- A new answer shape
{"route": …}for the route API: with therouteslist kept, the web planner can deploy before the route service and no request fails between the two deployments.
Systems: route-planning, routing, search
Contracts:specs/route-api.md,specs/vectors/route-answer.json, andplanner/search/query/contract.json(made fromplanner/search/query/schema.py). The guidedocs/content/software/trips.mdchanges too.
Size: L (a breaking change of the route API; more than 1,500 changed lines; three systems)
This epic removes the route comparison that step 1 of #2711 added (#2709 for the web, #2710 for iOS). "Compare versions" of #2711 stays.
Words
- Night picker: the list that opens under a night of a multi-day trip. It shows the towns where the rider can sleep.
- Stop: one town of that list, with its places to sleep (
Stopinbuilder/web/src/lib/planner/stops.ts). - Stay kind: one of the five kinds of place to sleep:
camp,hut,hostel,hotel,shelter(Stayinbuilder/web/src/lib/planner/editor.ts). The rider chooses them for the trip ("Sleep in") and can choose others for one night. - Drawer: the panel below the map that holds the elevation profile (
PlannerProfile.svelte). - Day list: the list of riding days and nights in the side panel (
Itinerary.svelte). A rest day is a day without riding between two riding days. - Pinned night: a night that the rider fixed at a place. A suggested night is one that the planner proposes. The even end is where a day ends when the planner only divides the riding time evenly.
- Visit, shaping point: a visit is a point of the route with a name, where the rider wants to go. A shaping point has no name and only bends the route.
autoLabel: a flag of a route point (RoutePointineditor.ts). It says that the planner made the label and may replace it.- Access note: a stretch of the route where OpenStreetMap says that the rider may have no access, such as a private road (
RouteClosureinrouting.ts). The kindsidepathmeans that the road has a signed cycle path beside it. - Gap: a point that the route does not reach, because no road with access is near it. An alpine stretch is a part of a hiking route on a path of grade T4 or harder.
- Preset: the routing preference of a plan, such as "Balanced" or "Less climbing". Signed routes are official cycling and hiking routes that the rider can load as a plan.
obc: the task runner of this repository;AGENTS.mdexplains it. The Systems come from the map indocs/design/README.md.AGENTS.mddefines theRequirements:line of a pull request.- Review page: the page linked in the TL;DR. It numbers the faults 01 to 12. Each sub-issue states its decision in words, so the page is not needed to build.
Facts
- The route server computes at most two alternatives:
less_climbingandcorridor. A corridor needs a request with exactly two points (planner/router/src/alternatives.rs). So a trip with nights or stops gets no corridor. - The route service rejects unknown request fields (
specs/route-api.md). The web planner sendsalternatives: falseon every request (builder/web/src/lib/planner/routing.ts). - A hovered map marker sets the class
hoveredon its result row (PlannerMap.svelte,QueryResults.svelte), but no code scrolls the row into view. - The iOS app sends
alternatives: falseon its normal route requests (companion-ios/Packages/OBCKit/Sources/OBCPlanner/PlannerService.swift). - The night picker asks the search for
what: ['sleep']and lists every stop (builder/web/src/lib/planner/night-stops.svelte.ts,StopPicker.svelte). Only the automatic suggestion uses the stay kinds (suitsinstops.ts). - "Choose" fits the map to the whole stretch of route that was searched for the night, plus 2 % of the route on each side (
showNightAreainPlannerApp.svelte). - The web client maps the place kind
caravan_siteto the stay kindcamp(stayKindsinbuilder/web/src/lib/planner/search/presentation.ts). The search service does the same: the query kindcampsitefinds the data kindscampsiteandcaravan_site(DATA_KINDSinplanner/search/query/schema.py). The search index does not keep the OpenStreetMap tagtents: the tag filter ofhost/obc-search-bake/src/features.rskeeps a fixed list of tags, andtentsandshelter_typeare not in it. - The
+button of the day list has nopaddingrule, so the browser's default padding moves its icon out of the centre (.plusinItinerary.svelte). - Two lookups for the nearest town exist:
placeNameinPlannerMap.sveltereads the loaded map tiles within 5 km, andtownNameinbuilder/web/src/lib/planner/point-names.tsasks the search within 3 km. - A search text of more than 80 characters already runs as an ordinary place search (
planner/search/query.mjs).
Plan
Each sub-issue is one pull request into the branch planner-ux, cut from develop. The owner reviews the running planner from planner-ux against the review page. Then planner-ux merges into develop.
Order: #3287 goes first, because it removes the most lines from PlannerApp.svelte, which #3288 to #3293 also change. Then #3288, #3289 and #3290 in parallel. Then #3291 and #3292 in parallel. Then #3293. #3294 follows #3290 and touches no file of the others.
- Delete route alternatives from the web planner, the iOS app, the route server and the route API #3287 Delete route alternatives from the web planner, the iOS app, the route server and the route API
- Planner search panel: control-style chips, results with a distance column and day groups, hover that scrolls #3288 Search panel: control-style chips, results with a distance column and day groups, hover that scrolls, no region block
- Planner route notes: one row that opens a list #3289 Route notes: one row that opens a list
- Planner night picker: a panel with a close button, the stay kinds as a filter, a calm map #3290 Night picker: a panel with a close button, the stay kinds as a filter, a calm map
- Planner: trip settings at the top of the day list, a one-row elevation drawer, a centred plus button #3291 Trip settings at the top of the day list, a one-row elevation drawer, a centred plus button
- Planner: name the start and the finish after the nearest town #3292 Name the start and the finish after the nearest town
- Planner: cut the remaining instruction sentences and fix three small faults #3293 Cut the remaining instruction sentences and fix three small faults
- Search index: keep the tents tag and check the shelter filter #3294 Search index: keep the
tentstag and check the shelter filter
Round 2, from the owner's browser check of planner-ux (wireframe page with the owner's picks: https://claude.ai/artifact/HibXoqwkvZM9jHwdae1Ka7). #3370, #3371 and #3368 run in parallel; #3372 follows #3371; #3369 touches only the route build.
- Planner route notes: one row for neighbouring stretches #3368 Route notes: one row for neighbouring stretches
- Routing: a road for traffic to a destination is an open road #3369 Routing: a road for traffic to a destination is an open road
- Planner: the totals leave the side panel (two variants to compare) #3370 The totals leave the side panel (two variants to compare, the owner picks one)
- Planner: a night and a town open as pages #3371 A night and a town open as pages
- Planner town card: select a place, one button confirms #3372 Town card: select a place, one button confirms
Shared look
#3288 adds one global style class, .planner-chip, beside .planner-action in PlannerApp.svelte. #3288 and #3291 use it. Its values: display: inline-flex, gap: 7px, min-height: 32px, padding: 0 9px 0 10px, border: 1px solid var(--line-strong), border-radius: 6px, background: var(--panel), font: 600 13px var(--sans), color: var(--ink). The first icon takes var(--chip-ink, var(--ink-soft)). On hover: background: var(--parchment-2) and border-color: var(--ink-faint). With aria-expanded="true": border-color: var(--ink).
Build state
Last update: 2026-11-19. Done. #3662 merged develop into planner-ux a third time, and #3338 merged planner-ux into develop (981ccd794). #3369 and the search changes take effect with the next builds of the routing data (PLANNER_ROUTING at revision 22) and the search index.
| Sub-issue | Pull request | State | Next step |
|---|---|---|---|
| #3287 delete alternatives | #3313 | Merged into planner-ux, issue closed |
none |
| #3289 route notes | #3314 | Merged into planner-ux (6c3304c85), issue closed |
none |
| #3288 search panel | #3316 | Merged into planner-ux (509e99a10), issue closed |
none |
| #3290 night picker | #3317 | Merged into planner-ux (213bfa508), issue closed |
none |
| #3292 start and finish names | #3327 | Merged into planner-ux (427c067c9), issue closed |
none |
| #3291 trip settings, drawer, plus button | #3329 | Merged into planner-ux (af46b30e4), issue closed |
none |
| #3294 search index and caravan category | #3328, #3331 | Merged into planner-ux, issue closed. It takes effect with the next build of the search index (PLANNER_SEARCH is at revision 3). #3331 (2383460ab) is the owner's follow-up: a shelter with a shelter_type of OTHER_SHELTERS (bus, field, smoking, changing rooms, parking, wildlife hide) gets no record |
none |
| #3293 text cuts | #3330 | Merged into planner-ux (06b8ceab2), issue closed |
none |
How the build runs
- One Opus builder for each sub-issue, in its own worktree
/media/timo/OSM1/tmp/planner-ux/b<issue>on a branchclaude/planner-ux-<issue>-<slug>cut fromorigin/planner-ux. Then one fresh Opus reviewer attacks the diff. The builder fixes the real findings, and the same reviewer checks a large fix again. The orchestrating session routes the findings, looks at the result itself and merges withgh pr merge <PR> --mergewhen CI is green. The owner allowed a Fable agent for a very hard piece; none was needed so far. - The briefs for the builder and the reviewer are in
/media/timo/OSM1/tmp/planner-ux/briefs.md. The source of the approved mock-up is/media/timo/OSM1/tmp/planner-ux/mockup/planner-ux-review.html. The review diffs are in/media/timo/OSM1/tmp/planner-ux/review/. - The base of each pull request is
planner-ux, notdevelop. So GitHub does not close the sub-issue at the merge: setStatus: donein its body, close it by hand and tick its line in the Plan above. - The machine is a shared PC with little free memory. Each agent runs one heavy command at a time. At most three builders run together. There is no Swift toolchain: CI compiles and tests iOS, and its two app builds take 10 to 20 minutes.
- planner: route notes in one row that opens a list (#3289) #3314, planner: search panel chips, results list and hover (#3288) #3316 and planner: night picker panel, stay kinds filter, calm map (#3290) #3317 all change
PlannerApp.svelte. After one of them merges, the others mergeorigin/planner-uxinto their branch and run their checks again.
What the pull requests changed that later sub-issues must know
- planner: delete route alternatives (#3287) #3313 (merged):
requestRoutereturns one route.EngineRoute.id,RoutingLine.primaryandRoutingLine.unpavedKmare gone. The side panel has noliststate. - planner: route notes in one row that opens a list (#3289) #3314:
RouteNotes.svelte;lib/planner/route-notes.tsholds theRouteNotetype,noteKeyand the merge and sort of the three kinds;closureLabel,gapLabelandalpineLabelreplace the old note functions; the iconlockexists. - planner: search panel chips, results list and hover (#3288) #3316: the global class
.planner-chipexists inPlannerApp.svelte(it shares its common rules with.planner-action).PlaceRowtakes a requireddistanceandshowKind;wrapDetailis gone.QueryResultstakesdaysandtheme, and shows "on route" under 50 m.PlannerQueryhas no region block; the test route button shows only in a development build. The position of the rider is stored as{ coordinate, at }, andsearchContext.heregives it only for five minutes.locatereturns the coordinate,'denied'or'unavailable'and writes no status message. A search answer can carrycode: 'location'. - planner: night picker panel, stay kinds filter, calm map (#3290) #3317:
suitable,stayNounsandstopKminstops.ts;StopPickerlists only stops that suit the kinds of the night; the stay kinds and "Pick on the map" share one footer row, which is where Planner: trip settings at the top of the day list, a one-row elevation drawer, a centred plus button #3291 puts itsStayChip. "Cancel" stays in the picker inside an open day, which has no close button.NightNodehas the.night-paneland titles on its two step buttons.nightViewis inlib/planner/view-change.ts,showNightinPlannerMap.svelte.StopCardgroups its places by stay kind. Caravan sites left the query kindscampsiteandsleep. - planner: name the start and the finish after the nearest town #3327:
setEndpointwithout a label gives the pointautoLabel: trueand the placeholder "Start" or "Finish" (endpointLabel(kind)ineditor.ts).session.autoName(id, coordinate, label)writes a found name with no Undo step.nameEndpointinPlannerApp.sveltenames only an endpoint that still has its placeholder.removeRoutePointclearsautoLabelon a promoted point that keeps a name of its own. The test map stub exportstiles.placeNamefor a spy. - planner: trip settings at the top of the day list, a one-row drawer, a centred plus #3329:
StayChip.svelte(a.planner-chipthat opens a list of checkboxes in the flow; propsvalue,label,onChange,onReset,resetLabel) is inTripRowand in the footer row ofStopPicker.PlannerApp.svelterenders<TripRow>aboveItinerarywhile no day is open, with the saved trip and not the copy with the suggested nights.PlannerProfilehas notrip, noonTrip, no day labels and no distance number.DayRowhas onetitle("Day 2 · Sun 20") for the closed row and the open day.stayIconinsearch/presentation.tsreplaces theiconfield ofstayOptions.Itineraryhas no hint paragraph. - search: no caravan sites and no camp sites without tents in the index #3328:
has_poiinplanner/search/records.pyis the one spot that keeps a place out of the search index and the place tiles; it drops a caravan site and a camp site withtents=no. The bake keeps the tagstentsandshelter_type. The groupcampofplace-kinds.jsonholds onlycampsite, and no client has a label forcaravan_site. The device map format and the GPX symbol table keep their caravan entries. - So two of the three small faults of Planner: cut the remaining instruction sentences and fix three small faults #3293 are already fixed: "on route" (planner: search panel chips, results list and hover (#3288) #3316) and the titles of the step buttons (planner: night picker panel, stay kinds filter, calm map (#3290) #3317). Planner: cut the remaining instruction sentences and fix three small faults #3293 keeps the day line and the text cuts.
The merge of develop (#3332, merged)
develop got #3324 (route request classes, the 422 limit error, the busy error, the memory release) while the epic ran. It was written with alternatives. The merge keeps all of #3324 except what served only alternatives: alternatives.rs with the corridor probe radius stays deleted, and the gate of the route service counts only a shape request as heavy (gate.enter(call == "shape") in planner/service/src/http.rs). A plain route was a light call on develop too.
Owner decisions during the build
- Requirements. The planner has no requirements in the verification console yet, and gets none for now. Every pull request of this epic has
Requirements: none. No check against the console is needed. - Caravan sites. They go completely: the planner shows them nowhere, not on the map, not in a search, not by name. The same holds for a camp site that takes no tents. A place where a rider cannot pitch a tent is of no use for cycling or hiking. Search index: keep the tents tag and check the shelter filter #3294 does this.
- Other shelters. A bus shelter, a smoking shelter, a parking shelter and the like leave the search index too (search: no record for bus, smoking and other shelters that give a rider no shelter #3331).
- Test route button. The button "Load Black Forest test route" goes completely, with its handler and the GPX file that the production build shipped for it (planner: delete the Black Forest test route button #3335).
- Browser check. The owner does it in the new session. So the session serves the planner from
planner-uxfor the owner early, after the first merges, and again after the last one.
To know before the merge into develop
- iOS. Every route request of an iOS build from before planner: delete route alternatives (#3287) #3313 fails against the new route service. Deploy in this order: web planner, new iOS build, route service.
- Route start. A typed request without a start ("route to Freiburg") starts at the position of the rider only while that position is less than five minutes old, else at the start of the plan.
- Wording. An access note for a group reads "Only for …" (planner: route notes in one row that opens a list (#3289) #3314), not "Access for … only".
After the last sub-issue
- Serve the planner from
planner-uxfor the owner, with a short list of what to look at for each finding. The owner checks it in the browser. Send back for a fix what the owner does not accept. - Open the pull request
planner-uxintodevelop, withRequirements: none. It merges only with the owner's word. - Deploy in the order web planner, new iOS build, route service. The caravan sites leave the map and the search index only with the next index build.
- Set
Status: doneon this epic, close it, and add a note to EPIC — Route planner review: compare, alternatives, overnights, editing, offline (web + iOS) #2711 that its step 1 was removed.
Done when
- Every sub-issue is merged into
planner-uxand its own checks pass. obc test affected --base origin/developpasses onplanner-ux.- The owner checks the running planner of
planner-uxin the browser and approves it. - Each pull request has the line
Requirements: none: the planner has no requirements in the verification console yet.
Generated by Claude Code
Activity
Merge remote-tracking branch 'origin/develop' into claude/planner-ux-…
Merge pull request #3338 from timohueser/planner-ux