bible270 1.16.0 → 1.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +62 -33
  3. data/README.md +144 -59
  4. data/Rakefile +3 -2
  5. data/app/controllers/bible270/admin_controller.rb +152 -33
  6. data/app/controllers/bible270/admin_roles_controller.rb +50 -0
  7. data/app/controllers/bible270/admin_scripture_frames_controller.rb +89 -0
  8. data/app/controllers/bible270/application_controller.rb +18 -2
  9. data/app/controllers/bible270/checkoffs_controller.rb +38 -9
  10. data/app/controllers/bible270/readers_controller.rb +1 -1
  11. data/app/controllers/bible270/scripture_frames_controller.rb +16 -0
  12. data/app/helpers/bible270/plan_helper.rb +4 -4
  13. data/app/mailers/bible270/notice_mailer.rb +2 -2
  14. data/app/models/bible270/checkoff.rb +69 -3
  15. data/app/models/bible270/participation.rb +71 -0
  16. data/app/models/bible270/plan_run.rb +121 -0
  17. data/app/models/bible270/reader.rb +142 -24
  18. data/app/models/bible270/scripture_frame.rb +48 -0
  19. data/app/models/bible270/setting.rb +13 -4
  20. data/app/views/bible270/admin/_reader_list.html.erb +55 -0
  21. data/app/views/bible270/admin/_scripture_frames.html.erb +34 -0
  22. data/app/views/bible270/admin/_scripture_text.html.erb +11 -0
  23. data/app/views/bible270/admin/index.html.erb +64 -49
  24. data/app/views/bible270/admin/show.html.erb +117 -54
  25. data/app/views/bible270/admin_scripture_frames/_form.html.erb +72 -0
  26. data/app/views/bible270/admin_scripture_frames/edit.html.erb +4 -0
  27. data/app/views/bible270/admin_scripture_frames/new.html.erb +4 -0
  28. data/app/views/bible270/days/_day_progress.html.erb +2 -2
  29. data/app/views/bible270/days/_reading.html.erb +5 -4
  30. data/app/views/bible270/profiles/edit.html.erb +14 -12
  31. data/app/views/bible270/readers/show.html.erb +1 -1
  32. data/app/views/bible270/shared/_admin_confirmations.html.erb +16 -0
  33. data/app/views/bible270/shared/_admin_reader_list_ui.html.erb +49 -0
  34. data/app/views/bible270/shared/_day_completion.html.erb +13 -0
  35. data/app/views/bible270/shared/_day_completion_dove.html.erb +4 -3
  36. data/app/views/bible270/shared/_day_completion_ui.html.erb +152 -0
  37. data/app/views/bible270/shared/_day_index.html.erb +2 -1
  38. data/app/views/bible270/shared/_header.html.erb +12 -4
  39. data/app/views/bible270/shared/_interaction_ui.html.erb +2 -62
  40. data/app/views/bible270/shared/_scripture_frame.html.erb +14 -0
  41. data/app/views/bible270/shared/_scripture_frame_ui.html.erb +247 -0
  42. data/app/views/bible270/shared/_scripture_library_ui.html.erb +34 -0
  43. data/app/views/bible270/shared/_styles.html.erb +154 -17
  44. data/app/views/layouts/bible270/application.html.erb +8 -0
  45. data/config/routes.rb +9 -2
  46. data/config/scripture_frames.yml +161 -0
  47. data/db/migrate/20260101000024_create_bible270_plan_runs.rb +60 -0
  48. data/db/migrate/20260101000025_add_admin_to_bible270_readers.rb +7 -0
  49. data/db/migrate/20260101000026_add_revert_to_bible270_plan_runs.rb +8 -0
  50. data/db/migrate/20260101000027_create_bible270_scripture_frames.rb +16 -0
  51. data/lib/bible270/configuration.rb +17 -4
  52. data/lib/bible270/migration_reconciler.rb +91 -8
  53. data/lib/bible270/reader_consistency.rb +8 -4
  54. data/lib/bible270/reader_progress_report.rb +2 -1
  55. data/lib/bible270/scripture_frames.rb +226 -0
  56. data/lib/bible270/version.rb +1 -1
  57. data/lib/bible270.rb +1 -0
  58. data/lib/generators/bible270/install/templates/bible270.rb.tt +8 -1
  59. metadata +26 -1
