bible270 1.1.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 323ea67db4332521a07129d64ca3b1e4f6405ba0d87352f14db5dcbcbbe675c7
-  data.tar.gz: b60e969effcc93b68b95c29e8054aae754a41210641146ce526eefd6d28e0229
+  metadata.gz: b9f698d3dbbc6afbb9130e3dc81767302792e8f25e23db7d702401eb290b747e
+  data.tar.gz: e109e61cc7a4e39098124cb7e1996c980d248b54c3e7649702901a6b5e65e392
 SHA512:
-  metadata.gz: 799b578048236367edd22c1b75e3c62d9c2b24a8dce6d28174695954a465d97ddffb75164d790b207d7aaca3d225a2a8f1f00e6e2d932cfd90b9824277c53f7d
-  data.tar.gz: 6c7c718e5e2c3b434090eb38481371ec0a63399769d0d54ded50fbee47de914bcbd5fe49605169b7a81b012f979826333d28b2aa349e8392955bd9567187a49c
+  metadata.gz: d9742929c763b48681e352e95510a8944eb087529453ed10af579fd737db35a75492ef55c25c9a6416d925728072b69868a02f2e8f3300882f14711a3f71c338
+  data.tar.gz: d5b50e44afd429885e2e90af7b36df10fa0aaff363d39c03309f4d1885560da0f73d020ba7de53571f0ae0be129b2e55bccba9e1bd02dc45d82984718d82134d

data/CHANGELOG.md

