## ADDED Requirements ### Requirement: Create collaborative session The Planner SHALL allow creating a new editing session that generates a unique shareable URL. Sessions SHALL be created either from the Planner directly (empty route) or via a Journal callback (with initial GPX data). #### Scenario: Create empty session - **WHEN** a user navigates to planner.trails.cool - **THEN** a new Yjs session is created with an empty waypoint list and the user is redirected to `/session/` #### Scenario: Create session from Journal callback - **WHEN** the Journal opens `planner.trails.cool/new?callback=&token=&gpx=` - **THEN** a new Yjs session is created with waypoints parsed from the GPX and the callback URL is stored for later save operations ### Requirement: Join session via link The Planner SHALL allow any user (including guests without accounts) to join an existing session by navigating to its URL. #### Scenario: Join active session - **WHEN** a user navigates to `planner.trails.cool/session/` - **THEN** the user connects to the Yjs document and sees the current route state with all other participants' cursors #### Scenario: Join expired session - **WHEN** a user navigates to a session URL that has expired - **THEN** the system displays an error message indicating the session no longer exists ### Requirement: Real-time collaborative editing The Planner SHALL synchronize waypoint edits across all connected participants in real-time using Yjs CRDTs. #### Scenario: Add waypoint - **WHEN** participant A adds a waypoint to the map - **THEN** participant B sees the waypoint appear within 500ms #### Scenario: Reorder waypoints - **WHEN** participant A drags a waypoint to reorder it - **THEN** participant B sees the updated waypoint order within 500ms #### Scenario: Concurrent edits - **WHEN** participant A and B both add waypoints simultaneously - **THEN** both waypoints appear for both participants without conflict ### Requirement: Session persistence The Planner SHALL persist Yjs session state to PostgreSQL so that sessions survive server restarts. #### Scenario: Server restart recovery - **WHEN** the Planner server restarts while a session is active - **THEN** reconnecting clients recover the full session state from PostgreSQL ### Requirement: Session expiry The Planner SHALL automatically expire sessions after a configurable period of inactivity (default: 7 days, max: 30 days). #### Scenario: Session expires - **WHEN** no edits are made to a session for 7 days - **THEN** the session is deleted from PostgreSQL and its URL returns a 404 ### Requirement: Manual session close The session owner (initiator) SHALL be able to manually close a session. #### Scenario: Owner closes session - **WHEN** the session owner clicks "Close Session" - **THEN** all connected participants are notified, the session triggers auto-save if a callback exists, and the session becomes inaccessible ### Requirement: User presence The Planner SHALL display presence indicators showing which users are currently connected to a session, including live cursors on the map. #### Scenario: Show connected users - **WHEN** multiple users are connected to a session - **THEN** each user sees a list of other connected users with assigned colors #### Scenario: Live map cursors - **WHEN** a user moves their mouse over the map - **THEN** other participants see a labeled cursor at that position on their map, colored to match the user's assigned color #### Scenario: Cursor disappears on leave - **WHEN** a user disconnects from the session - **THEN** their cursor disappears from all other participants' maps within 5 seconds ### Requirement: Planner home page The Planner home page SHALL explain the tool's purpose and provide a one-click way to start planning. #### Scenario: First-time visitor - **WHEN** a user visits planner.trails.cool for the first time - **THEN** they see a landing page explaining collaborative route planning, key features, and a prominent "Start Planning" button #### Scenario: Start a session - **WHEN** a user clicks "Start Planning" - **THEN** a new anonymous session is created and the user is redirected to the session view #### Scenario: Journal link - **WHEN** a user wants to save routes permanently - **THEN** a secondary CTA links to trails.cool for account creation ### Requirement: No user data collection The Planner SHALL NOT collect, store, or track any personal user data. Sessions are anonymous by default. #### Scenario: Anonymous session participation - **WHEN** a user joins a session without any account - **THEN** the user is assigned a random color and temporary display name with no data persisted about their identity ### Requirement: Session participant awareness Users in a planning session SHALL see who else is present and be able to identify themselves. #### Scenario: Participant list visible - **WHEN** multiple users are in a session - **THEN** the header shows each participant's name and color #### Scenario: Host badge - **WHEN** a participant is the routing host - **THEN** their entry in the participant list shows a host indicator #### Scenario: Edit own name - **WHEN** a user clicks their own name in the participant list - **THEN** an inline text input appears to change their display name #### Scenario: Name persisted - **WHEN** a user changes their name - **THEN** the name is saved to localStorage and immediately visible to all other participants via awareness #### Scenario: Join notification - **WHEN** a new participant joins the session - **THEN** a brief toast shows "[name] joined" #### Scenario: Leave notification - **WHEN** a participant leaves the session - **THEN** a brief toast shows "[name] left" ### Requirement: Planner session data model The Yjs document SHALL include noGoAreas and notes fields alongside waypoints and routeData. #### Scenario: Session with all fields - **WHEN** a Planner session is active - **THEN** the Yjs doc contains: waypoints (Y.Array), routeData (Y.Map), noGoAreas (Y.Array), notes (Y.Text)