data/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![Rails CI](https://github.com/avonderluft/bible270/actions/workflows/railsci.yml/badge.svg)](https://github.com/avonderluft/bible270/actions/workflows/railsci.yml) [![Test Coverage](https://img.shields.io/coverallsCoverage/github/avonderluft/bible270?branch=main&cacheSeconds=300)](https://coveralls.io/github/avonderluft/bible270?branch=main) [![Gem Version](https://img.shields.io/gem/v/bible270)](https://rubygems.org/gems/bible270) [![Downloads](https://img.shields.io/gem/dt/bible270)](https://rubygems.org/gems/bible270) [![GitHub Release Date - Published_At](https://img.shields.io/github/release-date/avonderluft/bible270?label=last%20release&color=seagreen)](https://github.com/avonderluft/bible270/releases)
4
4
 
5
- A mountable **Rails engine** for a 270-day (9-month) Bible reading plan. Readers check off readings, share reflections, and follow one another's progress.
5
+ A **Rails engine** for a 270-day (9-month) Bible reading plan. Readers check off readings, share reflections, and follow one another's progress.
6
6
 
7
7
  Created for [Kingdom Movement School of Ministry](https://www.kmsm.life/) and designed to work with [ComfyMiddleSeat](https://github.com/avonderluft/comfy-middle-seat) CMS, it also works in other Rails apps.
8
8
 
@@ -20,17 +20,17 @@ By default, psalms of 25 verses or fewer stay whole. Longer chapters use selecte
20
20
 
21
21
  The Old Testament and Revelation 22 finish on day 270 alongside Psalm 1. Daily readings average about 115 verses (range 76–166).
22
22
 
23
- `Bible270::Plan` generates the schedule deterministically from `Bible270::Versification`; the schedule is not stored in the database. **Progress and reflections are public.**
23
+ `Bible270::Plan` generates the schedule from `Bible270::Versification`, not the database. **Progress and reflections are public.**
24
24
 
25
- Signed-in readers see a small progress bar and completed-day count on Community, including in non-admin preview. The list stays alphabetical; only fully completed days count. A thin line marks today on each reader's active schedule; undated, future, and ended schedules have no marker. Visitors see names and join dates; management links and written ahead/behind status remain admin-only.
25
+ Community lists readers alphabetically. Signed-in readers, including admins in non-admin view, see progress bars and completed-day counts. A line marks today on active schedules, except undated, future, or ended ones. Visitors see names and join dates; management links and ahead/behind labels are admin-only.
26
26
 
27
27
  ## Requirements
28
28
 
29
29
  - **Ruby >= 3.2** and a **Rails >= 7.2** host app. CI covers selected combinations through Ruby 4.0 / Rails 8.1; check your host's dependencies before upgrading Ruby.
30
30
  - Turbo JavaScript for check-offs without a page reload. The gem includes `turbo-rails`; ordinary HTML forms remain available without JavaScript.
31
- - For picture uploads and backfills: **Active Storage** and **libvips** with PNG, JPEG, GIF, and WebP support on every upload/backfill host. Install libvips with, for example, `sudo apt-get install libvips-tools` on Ubuntu or `sudo pacman -S libvips` on Arch. The gem supplies `image_processing` and `ruby-vips`; native processing loads only when optimizing an image, not when displaying existing or provider avatars.
31
+ - For picture uploads and backfills: **Active Storage** and **libvips** with PNG, JPEG, GIF, and WebP support on each upload/backfill host. Install with `sudo apt-get install libvips-tools` (Ubuntu) or `sudo pacman -S libvips` (Arch). The gem includes `image_processing` and `ruby-vips`; libvips loads only for optimization, not avatar display.
32
32
 
33
- JavaScript controls show pending, success, and retry feedback. Repeated check-off and like requests converge on the requested state rather than reversing it.
33
+ JavaScript controls show pending, success, and retry feedback. Repeating a request keeps the intended check-off or like state.
34
34
 
35
35
  ## Install
36
36
 
@@ -65,9 +65,7 @@ The interactive generator:
65
65
  4. Writes `config/initializers/bible270.rb` and, for social sign-in, `omniauth.rb`.
66
66
  5. Adds `mount Bible270::Engine, at: Bible270.config.mount_at` to your routes.
67
67
 
68
- Defaults use `/daily-bread` with email and GitHub sign-in. **You must still configure mail delivery, provider credentials, and OAuth callback URLs** as listed by the generator. Migrations run before the initializers are written.
69
-
70
- Copied migrations belong to your app. The engine does not also add its migration directory to your app's migration paths.
68
+ Defaults use `/daily-bread` with email and GitHub sign-in. **Configure mail delivery, provider credentials, and OAuth callback URLs** as listed by the generator. Migrations run before initializers are written; the copied migrations belong to your app, with no duplicate engine migration path.
71
69
 
72
70
  For non-interactive setup:
73
71
 
@@ -88,7 +86,7 @@ bin/rails generate bible270:install --defaults \
88
86
  | `--migrate` / `--no-migrate` | Run or skip migrations |
89
87
  | `--active-storage` / `--no-active-storage` | Install or skip missing Active Storage tables |
90
88
 
91
- Re-running skips existing strategy gems and reuses the engine mount, moving it above catch-all routes if needed. Rails prompts before overwriting an initializer. If you skip bundling or migrations, complete them before using the affected features.
89
+ Re-running skips existing strategy gems and reuses the mount, moving it above catch-all routes if needed. Rails prompts before overwriting initializers. Complete any skipped bundling or migrations before using affected features.
92
90
 
93
91
  <details>
94
92
  <summary>Manual installation</summary>
@@ -125,7 +123,7 @@ Configure Action Mailer delivery and, if needed, [OmniAuth](#social-sign-in).
125
123
 
126
124
  ### Upgrading
127
125
 
128
- No generator re-run is needed:
126
+ **Back up the host database before migrating.** From the host Rails app (no generator re-run needed):
129
127
 
130
128
  ```bash
131
129
  bundle update bible270
@@ -133,7 +131,12 @@ bin/rails bible270:install:migrations # skips existing copies
133
131
  bin/rails db:migrate
134
132
  ```
135
133
 
136
- Review the [changelog](CHANGELOG.md) before deploying. Copy and run **all current migrations**, not just those for a feature you use; feature-specific migration notes appear below.
134
+ Review the [changelog](CHANGELOG.md) before deploying and run **all current migrations**, not just those for features you use.
135
+
136
+ - `20260101000024` saves existing readers and progress as the first run. **This migration cannot be rolled back without losing run history.** Keep a pre-migration backup for recovery.
137
+ - `20260101000025` enables admin roles in the panel. Configured admins become Site-admins and keep their access.
138
+ - `20260101000026` saves restart snapshots so future new runs can be reverted.
139
+ - `20260101000027` stores admin-added Scripture frame texts.
137
140
 
138
141
  **Schedule changes do not remap existing day-based check-offs.** Compared with 1.13.3, the current default Psalms/Proverbs assignments differ on days 112–113 and 117–270, including the closing Psalm 1 reading. Review the effect on an active group before upgrading.
139
142
 
@@ -145,14 +148,14 @@ A copied database may already contain the tables but have migration versions tha
145
148
  bin/rails bible270:migrations:reconcile
146
149
  ```
147
150
 
148
- The task recognizes Bible270 migrations and the related generated Active Storage migration by name, then checks tables, columns, indexes, and foreign keys. An existing table alone is not sufficient. **Review the preview and back up the database** before applying:
151
+ The task matches Bible270 and generated Active Storage migrations by name, then checks tables, columns, indexes, and foreign keys—not just table existence. **Review the preview and back up the database** before applying:
149
152
 
150
153
  ```bash
151
154
  APPLY=1 bin/rails bible270:migrations:reconcile
152
155
  bin/rails db:migrate
153
156
  ```
154
157
 
155
- Preview writes nothing. Apply only records verified local versions in `schema_migrations`; it does not alter application tables. Missing changes remain pending for `db:migrate`.
158
+ Preview writes nothing. Apply records verified versions in `schema_migrations`, without changing application tables. Missing changes remain pending for `db:migrate`.
156
159
 
157
160
  ## Mount point
158
161
 
@@ -192,10 +195,10 @@ Bible270.configure do |config|
192
195
  end
193
196
  ```
194
197
 
195
- - Tokens are 256-bit, URL-safe, single-use, and expire after 20 minutes by default. Conditional updates prevent double claims.
196
- - Only a **SHA-256 token digest** is stored, not the raw token or a password. Token records still contain personal data such as email addresses.
197
- - Valid-address requests receive the same “Check your inbox” response whether known, unknown, or rate-limited, avoiding disclosure through that message.
198
- - Names come from the reader, falling back to the email address (`mary.anne.smith@…` → “Mary Anne Smith”). Email readers use `provider: "email"` in the same identity model as OmniAuth readers.
198
+ - Links are single-use and expire after 20 minutes by default. Tokens are 256-bit and URL-safe.
199
+ - Only a **SHA-256 token digest** is stored, not the raw token or a password. Records still contain personal data, including email addresses.
200
+ - All valid-address requests get “Check your inbox,” whether known, unknown, or rate-limited, to avoid revealing accounts.
201
+ - Names come from the reader or email address (`mary.anne.smith@…` → “Mary Anne Smith”). Email readers use `provider: "email"`.
199
202
  - Schedule `Bible270::SignInToken.sweep!` to remove expired or consumed records older than seven days by default.
200
203
 
201
204
  ### Social sign-in
@@ -245,7 +248,7 @@ end
245
248
 
246
249
  ## Admin panel
247
250
 
248
- The panel at `<mount>/admin` returns **404** unless you explicitly authorize administrators:
251
+ The panel at `<mount>/admin` returns **404** for unauthorized readers. Configure Site-admins in the host initializer:
249
252
 
250
253
  ```ruby
251
254
  config.admin_emails = %w[andrew@example.org]
@@ -253,17 +256,25 @@ config.admin_emails = %w[andrew@example.org]
253
256
  config.admin_resolver = ->(reader) { reader.email.to_s.end_with?('@example.org') }
254
257
  ```
255
258
 
256
- Authorized readers get an Admin link. **View as non-admin** hides admin-only details and disables admin actions for the current session. You stay signed in as yourself; your check-offs and reflections still work. The Admin tab remains available with **Return to admin view**. This does not change roles or affect other sessions, and signing in again restores admin view.
259
+ The `admin_resolver` callback takes precedence over `admin_emails`.
260
+
261
+ - **Site-admins** can grant or revoke admin access on any reader's Admin page, including alumni, and delete other admins. Configured Site-admins cannot be demoted or deleted in the UI.
262
+ - **Admins** manage readers but cannot change roles or delete privileged readers.
263
+ - Roles persist across runs, independently of **Active/Alumni** status. Site-admins can change their own membership status.
264
+
265
+ Authorized readers get an **Admin** link. **View as non-admin** hides admin details and disables all administration for this session, including role and membership changes. You remain signed in; reflections and active check-offs still work. Use **Return to admin view** in the Admin tab or sign in again to restore access. Roles and other sessions are unchanged.
257
266
 
258
267
  The panel supports:
259
268
 
260
- - Sorting readers by name, completed days, activity, or consistency, with **Reader Stats** following the selected sort.
261
- - Changing reader profiles, themes, and notification preferences. Another reader's theme does not change your own.
262
- - Moving a reader to a day by adjusting their start date; check-offs remain tied to day numbers.
263
- - Setting progress exactly through day N, **clearing completions after N**, or toggling individual days.
264
- - Removing a reader **and all their check-offs and reflections**.
265
- - Moderating reflections at `<mount>/admin/comments`: hide reversibly or delete. Reflections are public immediately, without prior approval.
266
- - Sending individually addressed broadcasts to all readers with email addresses or only administrators.
269
+ - Sort active readers by name, completed days, activity, or consistency; **Reader Stats** follows the same sort.
270
+ - Edit profiles, themes, notification preferences, and the completion-dove setting.
271
+ - Adjust active readers' start dates; check-offs stay tied to day numbers.
272
+ - Set progress through day N, **clearing completions after N**, or toggle individual days.
273
+ - Mark readers as alumni, reactivate them, and view past-run history.
274
+ - Delete unprotected readers **and all their check-offs and reflections across runs**.
275
+ - Hide (reversibly) or delete reflections at `<mount>/admin/comments`. Posts are public immediately, without approval.
276
+ - Manage [Scripture frame](#scripture-frame) texts.
277
+ - Send individually addressed email: **Write to everyone** reaches active readers; **Write to all admins** includes alumni admins. Both require an email address.
267
278
 
268
279
  To print a progress report ordered by completed days:
269
280
 
@@ -271,7 +282,33 @@ To print a progress report ordered by completed days:
271
282
  docker compose exec -e RAILS_ENV=production rails bin/rails bible270:readers:list
272
283
  ```
273
284
 
274
- The report shows completed days, last activity, and calendar status: on track, ahead, behind, or undated.
285
+ The report defaults to active readers, showing completed days, last activity, and status: on track, ahead, behind, or undated.
286
+
287
+ ### Runs and alumni
288
+
289
+ At the bottom of Admin, enter a start date, choose **Start a new run**, and accept the confirmation prompt. This:
290
+
291
+ - Archives the current memberships and freezes their calendars and statistics.
292
+ - Makes all current Admins and Site-admins active in the new run, with zero progress and no personal start date. Previous progress stays in read-only history.
293
+ - Leaves other readers as alumni and opens enrollment, even if the installation started with `config.enrollment_open = false`.
294
+ - Keeps reader accounts, photos, check-offs, reflections, replies, likes, and admin roles.
295
+
296
+ **Revert to previous run** restores saved memberships (including admins), personal dates, the shared-date override, and enrollment settings. Newcomers become alumni; both runs' progress and discussions remain, and roles do not change. Confirm to proceed. Revert requires a restart made after migration `20260101000026`. Without a saved date override, the current site configuration applies.
297
+
298
+ Alumni can sign in, view Community's **active-reader list**, and post, reply to, and like reflections. Earlier reflections remain visible under the same moderation rules. Archived check-offs are read-only and excluded from current statistics and daily completer lists.
299
+
300
+ **Show / Hide Active Readers** starts expanded and remembers your choice for the current tab's sign-in session. Sorting and Reader Stats remain accessible when collapsed.
301
+
302
+ **Show / Hide Alumni** starts collapsed. Alumni use the selected sort and frozen statistics; each row has a confirmed **Make Active** button. Reader Stats includes active readers only.
303
+
304
+ Only admins reactivate alumni; signing in or posting does not re-enroll them:
305
+
306
+ - **New run:** zero completions and no personal start date; old history stays intact.
307
+ - **Same run:** progress and personal start date are preserved.
308
+
309
+ Each reader's **Past runs / history** table shows read-only start/end dates, archive date, and completed days.
310
+
311
+ Admin templates include `bible270/shared/admin_confirmations`, even with custom layouts. Keep this partial in host template overrides; no layout include is needed.
275
312
 
276
313
  ### Consistency ranking
277
314
 
@@ -279,24 +316,24 @@ Consistency is the average end-of-day score on a dated schedule:
279
316
 
280
317
  `100 + 5 × min(days ahead, 7) − 10 × days behind`
281
318
 
282
- A score of 100 is an average on-track baseline, not a percentage. Negative scores display as `0` but retain their true value for ranking. Scores, on-track/ahead percentages, and evaluated-day counts appear for every Admin sort; sorting by consistency also shows the scoring explanation and adds a **Rank** column to Reader Stats.
319
+ A score of 100 means on track on average, not 100%. Negative scores display as `0` but keep their true ranking. All Admin sorts show scores, on-track/ahead percentages, and evaluated-day counts; consistency sort adds an explanation and **Rank** column.
283
320
 
284
- - Evaluation runs from the later of plan start or account creation through the earlier of yesterday or plan end, in the plan's time zone. Late enrollment does not reset the scheduled day.
321
+ - Evaluation runs from the later of plan start or joining the run (`joined_at`) through the earlier of yesterday or plan end, in the plan's time zone. Archives use frozen dates and stop before the archive date. Joining late does not reset the scheduled day.
285
322
  - A day counts when all required readings are checked off, using the latest check-off timestamp. Early completions carry forward; today's catch-up does not improve previous evenings.
286
323
  - Readers with seven or more evaluated evenings rank first, then **Provisional** readers with one to six, then **Not ranked** readers with none.
287
- - Within each ranked group, ordering uses unrounded score, on-track/ahead percentage, and evaluated days. Equal metrics share competition ranks (`1, 1, 1, 4`); name and ID order ties. Unranked readers show a dash.
324
+ - Rank uses unrounded score, then on-track/ahead percentage, then evaluated days. Ties share ranks (`1, 1, 1, 4`), ordered by name and ID. Unranked readers show a dash.
288
325
 
289
- This is **reconstructed history, not an audit log**. Rechecking readings, bulk progress edits, or start-date changes can alter scores. Timestamps record when completion was entered, not necessarily when reading occurred. No snapshot job or additional migration is required.
326
+ This is **reconstructed history, not an audit log**. Rechecking readings, bulk progress edits, or date changes can alter active-run scores. Completion timestamps record entry time, not necessarily reading time. No snapshot job is required.
290
327
 
291
328
  ## Reflections and notifications
292
329
 
293
- The Reflections page groups conversations by their latest approved reply, with day/author filters, pagination, and activity indicators since the reader's previous visit.
330
+ Reflections are ordered by latest approved reply, with day/author filters, page navigation, and new-activity indicators.
294
331
 
295
- Drafts stay in the current browser for up to **30 days** and clear after a successful post. If storage is blocked or full, a warning appears but posting still works. On shared devices, clear browser storage to remove saved drafts.
332
+ Drafts stay in this browser for up to **30 days**, clearing after a successful post. Blocked or full storage triggers a warning but does not prevent posting. **Clear browser storage on shared devices** to remove drafts.
296
333
 
297
- Typing `@` offers up to five unambiguous reader handles; manual mentions work without JavaScript. **Formatting** opens tools for bold, italic, quotations, lists, links, and YouTube videos. **Preview** uses the same server-side sanitizer as posted content. Existing reflections remain literal plain text until deliberately converted; without the `body_format` migration (`20260101000021`), the composer falls back to plain text.
334
+ Type `@` for up to five reader-handle suggestions; manual mentions work without JavaScript. **Formatting** adds bold, italic, quotations, lists, links, and YouTube videos. **Preview** applies the same safety filtering as posts. Existing reflections stay plain text unless converted; without migration `20260101000021` (`body_format`), the composer also uses plain text.
298
335
 
299
- When `config.mention_notifications` is enabled, readers can choose email for every new reflection/reply, only direct replies and mentions, or none. Admins can change the same preference. Broad notices use BCC; direct notices are individually addressed.
336
+ With `config.mention_notifications` enabled, readers or admins can choose email for all reflections/replies, only direct replies and mentions, or none. Broad notices use BCC and exclude alumni. Personal notices are individually addressed and still reach opted-in alumni; saved preferences are kept.
300
337
 
301
338
  Migration `20260101000018` adds broad notifications without changing existing choices; `20260101000022` makes them the default for new readers only. Follow [Upgrading](#upgrading) to install these and the visit-tracking migration (`20260101000017`).
302
339
 
@@ -320,11 +357,43 @@ The **Video** button accepts YouTube watch, share (`youtu.be`), Shorts, live, an
320
357
  [YouTube video](https://www.youtube.com/watch?v=aB3_dE-fG12 "bible270-video")
321
358
  ```
322
359
 
323
- Preview and posted content show **View video**, or **View video ‘Name’**. No remote thumbnail or player loads until the reader requests playback. The player uses `www.youtube-nocookie.com` without autoplay; **loading it shares the reader's IP address and request metadata with YouTube**. Privacy-enhanced mode is not anonymous playback.
360
+ Preview and posts show **View video** or **View video ‘Name’**. No remote thumbnail or player loads until playback is requested. The player uses `www.youtube-nocookie.com` without autoplay. **Loading it shares the reader's IP address and request metadata with YouTube**; privacy-enhanced mode is not anonymous.
361
+
362
+ **Open on YouTube** works without JavaScript or when embeds are blocked, opening a new tab with `rel="nofollow ugc noopener"`. Emails use ordinary links with the optional name. Unmarked or unsupported links stay links; start times and playlists are not retained. No API key, extra gem, or migration is needed; uploads are not supported.
363
+
364
+ For a host Content Security Policy (CSP), add `https://www.youtube-nocookie.com` to existing **`frame-src`**; do not replace the policy or allow arbitrary frames. Custom layouts must render `bible270/shared/video_embeds` once.
365
+
366
+ ## Scripture frame
367
+
368
+ Hover over the bread icon for **3 seconds**, or open it immediately by tap, click, or Enter/Space. The random, theme-matched frame closes when you leave a hover preview, press Escape, click outside, or select the bread again.
369
+
370
+ Completing a day shows a random frame followed by the optional dove; both fade out together. Disabling the dove keeps the frame. Reduced-motion users see a static frame, and Escape dismisses the sequence.
371
+
372
+ The [bundled YAML catalog](config/scripture_frames.yml) supplies the defaults in biblical order. Manage texts under **Admin → Scripture frames**:
373
+
374
+ - **Add text:** enter Reference, Translation, and the required Text (up to 4,000 characters). Line breaks are preserved; Bible translation credits are automatic.
375
+ - For non-Scripture text, select **Other quotation** under Translation and enter **Author / source** and the quote. No Bible credit is attached.
376
+ - Edit or delete custom texts; enable or disable any text. Disabled texts remain previewable but do not appear in random frames.
377
+
378
+ Custom passages come first in biblical order, then quotations and defaults. Hover or focus a heading to preview; select it to expand. Use text you have permission to reproduce.
379
+
380
+ **Custom texts are stored in the database and supplement, not change, the YAML catalog.** Texts and enable/disable choices persist across runs. Defaults start enabled and cannot be edited or deleted. Custom texts require migration `20260101000027`.
381
+
382
+ **TODO:** Add [YouVersion API](https://developers.youversion.com/) lookup by reference and translation, with server-side credentials and required licensing and attribution.
383
+
384
+ Hosts can optionally replace the default catalog:
385
+
386
+ ```ruby
387
+ config.scripture_frames_path = Rails.root.join('config/bible270_scripture_frames.yml')
388
+ ```
389
+
390
+ Use the bundled format: entries with a unique slug `id`, `reference`, `translation`, `text`, and optional `attribution`. Keep one consistent credit per translation. Catalog translations join the built-in Admin choices. Custom texts still supplement the catalog; invalid or unreadable catalogs fall back to the bundled defaults.
324
391
 
325
- An **Open on YouTube** link remains available without JavaScript or when embedding is blocked. It opens a new tab with `rel="nofollow ugc noopener"`. Notification emails use ordinary links and preserve the optional name. Unmarked or unsupported links stay links; start times and playlist parameters are not retained. No API key, upload support, extra gem, or additional migration is needed.
392
+ Custom layouts that include the header must also render the shared styles and this partial once near the end of `<body>`:
326
393
 
327
- For a host Content Security Policy, add `https://www.youtube-nocookie.com` to the existing **`frame-src`** directive. Do not replace the policy or allow arbitrary frames. Custom engine layouts must also render `bible270/shared/video_embeds` once alongside the other shared scripts.
394
+ ```erb
395
+ <%= render "bible270/shared/scripture_frame_ui" %>
396
+ ```
328
397
 
329
398
  ## Themes
330
399
 
@@ -357,7 +426,7 @@ config.allow_reader_start_date = true
357
426
  | a date | false | Shared date for everyone; stored personal dates ignored |
358
427
  | nil | false | Fully undated |
359
428
 
360
- Dated plans show dates, a **Today** badge, and a “Go to today” link. Admins can override the shared `config.start_date` without deploying, or reset it to the configured value. Shared-date changes immediately remap dates, Today, and reminders for readers on that calendar. Personal calendars can also be adjusted. **Check-offs and reflections stay tied to day numbers.**
429
+ Dated active plans show dates, a **Today** badge, and “Go to today.” Admins can override the shared `config.start_date` without deploying, reset it, or adjust personal calendars. Changes immediately shift dates, Today, and reminders for affected active readers. **Check-offs and reflections stay tied to day numbers.** Archives keep their frozen calendar (including undated ones), with no Today marker; later date or calendar-setting changes do not affect them. Changing the start date does not [start a new run](#runs-and-alumni).
361
430
 
362
431
  Date helpers work without Rails:
363
432
 
@@ -371,7 +440,7 @@ Bible270::Plan.before_start?(date, start)
371
440
 
372
441
  ## Daily reading reminders
373
442
 
374
- Reminders require both host enablement and reader opt-in; both default to off. Readers choose a time in Profile (default `08:00`, quarter-hour choices). Existing off-quarter times remain available until changed. Times use the **plan's time zone**, shown in Profile, not the device's zone.
443
+ Reminders require host enablement and reader opt-in; both default to off. Profile offers quarter-hour times (default `08:00`), preserving older off-quarter choices until changed. Times use the **plan's time zone**, shown in Profile, not the device's.
375
444
 
376
445
  ```ruby
377
446
  # config/initializers/bible270.rb
@@ -403,7 +472,7 @@ For Docker Compose, use `pwd` in the Compose directory and `command -v docker` t
403
472
 
404
473
  `-T` disables the interactive terminal that cron cannot provide. Verify with `crontab -l` and check the log after the next interval. **Run one scheduler per database**, not one per web container.
405
474
 
406
- The task sends inline with `deliver_now` on the first run at or after the chosen local time and records the sent date only after successful delivery. It skips readers already sent that date, undated or out-of-range calendars, completed days, blank email addresses, and readers not opted in. Individual failures are logged without stopping other deliveries; each run prints the delivered count.
475
+ The task uses `deliver_now` on the first run at or after the chosen local time, recording the sent date only after success. It skips alumni, already-sent dates, undated or out-of-range calendars, completed days, blank emails, and readers not opted in. Failures are logged without stopping other deliveries; each run prints a delivered count.
407
476
 
408
477
  ## Avatar optimization
409
478
 
@@ -411,7 +480,9 @@ Profile and Admin uploads produce a **256×256 static WebP at quality 85**: auto
411
480
 
412
481
  Limits are **2 MiB** by default (`config.avatar_max_bytes`) and **40 million pixels** in the selected frame/container canvas. The pixel limit bounds dimensions, not total processor memory. Processing or storage failure leaves the previous picture and profile details unchanged.
413
482
 
414
- The current original, **including its metadata**, remains in `avatar`; the display image is stored as `avatar_thumbnail`. This retains a source for reprocessing, not a picture history, and increases storage even though downloads shrink. Removing or replacing a picture detaches the old pair; **keep Active Job workers running** for Active Storage purge jobs. No new migration is needed if Active Storage is already installed.
483
+ The original, **including its metadata**, stays in `avatar`; `avatar_thumbnail` holds the display image. This allows reprocessing, not picture history: storage grows even as downloads shrink. Replacing or removing a picture detaches the old pair; **keep Active Job workers running** for purge jobs. No migration is needed if Active Storage is installed.
484
+
485
+ On desktop, hover over an avatar for **3 seconds** to preview the uncropped original, fitted to the viewport with a 200 ms fade. The original is fetched on demand; touch behavior is unchanged.
415
486
 
416
487
  ### Backfill existing uploads
417
488
 
@@ -428,12 +499,12 @@ RAILS_ENV=production bundle exec rake bible270:avatars:optimize BATCH_SIZE=100
428
499
  RAILS_ENV=production bundle exec rake bible270:avatars:optimize FORCE=1
429
500
  ```
430
501
 
431
- - Skips current thumbnails, protects concurrent avatar changes, continues after individual failures, and exits nonzero if any fail. Correct failed files, limits, storage access, or processor dependencies, then rerun.
432
- - Reports reader IDs, counts, and original/optimized **display-byte totals**, not total storage savings.
433
- - `BATCH_SIZE` defaults to 100 (allowed: 1–1000). Dry-run checks eligibility only, not file availability or decodability.
434
- - Reads originals and writes thumbnails to configured storage; remote storage may incur request/transfer costs. It does not fetch provider avatars or change unrelated host attachments.
502
+ - Skips current thumbnails, protects concurrent avatar changes, and continues after failures, exiting nonzero if any fail. Fix files, limits, storage access, or processor dependencies, then rerun.
503
+ - Reports reader IDs, counts, and original/optimized **display-byte totals**, not storage savings.
504
+ - `BATCH_SIZE` defaults to 100 (range: 1–1000). Dry-run checks eligibility, not file availability or decodability.
505
+ - Reads originals and writes thumbnails; remote storage may incur request/transfer costs. Provider avatars and unrelated host attachments are untouched.
435
506
 
436
- Host upload code should use `reader.attach_avatar(upload)` or `Bible270::AvatarImages.update!(reader, attributes, upload: upload)`. Direct Active Storage attachment bypasses optimization. **Uploads and backfills must run outside caller-owned database transactions**: the service owns the commit boundary to prevent outer rollbacks from orphaning uploaded files. Failed cleanup retains unattached blob records and storage keys for retry; use logged blob IDs in your host's unattached-blob maintenance.
507
+ Host uploads should use `reader.attach_avatar(upload)` or `Bible270::AvatarImages.update!(reader, attributes, upload: upload)`; direct attachment bypasses optimization. **Run uploads and backfills outside caller-owned database transactions** to avoid orphaned files after rollback. Failed cleanup retains unattached blob records and storage keys for retry; use logged blob IDs in host cleanup.
437
508
 
438
509
  ## Configuration reference
439
510
 
@@ -444,7 +515,7 @@ Bible270.configure do |config|
444
515
  config.mount_at = "/daily-bread"
445
516
  config.app_name = "Daily Bread"
446
517
  config.tagline = "Journeying through Scripture in 9 months"
447
- config.admin_emails = %w[andrew@example.org]
518
+ config.admin_emails = %w[andrew@example.org] # Site-admins
448
519
 
449
520
  config.start_date = nil # no shared calendar by default
450
521
  config.allow_reader_start_date = true
@@ -536,14 +607,17 @@ Mount the engine and add a CMS navigation link to use its own themed pages. To u
536
607
 
537
608
  | Table | Holds |
538
609
  |-------|-------|
539
- | `bible270_readers` | Identity, provider/uid or polymorphic owner, start date, and reader preferences |
540
- | `bible270_checkoffs` | One row per reader/day/track/part, protected by a unique index |
610
+ | `bible270_readers` | Identity, provider/uid or polymorphic owner, personal start date, preferences, and persistent `admin` boolean |
611
+ | `bible270_plan_runs` | Current-run marker, shared start date, and archive timestamp |
612
+ | `bible270_participations` | One membership per reader/run (unique pair), Active/Alumni status, `joined_at`, personal date, archive date, and frozen effective start date |
613
+ | `bible270_checkoffs` | Reader and participation references; one row per participation/day/track/part, protected by a unique index |
541
614
  | `bible270_comments` | Day/track reflections and replies, stored as plain text or safely rendered Markdown |
542
615
  | `bible270_likes` | Reader likes on comments |
543
- | `bible270_settings` | Shared run and administrative settings |
616
+ | `bible270_settings` | Current shared-date override, enrollment state, and administrative settings |
617
+ | `bible270_scripture_frames` | Admin-added passages, translation credits, and enabled status; shared across runs |
544
618
  | `bible270_sign_in_tokens` | Email, token digest, expiry, and consumption time |
545
619
 
546
- A day is complete when all parts of all three tracks are checked off. Progress and visible reflections are public; they are not private journals.
620
+ A complete day requires all parts of all three tracks. Progress uses the current membership, or the latest historical one if absent; runs are never added together. Reflections, replies, and likes belong to readers and remain shared across groups. **Progress and visible reflections are public, not private journals.**
547
621
 
548
622
  ## Routes (inside the mount point)
549
623
 
@@ -562,6 +636,7 @@ DELETE /comments/:id comments#destroy
562
636
  POST /comments/:id/like likes#toggle
563
637
  GET /community readers#index
564
638
  GET /mention-suggestions readers#mention_suggestions (signed-in JSON)
639
+ GET /scripture-frame scripture_frames#show (public JSON)
565
640
  GET /readers/:id readers#show
566
641
  GET /progress readers#progress
567
642
  GET /sign_in sessions#new
@@ -602,9 +677,9 @@ Precedence is built-in `CHAPTER_BREAKS`, then `config.chapter_breaks`, then YAML
602
677
  | `PSALM_119_SECTION_SIZE` | `16` | Default verses per Psalm 119 section |
603
678
  | `CHAPTER_BREAKS` | Built-in chapter map | Selected breaks and whole-chapter overrides |
604
679
 
605
- For New Testament and Psalms/Proverbs readings, explicit breaks fix a chapter's reading count; unpinned chapters divide by verse load to fill the remaining days. The Psalms/Proverbs track reserves the final day for Psalm 1. Without explicit breaks, divided chapters use equal parts.
680
+ For New Testament and Psalms/Proverbs, explicit breaks fix a chapter's reading count; other chapters divide by verse load to fill remaining days, using equal parts. Psalms/Proverbs reserves the final day for Psalm 1.
606
681
 
607
- Breaks must be ascending, distinct, and inside the chapter; invalid entries or too many pinned readings raise `ArgumentError`. Results are memoized and refreshed when configured breaks change. There is no stored schedule to migrate, but **changing assignments does not remap existing check-offs or reflections**. Test custom schedules before using them with an active group.
682
+ Breaks must be ascending, distinct, and inside the chapter; invalid entries or too many pinned readings raise `ArgumentError`. Cached results refresh when breaks change. No schedule migration is needed, but **changed assignments do not remap check-offs or reflections**. Test custom schedules before using them with an active group.
608
683
 
609
684
  ## Scaling
610
685
 
@@ -622,11 +697,11 @@ Custom controls must POST with a CSRF token; use `button_to`. Confirm `omniauth-
622
697
 
623
698
  **No email arrives**
624
699
 
625
- Check Action Mailer delivery settings, an accepted `mailer_from`, and logs. Sign-in uses `deliver_now` unless `email_sign_in_deliver_later` is enabled; for queued mail, check the Active Job worker too. Delivery failures are not shown to readers to avoid disclosing account information.
700
+ Check Action Mailer settings, an accepted `mailer_from`, and logs. Sign-in uses `deliver_now` unless `email_sign_in_deliver_later` is enabled; then check the Active Job worker too. Delivery errors are hidden from readers to avoid revealing accounts.
626
701
 
627
702
  **“That link has expired or was already used”**
628
703
 
629
- Request a fresh link. Links are single-use and expire after 20 minutes by default. Mail scanners or preview bots can consume them before the reader clicks; investigate prefetching if it recurs. Increase `email_sign_in_ttl` only if expiry is the problem—it cannot restore a consumed link.
704
+ Request a fresh link. Links are single-use and expire after 20 minutes by default. Mail scanners or preview bots can consume them early; investigate prefetching if it recurs. Increasing `email_sign_in_ttl` helps only with expiry, not consumed links.
630
705
 
631
706
  **Custom layout is unstyled**
632
707
 
@@ -641,9 +716,19 @@ node --test test/javascript/*.cjs
641
716
  bundle exec rubocop --cache false
642
717
  ```
643
718
 
644
- `rake test` defaults to six isolated processes, prints combined results, writes coverage to `coverage/index.html`, and records runtimes in `tmp/parallel_runtime_test.log` for balancing. Set `PARALLEL_WORKERS` to change the count, or use `bundle exec rake test:serial` for serial coverage.
719
+ `rake test` uses up to eight CPU-aware workers and writes coverage to `coverage/index.html`. Tests share setup in `test/support`.
720
+
721
+ Use `PARALLEL_WORKERS=4 bundle exec rake test` to choose the count, or `bundle exec rake test:serial` for serial coverage. Logs keep warnings and errors in `test/dummy/log/test-*.log`; set `TEST_LOG_LEVEL=debug` for request, template, and SQL details.
645
722
 
646
- Video UI tests require **Node.js 22+**, use the built-in runner with no npm dependencies, and do not contact YouTube. Check live playback and host CSP separately in a browser. Plan logic is unit-tested without a Rails dependency.
723
+ JavaScript tests require **Node.js 22+**. Chromium layout checks run when a browser is available (`CHROME_BIN` selects it). Video tests do not contact YouTube; check live playback and host CSP separately.
724
+
725
+ CI also checks completion rendering in mobile and desktop WebKit. To run that check locally:
726
+
727
+ ```bash
728
+ npm install --prefix tmp/browser-tests --no-save --no-package-lock playwright@1.65.0
729
+ tmp/browser-tests/node_modules/.bin/playwright install --with-deps webkit
730
+ NODE_PATH=./tmp/browser-tests/node_modules B270_WEBKIT_TESTS=1 node --test test/javascript/day_completion_webkit_test.cjs
731
+ ```
647
732
 
648
733
  ### Get an email link for local testing
649
734
 
@@ -660,7 +745,7 @@ Use your local host/port. If `raw` is nil, the address is invalid or rate-limite
660
745
 
661
746
  Report bugs or open pull requests at <https://github.com/avonderluft/bible270>.
662
747
 
663
- Fork and clone the repository, branch from `main` (`git checkout -b my-feature`), and add tests with your change. Run the [development checks](#development), commit with a clear message, and open a pull request against `main` explaining what changed and why.
748
+ Fork, clone, and branch from `main` (`git checkout -b my-feature`). Add tests, run the [development checks](#development), and open a pull request against `main` explaining the change.
664
749
 
665
750
  - Keep plan logic independent of Rails.
666
751
  - Pin exact expected references in tests for schedule changes.
data/Rakefile CHANGED
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require 'bundler/gem_tasks' # provides build / install / release
4
+ require 'etc'
4
5
  require 'open3'
5
6
  require 'rake/testtask'
6
7
  require 'stringio'
@@ -144,7 +145,7 @@ end
144
145
 
145
146
  Rake::Task[:build].enhance([:normalize_gem_permissions])
146
147
 
147
- desc 'Run tests in isolated processes (default: 2 workers)'
148
+ desc 'Run tests in isolated processes'
148
149
  namespace :test do
149
150
  task :prepare_serial do
150
151
  FileUtils.rm_rf('coverage')
@@ -160,7 +161,7 @@ namespace :test do
160
161
  Rake::Task['test:serial'].enhance(['test:prepare_serial'])
161
162
 
162
163
  task :parallel do
163
- workers = ENV.fetch('PARALLEL_WORKERS', '6')
164
+ workers = ENV.fetch('PARALLEL_WORKERS') { Etc.nprocessors.clamp(1, 8).to_s }
164
165
  FileUtils.rm_rf('coverage')
165
166
  env = {
166
167
  'PARALLEL_COVERAGE' => 'true',