From 0afb2aaf5a218f8af31f4d9be917519e0333d04b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Mar 2026 17:51:37 +0000
Subject: [PATCH 1/2] Initial plan


From b3c450e0b33d56b55be790b6d5777257012d56c1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Mar 2026 18:24:39 +0000
Subject: [PATCH 2/2] Add word-by-word reading option for bonuses

Add readBonuses setting to BonusRoom that reads bonus leadin and
parts word by word (like tossup reading). After each part is fully
read, a dead time timer starts followed by the answer period.

Includes:
- Reading speed slider and toggle UI in bonus settings
- Pause button for bonus reading
- Client-side word-by-word display with proper targeting
- Settings persistence via localStorage

Co-authored-by: geoffrey-wu <42471355+geoffrey-wu@users.noreply.github.com>
---
 client/play/BonusClient.js             |  63 +++++++++++--
 client/play/bonuses/SoloBonusClient.js |  10 +++
 client/play/bonuses/index.html         |  10 +++
 client/play/bonuses/index.jsx          |  25 ++++++
 quizbowl/BonusRoom.js                  | 120 ++++++++++++++++++++++++-
 5 files changed, 219 insertions(+), 9 deletions(-)

diff --git a/client/play/BonusClient.js b/client/play/BonusClient.js
index 2d0c8db1d..9439022a6 100644
--- a/client/play/BonusClient.js
+++ b/client/play/BonusClient.js
@@ -8,13 +8,19 @@ export const BonusClientMixin = (ClientClass) => class extends ClientClass {
     switch (data.type) {
       case 'end-current-bonus': return this.endCurrentBonus(data);
       case 'give-bonus-answer': return this.giveBonusAnswer(data);
+      case 'pause': return this.pause(data);
       case 'reveal-leadin': return this.revealLeadin(data);
       case 'reveal-next-answer': return this.revealNextAnswer(data);
       case 'reveal-next-part': return this.revealNextPart(data);
+      case 'set-reading-speed': return this.setReadingSpeed(data);
       case 'start-bonus-answer': return this.startBonusAnswer(data);
       case 'start-next-bonus': return this.startNextBonus(data);
       case 'toggle-bonus-part': return this.toggleBonusPart(data);
+      case 'toggle-read-bonuses': return this.toggleReadBonuses(data);
       case 'toggle-three-part-bonuses': return this.toggleThreePartBonuses(data);
+      case 'update-question':
+        if (data.target) { return this.updateQuestion(data); }
+        return super.onmessage(message);
       default: return super.onmessage(message);
     }
   }
@@ -31,7 +37,7 @@ export const BonusClientMixin = (ClientClass) => class extends ClientClass {
     }
 
     if (directive !== 'prompt') {
-      document.getElementById('reveal').disabled = false;
+      document.getElementById('reveal').disabled = !this.room.settings.readBonuses;
     }
   }
 
@@ -54,10 +60,12 @@ export const BonusClientMixin = (ClientClass) => class extends ClientClass {
   }
 
   revealNextPart ({ bonusEligibleTeamId, currentPartNumber, part, value }) {
-    document.getElementById('reveal').disabled = !(
-      bonusEligibleTeamId === undefined ||
-      bonusEligibleTeamId === this.room.players[this.USER_ID]?.teamId
-    );
+    if (!this.room.settings.readBonuses) {
+      document.getElementById('reveal').disabled = !(
+        bonusEligibleTeamId === undefined ||
+        bonusEligibleTeamId === this.room.players[this.USER_ID]?.teamId
+      );
+    }
 
     const input = document.createElement('input');
     input.id = `checkbox-${currentPartNumber + 1}`;
@@ -93,6 +101,11 @@ export const BonusClientMixin = (ClientClass) => class extends ClientClass {
   startNextBonus ({ bonus, packetLength }) {
     this.startNextQuestion({ packetLength, question: bonus });
     document.getElementById('next').textContent = 'Skip';
+    const pauseButton = document.getElementById('pause');
+    if (pauseButton) {
+      pauseButton.textContent = 'Pause';
+      pauseButton.disabled = !this.room.settings.readBonuses;
+    }
   }
 
   setMode ({ mode }) {
@@ -116,6 +129,46 @@ export const BonusClientMixin = (ClientClass) => class extends ClientClass {
   toggleThreePartBonuses ({ threePartBonuses }) {
     document.getElementById('toggle-three-part-bonuses').checked = threePartBonuses;
   }
+
+  pause ({ paused }) {
+    const pauseButton = document.getElementById('pause');
+    if (pauseButton) {
+      pauseButton.textContent = paused ? 'Resume' : 'Pause';
+    }
+  }
+
+  setReadingSpeed ({ readingSpeed }) {
+    const el = document.getElementById('reading-speed');
+    if (el) {
+      el.value = readingSpeed;
+    }
+    const display = document.getElementById('reading-speed-display');
+    if (display) {
+      display.textContent = readingSpeed;
+    }
+  }
+
+  toggleReadBonuses ({ readBonuses }) {
+    const el = document.getElementById('toggle-read-bonuses');
+    if (el) {
+      el.checked = readBonuses;
+    }
+    const readingSpeedSettings = document.getElementById('reading-speed-settings');
+    if (readingSpeedSettings) {
+      readingSpeedSettings.classList.toggle('d-none', !readBonuses);
+    }
+  }
+
+  updateQuestion ({ word, target, currentPartNumber }) {
+    if (target === 'leadin') {
+      document.getElementById('leadin').innerHTML += word + ' ';
+    } else {
+      const partEl = document.getElementById(`bonus-part-${currentPartNumber + 1}`);
+      if (partEl) {
+        partEl.querySelector('p').innerHTML += word + ' ';
+      }
+    }
+  }
 };
 
 const BonusClient = BonusClientMixin(QuestionClient);
diff --git a/client/play/bonuses/SoloBonusClient.js b/client/play/bonuses/SoloBonusClient.js
index b7e458644..626054ccc 100644
--- a/client/play/bonuses/SoloBonusClient.js
+++ b/client/play/bonuses/SoloBonusClient.js
@@ -124,6 +124,16 @@ export default class SoloBonusClient extends BonusClient {
     window.localStorage.setItem('singleplayer-bonus-settings', JSON.stringify({ ...this.room.settings, version: settingsVersion }));
   }
 
+  setReadingSpeed ({ readingSpeed }) {
+    super.setReadingSpeed({ readingSpeed });
+    window.localStorage.setItem('singleplayer-bonus-settings', JSON.stringify({ ...this.room.settings, version: settingsVersion }));
+  }
+
+  toggleReadBonuses ({ readBonuses }) {
+    super.toggleReadBonuses({ readBonuses });
+    window.localStorage.setItem('singleplayer-bonus-settings', JSON.stringify({ ...this.room.settings, version: settingsVersion }));
+  }
+
   /**
  * Calculates the points per bonus and updates the display.
  */
diff --git a/client/play/bonuses/index.html b/client/play/bonuses/index.html
index 2780751fb..1cb2628fc 100644
--- a/client/play/bonuses/index.html
+++ b/client/play/bonuses/index.html
@@ -169,6 +169,14 @@ <h1 id="funny-toast-text" class="me-auto text-danger"></h1>
                         <input class="form-check-input" id="toggle-timer" type="checkbox" role="switch" checked>
                         <label class="form-check-label" for="toggle-timer">Enable timer</label>
                     </div>
+                    <div class="form-check form-switch">
+                        <input class="form-check-input" id="toggle-read-bonuses" type="checkbox" role="switch">
+                        <label class="form-check-label" for="toggle-read-bonuses">Read bonuses word by word</label>
+                    </div>
+                    <div class="d-none" id="reading-speed-settings">
+                        <label for="reading-speed">Reading speed: <span id="reading-speed-display">50</span><br></label>
+                        <input class="form-range" id="reading-speed" type="range" min="0" max="100" step="5">
+                    </div>
                     <div class="mb-2"></div>
                     <label for="set-strictness">Strictness: <span id="strictness-display">7</span><br></label>
                     <input class="form-range" id="set-strictness" type="range" min="0" max="20" step="1" value="7">
@@ -220,6 +228,8 @@ <h1 id="funny-toast-text" class="me-auto text-danger"></h1>
             <div class="col-12 col-lg-9" id="buttons">
                 <button class="btn btn-primary" id="next" data-bs-placement="top" data-bs-toggle="tooltip" type="button"
                     title="Shortcut: n key">Next</button>
+                <button class="btn btn-primary" id="pause" data-bs-placement="top" data-bs-toggle="tooltip" type="button"
+                    title="Shortcut: p key" disabled>Pause</button>
                 <button class="btn btn-danger d-lg-none" id="toggle-options" type="button" disabled>Options</button>
                 <button class="btn btn-danger" id="toggle-settings" data-bs-placement="top" data-bs-toggle="tooltip" type="button"
                     title="Shortcut: e key" type="button">
diff --git a/client/play/bonuses/index.jsx b/client/play/bonuses/index.jsx
index 937e708dc..43508e592 100644
--- a/client/play/bonuses/index.jsx
+++ b/client/play/bonuses/index.jsx
@@ -58,6 +58,24 @@ document.getElementById('type-to-answer').addEventListener('click', function ()
   socket.sendToServer({ type: 'toggle-type-to-answer', typeToAnswer: this.checked });
 });
 
+document.getElementById('toggle-read-bonuses').addEventListener('click', function () {
+  this.blur();
+  socket.sendToServer({ type: 'toggle-read-bonuses', readBonuses: this.checked });
+});
+
+document.getElementById('reading-speed').addEventListener('change', function () {
+  socket.sendToServer({ type: 'set-reading-speed', readingSpeed: this.value });
+});
+
+document.getElementById('reading-speed').addEventListener('input', function () {
+  document.getElementById('reading-speed-display').textContent = this.value;
+});
+
+document.getElementById('pause').addEventListener('click', function () {
+  this.blur();
+  socket.sendToServer({ type: 'pause' });
+});
+
 document.addEventListener('keydown', (event) => {
   if (['INPUT', 'TEXTAREA', 'SELECT'].includes(document.activeElement.tagName)) { return; }
 
@@ -71,6 +89,7 @@ document.addEventListener('keydown', (event) => {
     case 'e': return document.getElementById('toggle-settings').click();
     case 'k': return document.getElementsByClassName('card-header-clickable')[0].click();
     case 'n': return document.getElementById('next').click();
+    case 'p': return document.getElementById('pause').click();
     case 's': return document.getElementById('next').click();
     case 't': return document.getElementsByClassName('star-bonus')[0].click();
     case 'y': return navigator.clipboard.writeText(room.bonus._id ?? '');
@@ -119,6 +138,12 @@ if (window.localStorage.getItem('singleplayer-bonus-settings')) {
     socket.sendToServer({ type: 'set-strictness', ...savedSettings });
     socket.sendToServer({ type: 'toggle-timer', ...savedSettings });
     socket.sendToServer({ type: 'toggle-type-to-answer', ...savedSettings });
+    if (savedSettings.readBonuses !== undefined) {
+      socket.sendToServer({ type: 'toggle-read-bonuses', ...savedSettings });
+    }
+    if (savedSettings.readingSpeed !== undefined) {
+      socket.sendToServer({ type: 'set-reading-speed', ...savedSettings });
+    }
   } catch {
     window.localStorage.removeItem('singleplayer-bonus-settings');
   }
diff --git a/quizbowl/BonusRoom.js b/quizbowl/BonusRoom.js
index 5d5a86731..22bdaf658 100644
--- a/quizbowl/BonusRoom.js
+++ b/quizbowl/BonusRoom.js
@@ -1,4 +1,4 @@
-import { ANSWER_TIME_LIMIT, BONUS_PROGRESS_ENUM, MODE_ENUM } from './constants.js';
+import { ANSWER_TIME_LIMIT, BONUS_PROGRESS_ENUM, DEAD_TIME_LIMIT, MODE_ENUM } from './constants.js';
 import QuestionRoom from './QuestionRoom.js';
 
 export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomClass {
@@ -7,6 +7,12 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
 
     this.bonus = {};
     this.bonusProgress = BONUS_PROGRESS_ENUM.NOT_STARTED;
+    this.bonusTimeoutID = null;
+    this.bonusPaused = false;
+    this.bonusQuestionSplit = [];
+    this.bonusWordIndex = 0;
+    this.bonusReadingTarget = null;
+    this.bonusUserId = null;
     /**
      * 0-indexed variable that tracks current part of the bonus being read
      */
@@ -21,14 +27,27 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
       threePartBonuses: true,
       ...this.query
     };
+
+    this.settings = {
+      ...this.settings,
+      readBonuses: false,
+      readingSpeed: this.settings.readingSpeed ?? 50
+    };
   }
 
   async message (userId, message) {
     switch (message.type) {
       case 'give-answer': return this.giveBonusAnswer(userId, message);
       case 'next': return this.next(userId, message);
+      case 'pause':
+        if (this.settings.readBonuses && this.bonusProgress === BONUS_PROGRESS_ENUM.READING && this.bonusQuestionSplit.length > 0) {
+          return this.pauseBonus(userId);
+        }
+        return super.message(userId, message);
+      case 'set-reading-speed': return this.setReadingSpeed(userId, message);
       case 'start-bonus-answer': return this.startBonusAnswer(userId, message);
       case 'toggle-bonus-part': return this.toggleBonusPart(userId, message);
+      case 'toggle-read-bonuses': return this.toggleReadBonuses(userId, message);
       case 'toggle-three-part-bonuses': return this.toggleThreePartBonuses(userId, message);
       default: return super.message(userId, message);
     }
@@ -44,8 +63,10 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
     if (this.queryingQuestion) { return false; }
     if (this.bonusProgress === BONUS_PROGRESS_ENUM.READING && !this.settings.skip) { return false; }
 
+    clearTimeout(this.bonusTimeoutID);
     clearInterval(this.timer.interval);
     this.emitMessage({ type: 'timer-update', timeRemaining: 0 });
+    this.bonusPaused = false;
 
     const lastPartRevealed = this.bonusProgress === BONUS_PROGRESS_ENUM.LAST_PART_REVEALED;
     const pointsPerPart = this.pointsPerPart;
@@ -95,8 +116,69 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
     if (allowed) { await this.startNextBonus(userId); }
   }
 
+  pauseBonus (userId) {
+    this.bonusPaused = !this.bonusPaused;
+    if (this.bonusPaused) {
+      clearTimeout(this.bonusTimeoutID);
+      clearInterval(this.timer.interval);
+    } else if (this.bonusWordIndex >= this.bonusQuestionSplit.length) {
+      this.startServerTimer(
+        this.timer.timeRemaining,
+        (time) => this.emitMessage({ type: 'timer-update', timeRemaining: time }),
+        () => this.startBonusAnswer(this.bonusUserId)
+      );
+    } else {
+      this.readBonus(Date.now());
+    }
+    const username = this.players[userId].username;
+    this.emitMessage({ type: 'pause', paused: this.bonusPaused, username });
+  }
+
+  readBonus (expectedReadTime) {
+    if (Object.keys(this.bonus || {}).length === 0) { return; }
+    if (this.bonusWordIndex >= this.bonusQuestionSplit.length) {
+      if (this.bonusReadingTarget === 'leadin') {
+        this.revealNextPart();
+      } else {
+        this.startServerTimer(
+          DEAD_TIME_LIMIT * 10,
+          (time) => this.emitMessage({ type: 'timer-update', timeRemaining: time }),
+          () => this.startBonusAnswer(this.bonusUserId)
+        );
+      }
+      return;
+    }
+
+    const word = this.bonusQuestionSplit[this.bonusWordIndex];
+    this.bonusWordIndex++;
+    this.emitMessage({ type: 'update-question', word, target: this.bonusReadingTarget, currentPartNumber: this.currentPartNumber });
+
+    let time = Math.log(word.length) + 1;
+    if ((word.endsWith('.') && word.charCodeAt(word.length - 2) > 96 && word.charCodeAt(word.length - 2) < 123) ||
+      word.slice(-2) === '.\u201d' || word.slice(-2) === '!\u201d' || word.slice(-2) === '?\u201d') {
+      time += 2.5;
+    } else if (word.endsWith(',') || word.slice(-2) === ',\u201d') {
+      time += 1.5;
+    }
+
+    time = time * 0.9 * (140 - this.settings.readingSpeed);
+    const delay = time - Date.now() + expectedReadTime;
+
+    this.bonusTimeoutID = setTimeout(() => {
+      this.readBonus(time + expectedReadTime);
+    }, delay);
+  }
+
   revealLeadin () {
-    this.emitMessage({ type: 'reveal-leadin', leadin: this.bonus.leadin });
+    const leadin = this.settings.readBonuses ? '' : this.bonus.leadin;
+    this.emitMessage({ type: 'reveal-leadin', leadin });
+    if (this.settings.readBonuses) {
+      this.bonusQuestionSplit = (this.bonus.leadin_sanitized || this.bonus.leadin).split(' ').filter(word => word !== '');
+      this.bonusWordIndex = 0;
+      this.bonusReadingTarget = 'leadin';
+      clearTimeout(this.bonusTimeoutID);
+      this.readBonus(Date.now());
+    }
   }
 
   revealNextAnswer () {
@@ -116,13 +198,23 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
     if (this.bonusProgress === BONUS_PROGRESS_ENUM.LAST_PART_REVEALED) { return; }
 
     this.currentPartNumber++;
+    const part = this.settings.readBonuses ? '' : this.bonus.parts[this.currentPartNumber];
     this.emitMessage({
       type: 'reveal-next-part',
       bonusEligibleTeamId: this.bonusEligibleTeamId,
       currentPartNumber: this.currentPartNumber,
-      part: this.bonus.parts[this.currentPartNumber],
+      part,
       value: this.getPartValue()
     });
+
+    if (this.settings.readBonuses) {
+      const sanitizedParts = this.bonus.parts_sanitized || this.bonus.parts;
+      this.bonusQuestionSplit = (sanitizedParts[this.currentPartNumber] || '').split(' ').filter(word => word !== '');
+      this.bonusWordIndex = 0;
+      this.bonusReadingTarget = 'part';
+      clearTimeout(this.bonusTimeoutID);
+      this.readBonus(Date.now());
+    }
   }
 
   startBonusAnswer (userId) {
@@ -142,9 +234,13 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
     this.emitMessage({ type: 'start-next-bonus', packetLength: this.packet.bonuses.length, bonus: this.bonus, userId, username });
     this.currentPartNumber = -1;
     this.pointsPerPart = [];
+    this.bonusPaused = false;
     this.bonusProgress = BONUS_PROGRESS_ENUM.READING;
+    this.bonusUserId = userId;
     this.revealLeadin();
-    this.revealNextPart();
+    if (!this.settings.readBonuses) {
+      this.revealNextPart();
+    }
   }
 
   toggleBonusPart (userId, { partNumber, correct }) {
@@ -153,6 +249,22 @@ export const BonusRoomMixin = (QuestionRoomClass) => class extends QuestionRoomC
     this.pointsPerPart[partNumber] = correct ? this.getPartValue(partNumber) : 0;
   }
 
+  setReadingSpeed (userId, { readingSpeed }) {
+    if (isNaN(readingSpeed)) { return false; }
+    if (readingSpeed > 100) { readingSpeed = 100; }
+    if (readingSpeed < 0) { readingSpeed = 0; }
+
+    this.settings.readingSpeed = readingSpeed;
+    const username = this.players[userId].username;
+    this.emitMessage({ type: 'set-reading-speed', username, readingSpeed });
+  }
+
+  toggleReadBonuses (userId, { readBonuses }) {
+    this.settings.readBonuses = readBonuses;
+    const username = this.players[userId].username;
+    this.emitMessage({ type: 'toggle-read-bonuses', readBonuses, username });
+  }
+
   toggleThreePartBonuses (userId, { threePartBonuses }) {
     const username = this.players[userId].username;
     this.query.threePartBonuses = threePartBonuses;