Projects › BibleWeb › Notes › Verse-level notes
Done

Verse-level notes

Area: Notes Milestone: v1

Context

Problem: Bible readers want to jot down thoughts, insights, or questions about specific verses — and find them again later when they return to that passage.

Solution: A note system that attaches user-written notes to individual verses. Notes are created via the verse context menu and appear as subtle indicators in the reader text.

Not included: Rich text formatting (bold, italic, links) in notes. Notes are plain text only.

Functional

Users can create, edit, and delete notes on any verse. Notes are saved immediately and persist across sessions.

User flow:

  1. User clicks a verse → context menu → "Add Note"
  2. A note editor overlay appears with a text area
  3. User types their note and presses Ctrl+S to save (or clicks Save)
  4. The verse now shows a dashed underline on its first 5 words (note indicator)
  5. Clicking the underlined words reopens the note editor
  6. User can edit or delete the note

Edge cases:

  • Free tier: limited to 5 notes total
  • Pro tier: unlimited notes
  • Notes are per-user (requires authentication for server persistence, localStorage fallback for anonymous)
  • Empty notes are not saved

UX & Design

Note editor:

  • Fixed overlay in the reader (doesn't push content down)
  • Auto-resizing textarea
  • Ctrl+S to save, Escape to cancel
  • Shows verse reference in the header

Note indicator: Dashed underline on first 5 words of noted verses (see Verse Note Indicators feature).

Technical

DB table: user_notes

  • Columns: id (PK), userId, type ('verse'), bookId, chapter, verse, content, createdAt, updatedAt
  • Index on userId

API:

  • POST /api/notes — create (enforces free tier limit of 5)
  • PATCH /api/notes/[id] — update (ownership enforced)
  • DELETE /api/notes/[id] — delete (ownership enforced)
  • GET /api/notes — fetch all user notes

Client store (notes.svelte.ts):

  • Svelte 5 runes $state
  • Map<"bookId:chapter:verse", VerseNote> index for O(1) lookup
  • Optimistic updates (rollback on failure)
  • initNotes() fetches all notes on mount

Component: NoteEditor.svelte — fixed overlay with auto-resizing textarea, Ctrl+S save, Escape cancel.

Tier limits (tier.ts): Free = max 5 notes, Pro = unlimited.

Files:

  • apps/web/src/routes/api/notes/+server.ts — POST (create)
  • apps/web/src/routes/api/notes/[id]/+server.ts — PATCH, DELETE
  • apps/web/src/lib/server/queries/notes.ts — CRUD functions
  • apps/web/src/lib/stores/notes.svelte.ts — client store
  • apps/web/src/lib/components/bible/NoteEditor.svelte — editor UI

Status

Current: DONE Milestone: v1 Priority: Core — fundamental study feature

History:

  • BibleGame had a notes system for verses
  • Web version adds optimistic updates and Map-based O(1) lookups

Dependencies:

  • Requires: verse database (DONE), auth system (DONE)
  • Used by: note indicators (DONE), notes list (DONE), note export (DONE), note cross-linking (DONE)

Screenshots

Feature screenshot
← Back to Notes features