trails/openspec/specs/session-notes/spec.md at 57696286e4485eb0f10deb6f36cc8ad96c51ecaf

Ullrich Schäfer 0cf87b72ab

Fix medium-severity spec drift across 17 specs

- authentication-methods: document completeAuth mode param ("redirect"|"json");
  clarify add-passkey nudge (no dismiss mechanism, disappears on passkey add)
- journal-auth: session maxAge is 30 days; terms allow-list uses /legal/ prefix
  matching (broader than fixed list of paths)
- session-notes: mark awareness isolation and UndoManager isolation as not yet
  implemented (shared instances in current code)
- activity-feed: add fan-out scenario for visibility change to public
- explore: note that ?perPage is not yet implemented (hardcoded page size)
- multi-day-routes: add per-day GPX track split scenario (splitByDays option);
  document overnight vs isDayBreak naming gap
- osm-poi-overlays: debounce is 800ms + 2000ms min interval (not 500ms);
  retry is not automatic (fires on next viewport change)
- brouter-integration: rate limit corrected to 300/hour; add segment-cache
  requirement (client caches per-pair segments)
- wahoo-route-push: OAuth state shape uses camelCase (returnTo, pushAfter
  object) not snake_case with push_after boolean
- komoot-import: document noop adapter / ConnectedServiceManager bypass;
  note four Komoot-specific routes that bypass the generic OAuth framework
- background-jobs: exponential backoff not wired (retryLimit only); add SIGINT
- connected-services: add revoked status; name ConnectionNotActiveError
- infrastructure: add INTEGRATION_SECRET and SENTRY_DSN to env var lists;
  split secret decryption scenario by workflow (cd-apps vs cd-infra)
- secret-management: correct CD decryption — cd-apps only decrypts app.env;
  cd-infra decrypts both
- transactional-emails: welcome email is async (pg-boss job); magic-link email
  includes 6-digit numeric code
- journal-route-detail: websites are https: links (not mailto:); opening_hours
  is also displayed
- local-dev-environment: add mobile app (Expo) dev commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-24 11:11:31 +02:00

3.1 KiB

Raw Blame History

Purpose

Collaborative rich text notes in Planner sessions, powered by CodeMirror 6 with Yjs CRDT sync and real-time cursor awareness.

Requirements

Requirement: Collaborative session notes

Planner sessions SHALL have a shared text editor for participants to write notes, with character-level real-time sync.

Scenario: Write notes

WHEN a user types in the notes editor
THEN the text syncs character-by-character to all other participants via Yjs Y.Text

Scenario: Remote cursor awareness

WHEN multiple participants are editing notes
THEN each participant sees the others' cursor positions and selections highlighted in their assigned color with their name label

Scenario: Notes persist across reload

WHEN a participant reloads the session page
THEN the notes content is restored from the Yjs document
AND the editor displays the existing text immediately

Scenario: Notes persist across reconnect

WHEN a user leaves and rejoins a session
THEN the notes are still there (stored in Yjs doc and crash recovery)

Requirement: Editor implementation

The notes editor SHALL use CodeMirror 6 with y-codemirror.next for Yjs binding.

Scenario: Undo/redo (not fully isolated)

WHEN a user presses Ctrl+Z / Ctrl+Shift+Z in the notes editor
THEN undo/redo operates via the shared Y.UndoManager that also covers waypoints and no-go areas — undo in the notes editor may undo recent waypoint changes and vice versa

Note: the spec originally called for a separate Y.UndoManager for notes. The shipped implementation uses a single shared manager (new Y.UndoManager([waypoints, noGoAreas, notes], {...}) in use-yjs.ts). Full isolation is aspirational.

Scenario: Awareness field isolation (not yet isolated)

WHEN the notes editor sets cursor awareness state
THEN it uses the same shared awareness object as the map cursor awareness; the yCollab extension writes to the "user" field on the same channel

Note: the spec originally called for separate awareness fields. The shipped implementation passes the same awareness instance to both the map and notes editor. Full isolation is aspirational.

Requirement: Notes in GPX export

Notes SHALL be included in GPX exports as <metadata><desc>.

Scenario: Export plan with notes

WHEN a user exports a plan GPX and notes are present
THEN the GPX contains <metadata><desc> with the notes text

Scenario: Import GPX with notes

WHEN a GPX file with <metadata><desc> is imported
THEN the notes editor is populated with the description text

Requirement: Notes sync to Journal

Notes SHALL be saved to the Journal route description when saving via callback.

Scenario: Save to Journal with notes

WHEN a user saves a route to the Journal and notes are present
THEN the route's description field is set from the notes text

Scenario: Edit in Planner restores notes

WHEN a user clicks "Edit in Planner" on a Journal route with a description
THEN the Planner session's notes editor is populated with the description

3.1 KiB Raw Blame History