# Meta Photo Map Product Definition ## Goal Create one canonical photo-map landing page that lists and previews all photo maps, then lets a visitor load an individual trip into the same map experience without navigating to a separate one-trip map page. The core product principle is: > Overview is trip-level. Detail is photo-level. The landing page should feel like "one page to rule them all," but it should not eagerly load every photo marker from every trip on initial page load. ## Background The existing photo-map system supports individual maps such as `pages/*-map.md`, where one page maps one trip. Photo-map posts can also embed a map via front matter such as `photo_map: tohoku`. Now that trips can appear inside posts, standalone one-trip pages are less useful. The desired direction is to replace or supersede them with one all-trips photo-map page, likely at `/bike-map/`. The current runtime creates one Leaflet marker per photo and clusters those markers client-side. That is fine for one trip, but a naive all-trips page with 10 trips and 1,000 photos per trip would create about 10,000 photo markers up front. That is not the desired default architecture, especially for mobile. ## Primary Experience ### Overview Mode When the visitor opens the landing page, the map starts in overview mode. Overview mode shows all trips as trip-level objects: - One marker or visual anchor per trip. - A trip list or side panel containing all trips. - Each trip item should include title, description or short summary, and preferably a cover image if available. - The map should fit all trip markers or trip bounds. - The initial page should load only lightweight trip summary data, not all photo records for all trips. The overview should work for geographically distant trips, for example California, Japan, and France. Starting at world scale is acceptable when trips are globally distributed. ### Trip Mode When the visitor selects a trip, the page enters trip mode. Trip mode loads the selected trip's detailed data on demand: - Photo markers for that trip. - Photo marker clustering. - Full route GeoJSON for that trip. - Post markers associated with that trip, if any. - Existing fullscreen photo viewer behavior, scoped to the selected trip. The page should not perform a full page transition when entering trip mode. It should feel like the same map has expanded into the selected trip. Trip mode should make the active state obvious. The visitor should understand which trip is currently loaded. ## Returning To Overview The browser Back button should return from trip mode to overview mode, but it must not be the only exit affordance. Trip mode must provide a visible, labeled control: ```text <- All photo maps ``` or: ```text Back to all photo maps ``` This control unloads the active trip and returns the page to overview mode. Do not rely on an icon-only close button. A plain `X` is ambiguous because it might mean close the side panel, hide photos, close the viewer, or unload the trip. Clicking empty map space should not unload a trip. Map clicks are too easy to trigger accidentally while panning, zooming, or exploring. The Escape key may be supported as a secondary desktop shortcut. If implemented, it should close the photo viewer first. Only if no photo viewer is open should Escape return from trip mode to overview mode. ## Desktop Layout Desktop should use the map plus a side panel. Overview side panel: - Shows the page title and short intro. - Lists all available trips. - Each trip entry acts as a clear call to load that trip. - Trip entries may show cover image, title, description, rough region/date, photo count, route count, or linked post count if available. Trip side panel: - Starts with the visible `Back to all photo maps` control. - Shows the active trip title prominently. - Shows trip description and relevant metadata. - Shows linked posts, if present. - May include nearby or other trip cards later, but that is not required for the first version. The map should remain the dominant visual element. The panel should guide selection and orientation rather than become a separate archive page. ## Mobile Layout A permanent desktop-style side panel is not appropriate on mobile. Mobile should still provide the same states and controls, but the panel should become a bottom sheet, drawer, or stacked information area. Recommended mobile behavior: - Overview opens as a map-first experience. - Trip markers remain tappable. - Selecting a trip loads trip mode in place. - Trip mode shows a clearly visible `Back to all photo maps` pill over the map. - The control should be visible without requiring the user to discover browser Back. - The map should remain usable for pan/zoom and marker taps. Avoid placing the only trip-mode exit inside a hidden menu. Mobile users should immediately see how to return to the all-trips map. The exact mobile presentation can be refined during implementation, but the product requirement is that overview/trip mode and the return action are discoverable on a phone. ## URL And History Behavior The page should support browser history. Suggested states: - Overview: `/bike-map/` - Trip mode: `/bike-map/#trip=tohoku` - Photo viewer: `/bike-map/#trip=tohoku&photo=` or an equivalent namespaced hash format Selecting a trip should push history state so that browser Back returns to overview. Returning via `Back to all photo maps` should also update the URL back to overview. If a visitor lands directly on a trip hash, the page should load that trip. If a visitor lands directly on a trip/photo hash, the page should load the trip and open the photo viewer if the photo exists. Photo identifiers should be namespaced or otherwise guaranteed not to collide across trips. ## Data Model Requirements The landing page needs a lightweight all-trip index generated at build time. The index should include enough data for overview mode without requiring all photo records: - Trip slug. - Title. - Description. - Cover image or representative marker image, if available. A trip manifest may set `cover_photo: ` to choose the image used for overview trip cards. - Trip marker location, centroid, or bounds. - Optional simplified route preview or route bounds. - Counts such as photos, routes, and posts. - Link to the generated detailed trip data. - Links to generated route GeoJSON, if needed for previews. Detailed photo data should remain per trip and load on demand. The current per-trip generated data format can remain the source for trip mode, but implementation may need to adjust the runtime so it can load data dynamically instead of reading only one embedded `#photo-map-data` script at startup. ## Performance Requirements Initial overview load should scale with number of trips, not number of photos. The first version should avoid creating all photo markers for all trips at startup. When a trip is unloaded: - Remove its photo markers. - Remove its detailed route layers. - Clear active photo viewer state. - Return map bounds to the overview, unless the implementation intentionally preserves user map position. Loaded trip data may be cached in memory during the page session so re-selecting a trip does not require another network fetch. The design should continue to work if the site grows to 10 or more trips and 10,000 or more total photos. ## Visual Semantics Overview mode should not mix unrelated trip photos into one global cluster. A cluster containing photos from multiple trips creates ambiguity and weakens the trip-level mental model. Trip markers should feel distinct from photo markers. They may use larger pins, cards, cover thumbnails, route badges, or another clear visual treatment. Routes from multiple trips may overlap. The overview should avoid showing dense full-detail route overlays for every trip at once. If route previews are shown in overview, they should be simplified and visually secondary. Trip mode can use the existing route and photo-marker visual language. ## Existing One-Trip Pages The landing page should become the preferred destination for photo maps. Existing one-trip pages such as `/bike-map/tohoku/` can be removed, redirected, or retained temporarily. That decision can be made during implementation. Photo-map posts should remain unchanged unless explicitly scoped into this work. Do not break normal post behavior. ## Non-Goals For First Version - Do not load every photo from every trip on initial page load. - Do not require a backend service. - Do not introduce server-side dynamic APIs. - Do not implement automatic viewport-based loading unless it falls out naturally from the selected architecture. - Do not require multiple trips to be loaded simultaneously in the first version. - Do not make map-empty-click the primary way to unload a trip. ## Possible Future Enhancements - Multi-select trips for comparison. - Toggle nearby trips while in trip mode. - Zoom-based lazy loading of trips intersecting the viewport. - Search/filter by country, region, year, or trip type. - Trip stats such as distance, elevation, day count, and photo count. - Animated transition from trip overview marker to detailed route/photo mode. - Shareable URLs for selected trip, selected photo, or selected map bounds. ## Acceptance Criteria - `/bike-map/` or the chosen canonical URL opens an all-trips overview map. - Initial page load uses lightweight trip summary data only. - Selecting a trip loads that trip's photos and routes into the same map. - Trip mode has a visible labeled `Back to all photo maps` or equivalent control. - Browser Back returns from trip mode to overview mode. - Direct links to a trip state load that trip. - Desktop provides a side panel or equivalent persistent trip information area. - Mobile provides a discoverable equivalent to the side panel and does not rely only on browser Back. - Existing photo-map posts continue to work. - The implementation remains static-site compatible.