@@ -4,11 +4,32 @@ All notable changes to bible270. Format follows [Keep a Changelog](https://keepa
 
 ## Unreleased Changes
 
+### Added
+
+- let readers choose reflection emails for every new reflection and reply, only replies to their reflections and mentions of them, or none; administrators can manage the same setting, pending migrations are explained instead of silently hiding it, and existing preferences retain their previous behavior
+- suggest up to five unambiguous reader handles only while a signed-in writer types `@`, with keyboard and touch selection and no change to server-authoritative mention resolution
+
+### Fixed
+
+- refresh stale `Reader` column information after an in-process database migration so newly available reflection email controls do not remain hidden until the web process restarts
+
+**[Full Changelog](https://github.com/avonderluft/bible270/compare/v1.1.7...main)**
+
+## [1.1.7] - 2026-08-27
+
+### Fixed
+
+- silently recover checkoffs from expired or rotated sessions: refresh remembered sessions and CSRF tokens before resumed interactions, handle remaining stale-token races without a flash or Rails 422 page, and retry the intended checkoff once with a fresh token
+
+**[Full Changelog](https://github.com/avonderluft/bible270/compare/v1.1.6...v1.1.7)**
+
+## [1.1.6] - 2026-08-25
+
 ### Changed
 
-- show administrators a quiet, linked completed-day count on Community reader rows while keeping progress hidden—and its aggregate query skipped—for ordinary readers and visitors
+- show administrators a quiet, linked completed-day count on Community reader rows while keeping progress hidden—and its aggregate query skipped—for ordinary readers and visitors; the link stays unadorned at rest and uses the site’s gold hover and keyboard-focus treatment
 
-**[Full Changelog](https://github.com/avonderluft/bible270/compare/v1.1.5...main)**
+**[Full Changelog](https://github.com/avonderluft/bible270/compare/v1.1.5...v1.1.6)**
 
 ## [1.1.5] - 2026-08-25
 
@@ -552,6 +573,8 @@ This is the initial public release.
 
 * Email sign-in requires working Action Mailer delivery in the host application. Set `config.mailer_from`; delivery is inline by default, or set `email_sign_in_deliver_later` when a queue backend is available.
 
+[1.1.7]: https://github.com/avonderluft/bible270/releases/tag/v1.1.7
+[1.1.6]: https://github.com/avonderluft/bible270/releases/tag/v1.1.6
 [1.1.5]: https://github.com/avonderluft/bible270/releases/tag/v1.1.5
 [1.1.4]: https://github.com/avonderluft/bible270/releases/tag/v1.1.4
 [1.1.3]: https://github.com/avonderluft/bible270/releases/tag/v1.1.3

data/README.md

@@ -6,6 +6,8 @@ A mountable **Rails engine** that drops a 270-day (9 month) interactive Bible re
 
 Initially created for use by students and faculty of [Kingdom Movement School of Ministry](https://www.kmsm.life/), to read through all of Scripture together during the school year. Thus it is potentially useful for any Bible School, Seminary, or Discipleship school working on a 9 month schedule.
 
+For a guided tour of the implementation, see the [architecture walkthrough](docs/architecture.md).
+
 ## The plan
 
 Three readings a day, sized by **verse count** so each day takes roughly the same time.
@@ -280,9 +282,15 @@ The Reflections page lists conversations by their latest approved reply, support
 filters, and paginates older threads. Signed-in readers see which conversations became active since
 their previous visit. Reflection and reply drafts are retained for up to 30 days in that browser and
 cleared after a successful post. On a shared device, clearing browser storage also removes saved drafts.
+Typing `@` in the composer offers up to five unambiguous reader handles; manual mentions continue to
+work without JavaScript.
 
-After upgrading, copy and run migration `20260101000017`, which stores each reader's last visit to the
-Reflections page:
+When `config.mention_notifications` is enabled, each reader can request email for every new reflection
+and reply, only replies to their reflections and mentions of them, or none. Administrators can change
+the same preference from the reader's Admin page. Migration
+`20260101000018` adds the broad opt-in without changing any existing reader's choice. Migration
+`20260101000017` stores each reader's last visit to the Reflections page. After upgrading, install and
+run the current migrations:
 
 ```bash
 bin/rails bible270:install:migrations
@@ -396,7 +404,7 @@ Bible270.configure do |config|
   config.allow_reader_start_date = true
 
   config.daily_reminders = false             # schedule reminders:send every 15 minutes
-  config.mention_notifications = true         # replies and @mentions; readers may opt out
+  config.mention_notifications = true         # reflection/reply emails; readers choose the scope
   config.mailer_host = "example.com"          # links in reminder/notice email
 
   config.parent_controller = "ActionController::Base"   # or "::ApplicationController"
@@ -485,7 +493,8 @@ GET    /day/:day                 days#show       readings, who's finished, refle
 POST   /day/:day/toggle/:track   checkoffs#toggle
 POST   /day/:day/comments        comments#create
 DELETE /comments/:id             comments#destroy
-GET    /community                readers#index   leaderboard
+GET    /community                readers#index   reader directory
+GET    /mention-suggestions      readers#mention_suggestions (signed-in JSON)
 GET    /readers/:id              readers#show
 GET    /sign_in                  sessions#new    email form + provider list
 POST   /sign_in/email            sessions#email_link

data/app/controllers/bible270/admin_controller.rb

@@ -13,7 +13,8 @@ module Bible270
 
     before_action :require_admin!
     before_action :load_reader,
-                  only: %i[show destroy update_start update_profile remove_avatar complete_through toggle_day]
+                  only: %i[show destroy update_start update_profile update_notifications remove_avatar complete_through
+                           toggle_day]
     before_action :load_comment, only: %i[hide_comment unhide_comment destroy_comment]
 
     # ---- enrolment --------------------------------------------------------
@@ -69,6 +70,7 @@ module Bible270
     end
 
     def show
+      @comment_notifications_available = comment_notifications_available_for?(@reader)
       @days_completed = @reader.days_completed
       @comments = @reader.comments.order(created_at: :desc).limit(50)
     end
@@ -194,6 +196,24 @@ module Bible270
       end
     end
 
+    def update_notifications
+      unless Bible270.config.mention_notifications
+        return redirect_to admin_reader_path(@reader), alert: 'Reflection emails are disabled for this installation.'
+      end
+      unless comment_notifications_available_for?(@reader)
+        return redirect_to admin_reader_path(@reader),
+                           alert: 'Run the pending Bible270 database migration before changing reflection emails.'
+      end
+
+      level = params[:comment_notifications].to_s
+      unless Reader::COMMENT_NOTIFICATION_LEVELS.include?(level)
+        return redirect_to admin_reader_path(@reader), alert: 'Choose a reflection email setting from the list.'
+      end
+
+      @reader.update_comment_notification_level!(level)
+      redirect_to admin_reader_path(@reader), notice: 'Reflection email setting updated.'
+    end
+
     def remove_avatar
       @reader.remove_avatar!
       redirect_to admin_reader_path(@reader), notice: "Removed #{@reader.display_name}'s picture."
@@ -247,6 +267,13 @@ module Bible270
 
   private
 
+    def comment_notifications_available_for?(reader)
+      return false unless Bible270.config.mention_notifications && Reader.comment_notification_columns?
+
+      reader.reload unless reader.has_attribute?(:notify_on_all_comments)
+      true
+    end
+
     def require_admin!
       return if Bible270.config.admin_configured? && Bible270.config.admin?(current_reader)
 

data/app/controllers/bible270/application_controller.rb

@@ -26,6 +26,8 @@ module Bible270
 
     layout :bible270_layout
 
+    rescue_from ActionController::InvalidAuthenticityToken, with: :recover_from_stale_page
+
     helper_method :current_reader, :signed_in?, :b270_config, :enrollment_closed?
 
   private
@@ -101,6 +103,31 @@ module Bible270
       current_reader.present?
     end
 
+    # A suspended mobile tab can outlive its Rails session cookie. The page still
+    # contains the old session's CSRF token, so Rails would normally raise before
+    # current_reader could restore the session from the remember cookie. Redirect
+    # directly from Rails' forgery callback; rescue_from remains a fallback for an
+    # authenticity exception raised anywhere else in the request.
+    def handle_unverified_request
+      recover_from_stale_page
+    end
+
+    def recover_from_stale_page(error = nil)
+      reason = error ? error.class : 'an unverified request'
+      Rails.logger.info("[bible270] silently refreshing a page after #{reason}")
+
+      if stale_turbo_checkoff?
+        response.set_header('X-Bible270-Refresh-Session', 'true')
+        head :conflict
+      else
+        redirect_back fallback_location: root_path, allow_other_host: false, status: :see_other
+      end
+    end
+
+    def stale_turbo_checkoff?
+      controller_name == 'checkoffs' && action_name == 'toggle' && request.format.turbo_stream?
+    end
+
     # Guard participation (checking off / commenting). Viewing is always open.
     def require_reader!
       return true if signed_in?

data/app/controllers/bible270/profiles_controller.rb

@@ -14,9 +14,9 @@ module Bible270
 
     def update
       @comment_notifications_available = comment_notifications_available?
-      @notify_on_mention = requested_comment_notifications
+      @comment_notification_level = requested_comment_notification_level
       @daily_reminders_available = daily_reminders_available?
-      problems = []
+      problems = [comment_notification_problem].compact
       problems << 'both a first and last name' unless current_reader.update_names(params[:first_name],
                                                                                   params[:last_name])
       if params[:bible_version].present? && !current_reader.update_bible_version(params[:bible_version])
@@ -35,7 +35,7 @@ module Bible270
       end
 
       if problems.empty?
-        current_reader.update!(notify_on_mention: @notify_on_mention) if @comment_notifications_available
+        current_reader.update_comment_notification_level!(@comment_notification_level) if @comment_notifications_available
         if @daily_reminders_available
           current_reader.update!(daily_reminders: requested_daily_reminders,
                                  daily_reminder_time: requested_daily_reminder_time)
@@ -59,17 +59,27 @@ module Bible270
 
     def load_comment_notification_state
       @comment_notifications_available = comment_notifications_available?
-      @notify_on_mention = current_reader.wants_comment_notifications?
+      @comment_notification_level = current_reader.comment_notification_level
     end
 
     def comment_notifications_available?
-      Bible270.config.mention_notifications && current_reader.has_attribute?(:notify_on_mention)
+      return false unless Bible270.config.mention_notifications && Reader.comment_notification_columns?
+
+      current_reader.reload unless current_reader.has_attribute?(:notify_on_all_comments)
+      true
+    end
+
+    def requested_comment_notification_level
+      return current_reader.comment_notification_level unless params.key?(:comment_notifications)
+
+      params[:comment_notifications].to_s
     end
 
-    def requested_comment_notifications
-      return current_reader.wants_comment_notifications? unless params.key?(:notify_on_mention)
+    def comment_notification_problem
+      return unless @comment_notifications_available
+      return if Reader::COMMENT_NOTIFICATION_LEVELS.include?(@comment_notification_level)
 
-      params[:notify_on_mention] == '1'
+      'a reflection email preference from the list'
     end
 
     def load_daily_reminder_state

data/app/controllers/bible270/readers_controller.rb

@@ -35,5 +35,12 @@ module Bible270
       @days_completed = @reader.days_completed
       @recent_comments = @reader.comments.recent.limit(20)
     end
+
+    def mention_suggestions
+      return head :unauthorized unless signed_in?
+
+      response.headers['Cache-Control'] = 'private, no-store'
+      render json: { suggestions: Reader.mention_suggestions(params[:q], except: current_reader) }
+    end
   end
 end

data/app/controllers/bible270/sessions_controller.rb

@@ -17,6 +17,16 @@ module Bible270
       @origin = safe_origin(params[:origin])
     end
 
+    # Refresh a resumed page's session and CSRF token without reloading its content.
+    # Calling current_reader first lets the long-lived remember cookie rebuild a
+    # browser session that the phone may have discarded while the tab was asleep.
+    def refresh
+      current_reader
+      response.headers['X-CSRF-Token'] = form_authenticity_token
+      response.headers['Cache-Control'] = 'no-store'
+      head :no_content
+    end
+
     def create
       auth = request.env['omniauth.auth']
       redirect_to(sign_in_path, alert: "Sign in didn't complete. Please try again.") and return unless auth

data/app/mailers/bible270/notice_mailer.rb

@@ -36,6 +36,18 @@ module Bible270
       deliver_comment_notice("#{@app_name}: #{@author.display_name} replied on day #{@comment.day}")
     end
 
+    def comment_posted(comment_id:, reader_id:)
+      return message.perform_deliveries = false unless prepare_comment_notice(comment_id, reader_id)
+      return message.perform_deliveries = false unless @reader.wants_all_comment_notifications?
+      return message.perform_deliveries = false if @comment.reader_id == @reader.id
+
+      kind = @comment.reply? ? 'reply' : 'reflection'
+      @heading = "#{@author.display_name} posted a #{kind}"
+      @introduction = "#{@author.display_name} posted a #{kind} on day #{@comment.day}."
+      @reason = 'You are getting this because you asked to be emailed about every new reflection and reply.'
+      deliver_comment_notice("#{@app_name}: #{@author.display_name} posted a #{kind} on day #{@comment.day}")
+    end
+
     def daily_reminder(reader_id:, day:, on: Bible270.today)
       @reader = Reader.find_by(id: reader_id)
       return message.perform_deliveries = false unless Bible270.config.daily_reminders?

data/app/models/bible270/comment.rb

@@ -155,11 +155,13 @@ module Bible270
     end
 
     def notify_comment_readers
-      return unless Bible270.config.mention_notifications
+      return unless Bible270.config.mention_notifications && approved?
 
       replied_to = reply_notification_reader
       deliver_comment_notice(replied_to, :replied) if replied_to
-      notify_mentioned_readers(except: [replied_to&.id].compact)
+      directly_notified = [reader_id, replied_to&.id].compact
+      directly_notified.concat(notify_mentioned_readers(except: directly_notified))
+      notify_all_comment_readers(except: directly_notified)
     end
 
     def notify_newly_mentioned_readers
@@ -171,13 +173,20 @@ module Bible270
     end
 
     def notify_mentioned_readers(except: [])
-      return unless Bible270.config.mention_notifications
+      return [] unless Bible270.config.mention_notifications
 
-      Reader.mentioned_in(body).each do |mentioned|
+      Reader.mentioned_in(body).each_with_object([]) do |mentioned, notified|
         next if mentioned.id == reader_id
         next if except.include?(mentioned.id)
 
         deliver_comment_notice(mentioned, :mentioned)
+        notified << mentioned.id
+      end
+    end
+
+    def notify_all_comment_readers(except: [])
+      Reader.all_comment_notification_recipients.where.not(id: except).find_each do |recipient|
+        deliver_comment_notice(recipient, :comment_posted)
       end
     end
 

data/app/models/bible270/reader.rb

@@ -31,6 +31,9 @@ module Bible270
     DAILY_REMINDER_MINUTES = %w[00 15 30 45].freeze
     DAILY_REMINDER_COLUMNS = %w[daily_reminders daily_reminder_time last_daily_reminder_sent_on].freeze
     REFLECTIONS_SEEN_COLUMN = 'reflections_seen_at'
+    COMMENT_NOTIFICATION_LEVELS = %w[all personal none].freeze
+    COMMENT_NOTIFICATION_COLUMNS = %w[notify_on_mention notify_on_all_comments].freeze
+    MENTION_SUGGESTION_LIMIT = 5
 
     validates :display_name, presence: true
     validates :uid, uniqueness: { scope: :provider }, allow_nil: true
@@ -244,11 +247,76 @@ module Bible270
 
     # ---- mentions ----------------------------------------------------------
 
-    # Older copied databases may briefly lack the preference column while their
+    # Older copied databases may briefly lack preference columns while their
     # migrations are being reconciled. Preserve the historical opted-in behavior
-    # until the column is available rather than breaking reflection delivery.
+    # until the original column is available rather than breaking reflection delivery.
     def wants_comment_notifications?
-      !has_attribute?(:notify_on_mention) || self[:notify_on_mention] != false
+      wants_all_comment_notifications? || !has_attribute?(:notify_on_mention) || self[:notify_on_mention] != false
+    end
+
+    def wants_all_comment_notifications?
+      has_attribute?(:notify_on_all_comments) && self[:notify_on_all_comments] == true
+    end
+
+    def comment_notification_level
+      return 'all' if wants_all_comment_notifications?
+
+      wants_comment_notifications? ? 'personal' : 'none'
+    end
+
+    def update_comment_notification_level!(level)
+      raise ArgumentError, 'unknown reflection email preference' unless COMMENT_NOTIFICATION_LEVELS.include?(level)
+
+      update!(notify_on_mention: level != 'none', notify_on_all_comments: level == 'all')
+    end
+
+    def self.comment_notification_columns?
+      return true if (COMMENT_NOTIFICATION_COLUMNS - column_names).empty?
+
+      # A migration commonly runs in a one-off process while the web process keeps
+      # its old schema cache. Refresh once before reporting that the migration is
+      # still pending, so the controls appear without requiring an application restart.
+      reset_column_information
+      (COMMENT_NOTIFICATION_COLUMNS - column_names).empty?
+    rescue ActiveRecord::StatementInvalid
+      false
+    end
+
+    def self.all_comment_notification_recipients
+      return none unless comment_notification_columns?
+
+      where(notify_on_all_comments: true).where.not(email: [nil, ''])
+    end
+
+    # Small, deterministic suggestions for the reflection composer. Full-handle
+    # collisions are omitted because the server must never guess which reader a
+    # mention intended.
+    def self.mention_suggestions(query, except: nil)
+      needle = Mentions.normalize(query.to_s.first(61))
+      candidates = where.not(first_name: [nil, '']).where.not(last_name: [nil, ''])
+      candidates = candidates.where.not(id: except.id) if except
+      unique = candidates.to_a.group_by { |reader| canonical_mention_handle(reader) }
+        .select { |handle, readers| handle.present? && readers.one? }
+
+      ranked = unique.filter_map do |handle, readers|
+        reader = readers.first
+        surname = Mentions.normalize(reader.last_name)
+        rank = if needle.empty? || handle.start_with?(needle)
+                 0
+               elsif surname.start_with?(needle)
+                 1
+               end
+        next unless rank
+
+        [{ name: reader.display_name, handle: "@#{handle}" }, rank, handle, reader.id]
+      end
+      ranked.sort_by { |_, rank, handle, id| [rank, handle, id] }
+        .first(MENTION_SUGGESTION_LIMIT)
+        .map(&:first)
+    end
+
+    def self.canonical_mention_handle(reader)
+      Mentions.handles_for(reader.first_name, reader.last_name).last
     end
 
     # The readers a piece of text mentions. A handle matching more than one reader

data/app/views/bible270/admin/show.html.erb

@@ -46,6 +46,30 @@
   <% end %>
 </div>
 
+<div class="b270-panel">
+  <h2 class="b270-subhead">Email notifications</h2>
+  <% unless Bible270.config.mention_notifications %>
+    <p class="b270-hint">Reflection emails are disabled for this installation.</p>
+  <% else %>
+    <% unless @comment_notifications_available %>
+      <p class="b270-flash alert" style="margin:0">
+        Run the pending Bible270 database migration before changing reflection emails.
+      </p>
+    <% else %>
+      <% if @reader.email.blank? %>
+        <p class="b270-hint">This reader does not currently have an email address.</p>
+      <% end %>
+      <%= form_with url: admin_reader_notifications_path(@reader), method: :patch,
+                    class: "b270-emailform" do %>
+        <%= render "bible270/shared/comment_notification_choices",
+              level: @reader.comment_notification_level,
+              personal_label: "Only replies to their reflections and mentions of them" %>
+        <%= submit_tag 'Save', class: 'b270-btn' %>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>
+
 <div class="b270-panel">
   <h2 class="b270-subhead">Where they are in the plan</h2>
   <%= form_with url: admin_reader_start_path(@reader), method: :patch, class: "b270-startform" do %>

data/app/views/bible270/comments/_form.html.erb

@@ -18,7 +18,18 @@
     </p>
   <% end %>
   <%= f.hidden_field :parent_id %>
-  <%= f.text_area :body, placeholder: comment.parent_id.present? ? "Write your reply…" : "Share a reflection on today's reading…" %>
+  <div class="b270-mention-composer" data-b270-mention-composer
+       data-suggestions-url="<%= mention_suggestions_path %>">
+    <%= f.label :body, (posting_reply ? "Reply" : "Reflection"), class: "b270-sr-only" %>
+    <%= f.text_area :body,
+          placeholder: posting_reply ? "Write your reply…" : "Share a reflection on today's reading…",
+          role: "combobox", autocomplete: "off",
+          aria: { autocomplete: "list", expanded: "false", haspopup: "listbox",
+                  controls: "b270-mention-options" } %>
+    <div class="b270-mention-options" id="b270-mention-options" role="listbox"
+         data-b270-mention-options hidden></div>
+    <p class="b270-sr-only" data-b270-mention-status aria-live="polite"></p>
+  </div>
   <p class="b270-draft-status" data-b270-draft-status aria-live="polite"></p>
   <div class="row">
     <%= f.select :track,

data/app/views/bible270/days/_reading.html.erb

@@ -22,7 +22,7 @@
               <% if signed_in? %>
                 <%= button_to toggle_checkoff_part_path(day, track, index), class: "b270-toggle",
                       params: { checked: part_done ? "0" : "1" },
-                      form: { data: { turbo_stream: true, b270_submit: true,
+                      form: { data: { turbo_stream: true, b270_submit: true, b270_checkoff: true,
                                       b270_pending: "Saving reading…",
                                       b270_success: (part_done ? "Reading marked unread." : "Reading marked read."),
                                       b270_failure: "Couldn’t update that reading. Try again." } },
@@ -46,7 +46,7 @@
       <% if signed_in? %>
         <%= button_to toggle_checkoff_part_path(day, track, 0), class: "b270-toggle",
               params: { checked: done ? "0" : "1" },
-              form: { data: { turbo_stream: true, b270_submit: true,
+              form: { data: { turbo_stream: true, b270_submit: true, b270_checkoff: true,
                               b270_pending: "Saving reading…",
                               b270_success: (done ? "Reading marked unread." : "Reading marked read."),
                               b270_failure: "Couldn’t update that reading. Try again." } },

data/app/views/bible270/days/show.html.erb

@@ -27,6 +27,7 @@
         <%= render "bible270/comments/form", day: @day, comment: @new_comment %>
       </div>
       <%= render "bible270/shared/comment_drafts" %>
+      <%= render "bible270/shared/mention_typeahead" %>
     <% end %>
   </div>
 </div>

data/app/views/bible270/profiles/edit.html.erb

@@ -38,14 +38,13 @@
     <%= render "bible270/shared/passage_source", reader: current_reader %>
 
     <% if @comment_notifications_available %>
-      <div class="b270-field">
-        <span>Email notifications</span>
-        <label class="b270-reminder-optin">
-          <%= hidden_field_tag :notify_on_mention, "0", id: nil %>
-          <%= check_box_tag :notify_on_mention, "1", @notify_on_mention %>
-          <span>Email me about replies and mentions</span>
-        </label>
-      </div>
+      <%= render "bible270/shared/comment_notification_choices",
+            level: @comment_notification_level,
+            personal_label: "Only replies to my reflections and mentions of me" %>
+    <% elsif Bible270.config.mention_notifications %>
+      <p class="b270-flash alert" style="margin:0">
+        Reflection email settings are temporarily unavailable while this installation finishes a database update.
+      </p>
     <% end %>
 
     <% if @daily_reminders_available %>

data/app/views/bible270/shared/_comment_notification_choices.html.erb

@@ -0,0 +1,17 @@
+<fieldset class="b270-field b270-notification-field">
+  <legend>Reflection emails</legend>
+  <div class="b270-notification-choices">
+    <label class="b270-notification-choice">
+      <%= radio_button_tag :comment_notifications, "all", level == "all" %>
+      <span>Every new reflection and reply</span>
+    </label>
+    <label class="b270-notification-choice">
+      <%= radio_button_tag :comment_notifications, "personal", level == "personal" %>
+      <span><%= personal_label %></span>
+    </label>
+    <label class="b270-notification-choice">
+      <%= radio_button_tag :comment_notifications, "none", level == "none" %>
+      <span>None</span>
+    </label>
+  </div>
+</fieldset>

data/app/views/bible270/shared/_interaction_ui.html.erb

@@ -1,5 +1,6 @@
-<script nonce="<%= content_security_policy_nonce %>">
+<script nonce="<%= content_security_policy_nonce %>" data-refresh-path="<%= refresh_session_path %>">
   (() => {
+    const refreshSessionPath = document.currentScript.dataset.refreshPath;
     if (window.Bible270InteractionUI) {
       window.Bible270InteractionUI.reset();
       return;
@@ -30,6 +31,42 @@
       document.querySelectorAll("form[data-b270-submit='true']").forEach(resetForm);
     }
 
+    const SESSION_REFRESH_AFTER = 5 * 60 * 1000;
+    let sessionRefreshedAt = Date.now();
+    let sessionRefresh = null;
+    let hiddenAt = null;
+
+    function updateAuthenticityToken(token) {
+      const meta = document.querySelector("meta[name='csrf-token']");
+      if (meta) meta.content = token;
+      document.querySelectorAll("input[name='authenticity_token']").forEach((input) => {
+        input.value = token;
+      });
+    }
+
+    function refreshSession() {
+      if (sessionRefresh) return sessionRefresh;
+
+      sessionRefresh = fetch(refreshSessionPath, {
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { Accept: "text/plain" }
+      }).then((response) => {
+        const token = response.headers.get("X-CSRF-Token");
+        if (!response.ok || !token) throw new Error("Could not refresh the session");
+
+        updateAuthenticityToken(token);
+        sessionRefreshedAt = Date.now();
+      }).finally(() => {
+        sessionRefresh = null;
+      });
+      return sessionRefresh;
+    }
+
+    function sessionRefreshNeeded() {
+      return Date.now() - sessionRefreshedAt >= SESSION_REFRESH_AFTER;
+    }
+
     let scriptureWindow = null;
     const replacesBackgroundTabs = /iPad|iPhone|iPod/.test(navigator.userAgent) ||
       (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
@@ -62,6 +99,24 @@
     document.addEventListener("submit", (event) => {
       const form = event.target.closest("form[data-b270-submit='true']");
       if (!form) return;
+
+      if (sessionRefresh || sessionRefreshNeeded()) {
+        event.preventDefault();
+        if (form.dataset.b270AwaitingSession === "true") return;
+
+        form.dataset.b270AwaitingSession = "true";
+        const submitter = event.submitter;
+        refreshSession().then(() => {
+          delete form.dataset.b270AwaitingSession;
+          form.requestSubmit(submitter || undefined);
+        }).catch(() => {
+          delete form.dataset.b270AwaitingSession;
+          sessionRefreshedAt = Date.now();
+          form.requestSubmit(submitter || undefined);
+        });
+        return;
+      }
+
       if (form.dataset.b270Submitting === "true") {
         event.preventDefault();
         return;
@@ -77,11 +132,39 @@
       announce(form.dataset.b270Pending || "Saving…", "pending");
     });
 
+    function staleSessionResponse(fetchResponse) {
+      if (!fetchResponse) return false;
+      if (fetchResponse.statusCode === 422) return true;
+
+      return fetchResponse.statusCode === 409 &&
+        fetchResponse.response.headers.get("X-Bible270-Refresh-Session") === "true";
+    }
+
+    document.addEventListener("turbo:before-fetch-response", (event) => {
+      const target = event.target;
+      const form = target.closest && target.closest("form[data-b270-checkoff='true']");
+      const response = event.detail.fetchResponse;
+      if (!form || !staleSessionResponse(response)) return;
+
+      event.preventDefault();
+      if (form.dataset.b270RetriedAfterStaleSession === "true") {
+        window.location.reload();
+        return;
+      }
+
+      form.dataset.b270RetriedAfterStaleSession = "true";
+      resetForm(form);
+      refreshSession().then(() => form.requestSubmit()).catch(() => window.location.reload());
+    });
+
     document.addEventListener("turbo:submit-end", (event) => {
       const form = event.target;
       if (!form.matches("form[data-b270-submit='true']")) return;
 
       resetForm(form);
+      if (form.dataset.b270RetriedAfterStaleSession === "true" &&
+          staleSessionResponse(event.detail.fetchResponse)) return;
+
       if (event.detail.success) {
         announce(form.dataset.b270Success || "Saved.", "success");
       } else {
@@ -89,7 +172,18 @@
       }
     });
 
-    window.addEventListener("pageshow", reset);
+    window.addEventListener("pageshow", (event) => {
+      reset();
+      if (event.persisted) refreshSession().catch(() => {});
+    });
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        hiddenAt = Date.now();
+      } else if (hiddenAt && Date.now() - hiddenAt >= SESSION_REFRESH_AFTER) {
+        refreshSession().catch(() => {});
+        hiddenAt = null;
+      }
+    });
     document.addEventListener("turbo:load", reset);
 
     window.Bible270InteractionUI = { reset };

data/app/views/bible270/shared/_mention_typeahead.html.erb

@@ -0,0 +1,177 @@
+<script nonce="<%= content_security_policy_nonce %>">
+  (() => {
+    if (window.Bible270MentionTypeahead) {
+      window.Bible270MentionTypeahead.reset();
+      return;
+    }
+
+    const cache = new Map();
+
+    function activeToken(textarea) {
+      if (textarea.selectionStart !== textarea.selectionEnd) return null;
+
+      const cursor = textarea.selectionStart;
+      const before = textarea.value.slice(0, cursor);
+      const match = before.match(/(?:^|[^\p{L}\p{N}_@])@([\p{L}\p{N}.'-]{0,61})$/u);
+      if (!match) return null;
+
+      return { start: cursor - match[1].length - 1, end: cursor, query: match[1] };
+    }
+
+    function close(composer, state) {
+      const textarea = composer.querySelector("textarea");
+      const options = composer.querySelector("[data-b270-mention-options]");
+      const status = composer.querySelector("[data-b270-mention-status]");
+      options.hidden = true;
+      options.replaceChildren();
+      textarea.setAttribute("aria-expanded", "false");
+      textarea.removeAttribute("aria-activedescendant");
+      status.textContent = "";
+      state.items = [];
+      state.active = -1;
+      state.token = null;
+    }
+
+    function selectActive(composer, state, index) {
+      if (!state.items.length) return;
+
+      state.active = (index + state.items.length) % state.items.length;
+      const textarea = composer.querySelector("textarea");
+      composer.querySelectorAll("[role='option']").forEach((option, optionIndex) => {
+        const selected = optionIndex === state.active;
+        option.setAttribute("aria-selected", selected ? "true" : "false");
+        if (selected) textarea.setAttribute("aria-activedescendant", option.id);
+      });
+    }
+
+    function insert(composer, state, item) {
+      const textarea = composer.querySelector("textarea");
+      const token = activeToken(textarea) || state.token;
+      if (!token) return close(composer, state);
+
+      const after = textarea.value.slice(token.end);
+      const separator = after === "" || /^[\p{L}\p{N}@]/u.test(after) ? " " : "";
+      textarea.value = `${textarea.value.slice(0, token.start)}${item.handle}${separator}${after}`;
+      const cursor = token.start + item.handle.length + separator.length;
+      textarea.setSelectionRange(cursor, cursor);
+      close(composer, state);
+      textarea.focus();
+      textarea.dispatchEvent(new Event("input", { bubbles: true }));
+    }
+
+    function render(composer, state, token, items) {
+      const textarea = composer.querySelector("textarea");
+      const options = composer.querySelector("[data-b270-mention-options]");
+      const status = composer.querySelector("[data-b270-mention-status]");
+      const current = activeToken(textarea);
+      if (!current || current.start !== token.start || current.query !== token.query) return;
+
+      const safeItems = items.filter((item) => item && typeof item.name === "string" &&
+        typeof item.handle === "string").slice(0, 5);
+      if (!safeItems.length) return close(composer, state);
+
+      options.replaceChildren();
+      state.items = safeItems;
+      state.token = token;
+      safeItems.forEach((item, index) => {
+        const option = document.createElement("button");
+        option.type = "button";
+        option.id = `b270-mention-option-${index}`;
+        option.className = "b270-mention-option";
+        option.setAttribute("role", "option");
+        option.setAttribute("aria-selected", "false");
+        option.textContent = `${item.name}  ${item.handle}`;
+        option.addEventListener("pointerdown", (event) => event.preventDefault());
+        option.addEventListener("click", () => insert(composer, state, item));
+        options.append(option);
+      });
+      options.hidden = false;
+      textarea.setAttribute("aria-expanded", "true");
+      status.textContent = `${safeItems.length} mention suggestion${safeItems.length === 1 ? "" : "s"} available.`;
+      selectActive(composer, state, 0);
+    }
+
+    function request(composer, state, token) {
+      const key = token.query.toLocaleLowerCase();
+      if (cache.has(key)) return render(composer, state, token, cache.get(key));
+
+      if (state.abort) state.abort.abort();
+      state.abort = new AbortController();
+      const url = new URL(composer.dataset.suggestionsUrl, window.location.href);
+      url.searchParams.set("q", token.query);
+      fetch(url, {
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { Accept: "application/json" },
+        signal: state.abort.signal
+      }).then((response) => {
+        if (!response.ok) throw new Error("Mention suggestions unavailable");
+        return response.json();
+      }).then((body) => {
+        const items = Array.isArray(body.suggestions) ? body.suggestions : [];
+        cache.set(key, items);
+        render(composer, state, token, items);
+      }).catch((error) => {
+        if (error.name !== "AbortError") close(composer, state);
+      });
+    }
+
+    function update(composer, state) {
+      const textarea = composer.querySelector("textarea");
+      const token = activeToken(textarea);
+      window.clearTimeout(state.timer);
+      if (!token) return close(composer, state);
+
+      state.timer = window.setTimeout(() => request(composer, state, token), 120);
+    }
+
+    function initialize(composer) {
+      if (composer.dataset.b270MentionReady === "true") return;
+      composer.dataset.b270MentionReady = "true";
+      const textarea = composer.querySelector("textarea");
+      const state = { items: [], active: -1, token: null, timer: null, abort: null };
+
+      textarea.addEventListener("input", () => update(composer, state));
+      textarea.addEventListener("click", () => update(composer, state));
+      textarea.addEventListener("keydown", (event) => {
+        if (!state.items.length) return;
+
+        if (event.key === "ArrowDown") {
+          event.preventDefault();
+          selectActive(composer, state, state.active + 1);
+        } else if (event.key === "ArrowUp") {
+          event.preventDefault();
+          selectActive(composer, state, state.active - 1);
+        } else if (event.key === "Enter" && !event.shiftKey && state.active >= 0) {
+          event.preventDefault();
+          insert(composer, state, state.items[state.active]);
+        } else if (event.key === "Escape") {
+          event.preventDefault();
+          close(composer, state);
+        } else if (event.key === "Tab") {
+          close(composer, state);
+        }
+      });
+      textarea.addEventListener("blur", () => {
+        window.setTimeout(() => {
+          if (!composer.contains(document.activeElement)) close(composer, state);
+        }, 0);
+      });
+    }
+
+    function scan() {
+      document.querySelectorAll("[data-b270-mention-composer]").forEach(initialize);
+    }
+
+    function reset() {
+      cache.clear();
+      scan();
+    }
+
+    scan();
+    new MutationObserver(scan).observe(document.documentElement, { childList: true, subtree: true });
+    window.addEventListener("pageshow", scan);
+    document.addEventListener("turbo:load", reset);
+    window.Bible270MentionTypeahead = { scan, reset };
+  })();
+</script>

data/app/views/bible270/shared/_styles.html.erb

@@ -40,6 +40,11 @@
   .b270-field{display:grid;gap:5px;font-size:12.5px;color:var(--muted)}
   .b270-field input{font:inherit;font-size:15px;padding:10px 12px;border:1px solid var(--line);border-radius:9px;background:#fff;color:var(--ink);width:100%}
   .b270-field input:focus{outline:none;border-color:var(--gold);box-shadow:0 0 0 3px rgba(165,129,44,.13)}
+  .b270-notification-field{margin:0;padding:0;border:0}
+  .b270-notification-field legend{padding:0;margin:0 0 3px}
+  .b270-notification-choices{display:grid;gap:7px}
+  .b270-notification-choice{display:flex;align-items:flex-start;gap:7px;line-height:1.35;cursor:pointer}
+  .b270-field .b270-notification-choice input[type=radio]{width:auto;margin:1px 0 0;padding:0;flex:none;accent-color:var(--gold)}
   .b270-reminder-row{display:flex;align-items:center;gap:12px;width:100%;flex-wrap:wrap}
   .b270-reminder-optin,.b270-reminder-time{display:inline-flex;align-items:center;gap:7px;color:var(--muted);white-space:nowrap}
   .b270-reminder-optin{position:relative;min-width:0}
@@ -247,6 +252,15 @@
   .b270-cdel{font-size:12px;color:var(--oxblood);background:none;border:none;cursor:pointer;padding:0;margin-left:8px}
   .b270-input{width:100%;padding:9px 11px;border:1px solid var(--line);border-radius:9px;background:#fff;font:inherit;font-size:14px;margin-bottom:8px}
   .b270-form textarea{width:100%;font:inherit;font-size:15px;border:1px solid var(--line);border-radius:10px;padding:11px 13px;background:#fff;resize:vertical;min-height:76px}
+  .b270-sr-only{position:absolute!important;width:1px!important;height:1px!important;padding:0!important;margin:-1px!important;overflow:hidden!important;clip:rect(0,0,0,0)!important;white-space:nowrap!important;border:0!important}
+  .b270-mention-composer{position:relative}
+  .b270-mention-options{position:absolute;z-index:30;left:0;right:0;top:calc(100% + 4px);overflow:hidden;
+                        border:1px solid var(--line);border-radius:10px;background:var(--card);box-shadow:var(--shadow)}
+  .b270-mention-options[hidden]{display:none}
+  .b270 .b270-mention-option{display:block;width:100%;min-height:44px;padding:10px 12px;border:0;border-radius:0;
+                             background:var(--card);color:var(--ink);font:inherit;font-size:13px;text-align:left;cursor:pointer}
+  .b270-mention-option+ .b270-mention-option{border-top:1px solid var(--line-soft)}
+  .b270-mention-option:hover,.b270-mention-option[aria-selected=true]{background:var(--paper);color:var(--gold)}
   .b270-draft-status{min-height:16px;margin:4px 0 -4px;font-size:11.5px;color:var(--faint)}
   .b270-form .row{display:flex;align-items:center;gap:10px;margin-top:10px}
   .b270-form .row select{max-width:100%}

data/config/routes.rb

@@ -20,8 +20,9 @@ Bible270::Engine.routes.draw do
   get    'admin',                        to: 'admin#index',            as: :admin
   get    'admin/readers/:id',            to: 'admin#show',             as: :admin_reader
   delete 'admin/readers/:id',            to: 'admin#destroy'
-  patch  'admin/readers/:id/profile',    to: 'admin#update_profile',   as: :admin_reader_profile
-  delete 'admin/readers/:id/avatar',     to: 'admin#remove_avatar',    as: :admin_reader_avatar
+  patch  'admin/readers/:id/profile',    to: 'admin#update_profile', as: :admin_reader_profile
+  patch  'admin/readers/:id/notifications', to: 'admin#update_notifications', as: :admin_reader_notifications
+  delete 'admin/readers/:id/avatar',     to: 'admin#remove_avatar', as: :admin_reader_avatar
   patch  'admin/readers/:id/version',    to: 'admin#update_bible_version', as: :admin_reader_version
   patch  'admin/readers/:id/start',      to: 'admin#update_start',     as: :admin_reader_start
   patch  'admin/readers/:id/through',    to: 'admin#complete_through', as: :admin_reader_through
@@ -45,11 +46,13 @@ Bible270::Engine.routes.draw do
   get 'progress', to: 'readers#progress', as: :progress
 
   get 'community', to: 'readers#index', as: :community
+  get 'mention-suggestions', to: 'readers#mention_suggestions', as: :mention_suggestions, defaults: { format: :json }
   get 'readers/:id', to: 'readers#show', as: :reader
 
   # Built-in OmniAuth sign-in. The request phase (POST <mount>/auth/:provider)
   # is handled by the OmniAuth middleware in the host app, not by these routes.
   get    'sign_in',                 to: 'sessions#new', as: :sign_in
+  get    'session/refresh',         to: 'sessions#refresh', as: :refresh_session
 
   # Email (magic link) sign-in, for readers without a social account.
   post   'sign_in/email',           to: 'sessions#email_link',     as: :email_sign_in_link

data/db/migrate/20260101000018_add_all_comment_notices_to_bible270_readers.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddAllCommentNoticesToBible270Readers < ActiveRecord::Migration[7.0]
+  def change
+    add_column :bible270_readers, :notify_on_all_comments, :boolean, null: false, default: false
+  end
+end

data/lib/bible270/migration_reconciler.rb

@@ -27,6 +27,7 @@ module Bible270
       'AddPassageSourceToBible270Readers' => :check_passage_source,
       'AddDailyRemindersToBible270Readers' => :check_daily_reminders,
       'AddReflectionsSeenAtToBible270Readers' => :check_reflections_seen_at,
+      'AddAllCommentNoticesToBible270Readers' => :check_all_comment_notices,
       'CreateActiveStorageTables' => :check_active_storage
     }.freeze
 
@@ -190,6 +191,10 @@ module Bible270
       table_missing(:bible270_readers, columns: %i[reflections_seen_at])
     end
 
+    def check_all_comment_notices
+      table_missing(:bible270_readers, columns: %i[notify_on_all_comments])
+    end
+
     # The Bible270 installer can install Active Storage for reader avatars. A
     # copied database can therefore have the same timestamp mismatch for Rails'
     # generated Active Storage migration as it has for the engine migrations.

data/lib/bible270/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bible270
-  VERSION = '1.1.6'
+  VERSION = '1.2.0'
 end

data/lib/generators/bible270/install/install_generator.rb

@@ -517,7 +517,7 @@ module Bible270
             # Readers choose an opt-in time only when enabled. This application owns
             # scheduling: run `bin/rails bible270:reminders:send` every 15 minutes.
             config.daily_reminders = false
-            config.mention_notifications = true # direct replies and @mentions; readers may opt out
+            config.mention_notifications = true # reflection/reply emails; readers choose the scope
             # config.mailer_host = 'example.com' # links back to the day and profile
 
             # --- Reading links --------------------------------------------------------

data/lib/generators/bible270/install/templates/bible270.rb.tt

@@ -60,7 +60,7 @@ Bible270.configure do |config|
   # Readers choose an opt-in time on their profile only when this is enabled.
   # The host app owns scheduling: run `bin/rails bible270:reminders:send` every 15 minutes.
   config.daily_reminders = false
-  config.mention_notifications = true # direct replies and @mentions; readers may opt out
+  config.mention_notifications = true # reflection/reply emails; readers choose the scope
   # config.mailer_host = "example.com"       # required for day/profile links in email
 
   # --- Reading links ---------------------------------------------------------

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bible270
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew vonderLuft
@@ -137,12 +137,14 @@ files:
 - app/views/bible270/readers/show.html.erb
 - app/views/bible270/sessions/new.html.erb
 - app/views/bible270/shared/_comment_drafts.html.erb
+- app/views/bible270/shared/_comment_notification_choices.html.erb
 - app/views/bible270/shared/_day_index.html.erb
 - app/views/bible270/shared/_footer.html.erb
 - app/views/bible270/shared/_grid_legend.html.erb
 - app/views/bible270/shared/_header.html.erb
 - app/views/bible270/shared/_interaction_status.html.erb
 - app/views/bible270/shared/_interaction_ui.html.erb
+- app/views/bible270/shared/_mention_typeahead.html.erb
 - app/views/bible270/shared/_nav_links.html.erb
 - app/views/bible270/shared/_passage_source.html.erb
 - app/views/bible270/shared/_progress.html.erb
@@ -170,6 +172,7 @@ files:
 - db/migrate/20260101000015_add_passage_source_to_bible270_readers.rb
 - db/migrate/20260101000016_add_daily_reminders_to_bible270_readers.rb
 - db/migrate/20260101000017_add_reflections_seen_at_to_bible270_readers.rb
+- db/migrate/20260101000018_add_all_comment_notices_to_bible270_readers.rb
 - lib/bible270.rb
 - lib/bible270/avatars.rb
 - lib/bible270/configuration.rb