Skip to content

EPIC — Planner UX: less text, clear controls, nights that follow the stay kinds, no route alternatives #3286

Closed
13 of 13 issues completed

Description

@timohueser

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 the routes list 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, and planner/search/query/contract.json (made from planner/search/query/schema.py). The guide docs/content/software/trips.md changes 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 (Stop in builder/web/src/lib/planner/stops.ts).
  • Stay kind: one of the five kinds of place to sleep: camp, hut, hostel, hotel, shelter (Stay in builder/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 (RoutePoint in editor.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 (RouteClosure in routing.ts). The kind sidepath means 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.md explains it. The Systems come from the map in docs/design/README.md. AGENTS.md defines the Requirements: 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_climbing and corridor. 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 sends alternatives: false on every request (builder/web/src/lib/planner/routing.ts).
  • A hovered map marker sets the class hovered on its result row (PlannerMap.svelte, QueryResults.svelte), but no code scrolls the row into view.
  • The iOS app sends alternatives: false on 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 (suits in stops.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 (showNightArea in PlannerApp.svelte).
  • The web client maps the place kind caravan_site to the stay kind camp (stayKinds in builder/web/src/lib/planner/search/presentation.ts). The search service does the same: the query kind campsite finds the data kinds campsite and caravan_site (DATA_KINDS in planner/search/query/schema.py). The search index does not keep the OpenStreetMap tag tents: the tag filter of host/obc-search-bake/src/features.rs keeps a fixed list of tags, and tents and shelter_type are not in it.
  • The + button of the day list has no padding rule, so the browser's default padding moves its icon out of the centre (.plus in Itinerary.svelte).
  • Two lookups for the nearest town exist: placeName in PlannerMap.svelte reads the loaded map tiles within 5 km, and townName in builder/web/src/lib/planner/point-names.ts asks 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.

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.

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 branch claude/planner-ux-<issue>-<slug> cut from origin/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 with gh pr merge <PR> --merge when 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, not develop. So GitHub does not close the sub-issue at the merge: set Status: done in 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 merge origin/planner-ux into their branch and run their checks again.

What the pull requests changed that later sub-issues must know

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-ux for the owner early, after the first merges, and again after the last one.

To know before the merge into develop

After the last sub-issue

  1. Serve the planner from planner-ux for 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.
  2. Open the pull request planner-ux into develop, with Requirements: none. It merges only with the owner's word.
  3. 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.
  4. Set Status: done on 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-ux and its own checks pass.
  • obc test affected --base origin/develop passes on planner-ux.
  • The owner checks the running planner of planner-ux in 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

  1. added
    epicTracking issue spanning multiple sub-issues
    on Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    epicTracking issue spanning multiple sub-issues

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions