TREK Tours — Non-Motorized Day Tour Planning

[elmocito]

Why

Enable non-motorized day-tour planning in trip context, with a clear distinction between a route being planned and a Tour being attached to a trip day.

Included scope

• A first-party Tours trip Add-on, with Hike as the first active Tour type.
• Tours ADD and PLAN workflows, with Hike as the first active Tour type.
• GPX import and read-only review.
• Valhalla pedestrian routing and T1–T6 difficulty selection.
• Tours-local Topo map, elevation profile, and route-profile focus marker.
• Editable persisted waypoints and atomic Tour save.
• Segment-aware day routing at Tour boundaries.
• Desktop/tablet Planner authoring and mobile Tour View/Attach.
• Tours OFF fallback to legacy Places behavior.

Why an Add-on, not a Plugin

Tours is an optional first-party trip-planning capability that extends the existing Places and day-assignment workflows, permissions, map, and offline trip bundle. It belongs to TREK's built-in Add-on lifecycle rather than the Plugin system, which is intended for separately supplied integrations and extensions.

Architecture

Tours are an isolated bounded context. Place serves as an internal geometry carrier; Tour metadata and ordered points live in tours, tour_waypoints, and tour_types. No Tours columns are added to Places. Add-on gating preserves legacy behavior when Tours is disabled.

Non-Goals

No live navigation, GPS tracking, social trail network, Wanderer connector, or additional Tour type is included in this PR.

Database and migrations

The migration lineage preserves upstream migrations through 258 and adds Tours migrations 259–262. The additions cover Tour types, Tour facets, ordered waypoints, and hiking-routing difficulty. Legacy/frozen lineage states use a safe bridge strategy.

Permissions

Tour creation, editing, and import use place_edit. Attaching or removing a Tour assignment uses day_edit. Mobile Tour details remain View/Attach-only.

Tests and validation

The reviewed public diff contains 202 changed files.

Local validation ran on macOS with Node.js 22.23.1 and npm 10.9.8. The pinned public workflows use Node.js 24 for the monorepo jobs and Node.js 22 for Plugin Facts and the standalone Plugin SDK.

• Strict i18n parity, Shared/Server/Server-test/Client/Plugin-SDK typechecks, normal Shared/Server/Client builds, lint:pages, current-branch Server and Client check-only ESLint, and git diff --check on the public diff passed. ESLint reported warnings but no errors; no auto-fixing lint was run.
• Focused Mac tests passed before the dev sync: Server E2E (Places, Trips, Assignments, Days), 91 tests; focused Server Tours/Places/migration/Roadtrip regressions, 19 files and 416 tests; focused Client page/Tours/mobile/map/elevation/PDF/overview/Roadtrip regressions, 30 files and 1,101 tests.
• After merging current dev, the upstream notification transport tests passed (64); the focused Server Tours smoke passed (8 files, 96 tests); and the focused Client page/Tours smoke passed (9 files, 465 tests).
• Pre-repair only: the earlier Server full coverage run had 8 failures and the Client full coverage run had 35 failures. This included missing Tours tables in the hand-built E2E fixtures, missing isTourPlace and listener-count fixture updates, the tours:changed registry classification, and the page-pattern violations. The applicable targeted checks passed after those repairs. The monolithic Server and Client suites were not rerun afterward, so these are not claimed as post-repair full-suite results.
• The Sunday-dependent PlaceInspector baseline expectation and the full-suite PLACE-020 socket reset remain unrelated baseline/environment findings. The 135 Shared locale-entrypoint Prettier findings are unchanged from the pinned base; no formatting was applied.
• Translation files passed strict key/file/placeholder parity. AI-generated translations have not been certified by native speakers.

Hosted GitHub Actions have not run for this change; no hosted CI pass is implied.

Review order

Order	Area	Focus
1	Product boundary	First-party Add-on lifecycle, isolated Tours facet, and Place as geometry carrier
2	Data and migrations	Tour tables, migrations 259–262, and legacy/frozen lineage bridges
3	Permissions and persistence	place_edit versus day_edit, atomic save/import, and deletion/invalidation
4	Planning workflow	ADD/PLAN, GPX read-only review, T1–T6, Topo maps, elevation focus, segment-aware routing
5	Client integration	Desktop/tablet Planner, mobile View/Attach-only, Tours OFF fallback, realtime invalidation
6	Validation and follow-ups	Focused Mac results, hosted CI pending, and post-MVP exclusions

Known limitations / post-MVP

Follow-up candidates include waypoint drag, Return to start/reverse/out-and-back, OpenHikingMap or other overlays, GPX conversion, external navigation handoff, and Wanderer integration.

Review questions for Maurice

• Is Tours appropriately a first-party Add-on rather than a Plugin integration?
• Is the product boundary between Tours and Places clear?
• Is the ADD/PLAN placement appropriate in the trip workflow?
• Is the bounded-context split and Core integration maintainable?
• Is the place_edit / day_edit permission boundary correct?
• Is the migration and legacy bridge strategy acceptable?
• What changes are required before merge?