@internetarchive/ia-book-actions 1.4.4-alpha1 → 1.4.4-alpha10

package/index.html

@@ -97,6 +97,7 @@
       border: 2px solid #194880;
       border-radius: 10px;
       background: white;
+      height: 50px;
     }
     .timer-presets button.active-preset {
       background: #194880;
@@ -137,6 +138,9 @@
     .loan-status-badge.status-active {
       background: #2e7d32; /* green: loan is currently checked out */
     }
+    .loan-status-badge.status-renewing {
+      background: #b8860b; /* amber: a renew_loan attempt is in flight */
+    }
     .loan-status-badge.status-returned {
       background: #d9534f; /* red: auto-returned / not on loan */
     }
@@ -216,7 +220,7 @@
     console.log = (...consoleArgs) => {
       __nativeConsoleLog(...consoleArgs);
 
-      const loggedPrefixes = ['[ActionsHandlerService]', '[IABookActions]', '[Demo]'];
+      const loggedPrefixes = ['[IABookActions]', '[IABookActions]', '[Demo]'];
       if (typeof consoleArgs[0] !== 'string' || !loggedPrefixes.some((prefix) => consoleArgs[0].startsWith(prefix))) {
         return;
       }
@@ -280,7 +284,7 @@
     const timerPresets = {
       '15s': { loanTotalTime: 15, loanRenewAtLast: 13, pageChangedInLast: 5 },
       '30s': { loanTotalTime: 30, loanRenewAtLast: 27, pageChangedInLast: 10 },
-      '2': { loanTotalTime: 120, loanRenewAtLast: 110, pageChangedInLast: 30 },
+      '2': { loanTotalTime: 120, loanRenewAtLast: 95, pageChangedInLast: 15 },
       '5': { loanTotalTime: 300, loanRenewAtLast: 240, pageChangedInLast: 60 },
       '10': { loanTotalTime: 600, loanRenewAtLast: 480, pageChangedInLast: 120 },
       '30': { loanTotalTime: 1800, loanRenewAtLast: 1500, pageChangedInLast: 600 },
@@ -439,6 +443,14 @@
         await iaBookActions.updateComplete;
       }
 
+      // showWarningModal() reads its message text from
+      // loanRenewHelper.getMessageTexts(loanRenewResult.texts, ...) — that
+      // helper only exists, and loanRenewResult.texts only gets populated,
+      // once autoLoanRenewChecker() has run at least once (this is what the
+      // real periodic timer calls before ever showing the modal). Run it
+      // here too so the button shows the same populated message a real
+      // warning would.
+      await iaBookActions.autoLoanRenewChecker(false);
       iaBookActions.showWarningModal();
     });
 
@@ -578,6 +590,13 @@
     function computeLoanStatus() {
       const lendingStatus = iaBookActions.lendingStatus || {};
 
+      // Checked first: autoRenewExpiredLoan() optimistically flips
+      // browsingExpired back to false the moment a retry starts (before the
+      // renew_loan call has actually landed), so without this check the
+      // badge would misleadingly jump straight to ACTIVE during the retry.
+      if (iaBookActions.loanRenewInProgress) {
+        return { badge: 'RENEWING', className: 'status-renewing' };
+      }
       if (lendingStatus.browsingExpired) {
         return { badge: 'RETURNED', className: 'status-returned' };
       }
@@ -662,7 +681,10 @@
                 <button id="show_expired_modal">2. Auto-return due to inactivity<br>(no modal, page stays put)</button>
               </td>
               <td class="action-button">
-                <button class="pageChangedEvent">3. Interact with book (turn page)<br>silently renew if interact in given time</button>
+                <button class="pageChangedEvent">
+                  3. Interact with book (turn page)<br>
+                  silently renew while active or after auto-return
+                </button>
               </td>
               <td class="action-button">
                 <button id="resync_timer">4. Return to tab after time away<br>(visibilitychange — silent retry if expired)</button>
@@ -688,9 +710,6 @@
               <td class="searchParam">
                 <label><input type="checkbox" name="search" value="Search Param" />Search Param</label>
               </td>
-              <td>
-                <label class="ia-button"><button class="pageChangedEvent">Page Change Event</button></label>
-              </td>
             </tr>
           </table>
       </fieldset>

package/package.json

@@ -7,7 +7,7 @@
   },
   "author": "Internet Archive",
   "license": "AGPL-3.0-only",
-  "version": "1.4.4-alpha1",
+  "version": "1.4.4-alpha10",
   "main": "index.js",
   "module": "index.js",
   "publishConfig": {

package/src/core/services/actions-handler/actions-handler-service.js

@@ -84,10 +84,10 @@ export default async function ActionsHandlerService(options) {
       .then(data => {
         // `data` is the parsed version of the JSON returned from the above endpoint.
         if (!data?.error) {
-          log(`[ActionsHandlerService] ✓ ${option.action} succeeded`, data);
+          log(`[IABookActions] ✓ ${option.action} succeeded`, data);
           option?.success(data);
         } else {
-          log(`[ActionsHandlerService] ✗ ${option.action} failed`, data);
+          log(`[IABookActions] ✗ ${option.action} failed`, data);
           option?.error(data);
         }
       });

package/src/core/services/actions-handler/actions-handler.js

@@ -53,20 +53,8 @@ export default class ActionsHandler extends LitElement {
       );
     });
 
-    this.addEventListener('autoRenew', async ({ detail }) => {
-      this.handleLoanRenewNow();
-      await this.loanAnanlytics?.storeLoanStatsCount(
-        this.identifier,
-        'autorenew'
-      );
-
-      const analyticsLabel = detail?.renewType === 'auto' ? analyticsLabels.browseAutoRenew : analyticsLabels.browseManualRenew;
-      this.loanAnanlytics?.sendEvent(
-        analyticsCategories.browse,
-        analyticsActions.browseRenew,
-        analyticsLabel,
-        this.identifier
-      );
+    this.addEventListener('autoRenew', ({ detail }) => {
+      this.handleLoanRenewNow(detail?.renewType);
     });
 
     this.addEventListener('autoReturn', async () => {
@@ -177,14 +165,14 @@ export default class ActionsHandler extends LitElement {
     });
   }
 
-  handleLoanRenewNow() {
+  handleLoanRenewNow(renewType) {
     const action = 'renew_loan';
 
     ActionsHandlerService({
       action,
       identifier: this.identifier,
       success: async data => {
-        log('RENEW_LOAN --- ', data, action, data.loan, this.identifier);
+        log('RENEW_LOAN --- ', data, this.identifier);
         const activeLoan = data.loan ? data.loan : undefined;
         const isRenewal = activeLoan.renewal;
 
@@ -192,6 +180,23 @@ export default class ActionsHandler extends LitElement {
           // Await — loanAutoRenewed listeners read this same cache key
           // immediately; dispatching before the write lands was a race.
           await this.setBrowseTimeSession();
+
+          // Only record the renew analytics event once the renewal has
+          // actually succeeded — not merely attempted.
+          await this.loanAnanlytics?.storeLoanStatsCount(
+            this.identifier,
+            'autorenew'
+          );
+          const analyticsLabel =
+            renewType === 'auto'
+              ? analyticsLabels.browseAutoRenew
+              : analyticsLabels.browseManualRenew;
+          this.loanAnanlytics?.sendEvent(
+            analyticsCategories.browse,
+            analyticsActions.browseRenew,
+            analyticsLabel,
+            this.identifier
+          );
         } else {
           log('RENEW_LOAN ERROR --- ', {
             action,

package/src/core/services/loan-token-poller.js

@@ -18,6 +18,18 @@ export class LoanTokenPoller {
 
     this.loanTokenInterval = undefined;
 
+    /**
+     * Lending::do_renew() (backend) deletes the old loan record and
+     * writes a brand-new one on every renewal — this poller's initial
+     * create_token call (fired right after a renewal re-establishes the
+     * reading session) can race that write's propagation and come back
+     * with "you do not currently have this book borrowed" even though
+     * the loan is genuinely valid. Retry a few times with backoff instead
+     * of giving up on the first attempt.
+     */
+    this.maxInitialTokenRetries = 3;
+    this.initialTokenRetryDelay = 1000; // ms, multiplied by attempt number
+
     /**
      * loan analytics instance
      * @see loan-analytics.js
@@ -58,29 +70,64 @@ export class LoanTokenPoller {
     }
   }
 
-  async handleLoanTokenPoller(isInitial = false) {
+  /**
+   * @param {boolean} isInitial - the first create_token call right after
+   *   bookAccessed()/a renewal, as opposed to a routine interval tick.
+   * @param {number} retryCount - internal, counts retries of the initial call.
+   */
+  async handleLoanTokenPoller(isInitial = false, retryCount = 0) {
     const action = 'create_token';
     ActionsHandlerService({
       identifier: this.identifier,
       action,
-      error: data => {
-        this.errorCallback({ detail: { action, data } });
-
-        // send error to Sentry
-        window?.Sentry?.captureMessage(
-          `${sentryLogs.handleLoanTokenPoller} - Error: ${JSON.stringify(data)}`
-        );
-
-        // send LendingServiceError to GA
-        this.loanAnalytics?.sendEvent(
-          'LendingServiceLoanError',
-          action,
-          this.identifier
-        );
-      },
+      error: data => this.handleTokenError(data, isInitial, retryCount),
       success: () => {
         if (isInitial) this.successCallback();
       },
     });
   }
+
+  /**
+   * Decide whether a create_token failure should be retried (a stale
+   * read of the loan record right after a renewal, see the constructor
+   * comment) or reported via errorCallback. Split out from
+   * handleLoanTokenPoller so it's directly testable without needing to
+   * mock the network call.
+   *
+   * @param {Object} data - the error payload from ActionsHandlerService.
+   * @param {boolean} isInitial
+   * @param {number} retryCount
+   */
+  handleTokenError(data, isInitial, retryCount) {
+    const action = 'create_token';
+    const isStaleLoanReadError =
+      typeof data?.error === 'string' &&
+      /do not currently have this book borrowed/i.test(data.error);
+
+    if (
+      isInitial &&
+      isStaleLoanReadError &&
+      retryCount < this.maxInitialTokenRetries
+    ) {
+      const delay = this.initialTokenRetryDelay * (retryCount + 1);
+      setTimeout(() => {
+        this.handleLoanTokenPoller(true, retryCount + 1);
+      }, delay);
+      return;
+    }
+
+    this.errorCallback({ detail: { action, data } });
+
+    // send error to Sentry
+    window?.Sentry?.captureMessage(
+      `${sentryLogs.handleLoanTokenPoller} - Error: ${JSON.stringify(data)}`
+    );
+
+    // send LendingServiceError to GA
+    this.loanAnalytics?.sendEvent(
+      'LendingServiceLoanError',
+      action,
+      this.identifier
+    );
+  }
 }

package/src/ia-book-actions.js

@@ -96,6 +96,15 @@ export default class IABookActions extends LitElement {
 
     this.loanRenewInProgress = false;
 
+    /**
+     * True while a renewal in flight is recovering from a loan that
+     * genuinely lapsed (set by autoRenewExpiredLoan), as opposed to a
+     * routine pre-expiry top-up. Only the recovery case needs BookReader
+     * re-initialized once the renewal is confirmed — see
+     * handleLoanAutoRenewed.
+     */
+    this.recoveringFromLoanExpiry = false;
+
     this.warningModalOpen = false;
 
     /**
@@ -180,6 +189,13 @@ export default class IABookActions extends LitElement {
     }
 
     if (changed.has('loanRenewResult') && this.loanRenewResult.renewNow) {
+      // Any renewal — not just the auto-return recovery path — pauses the
+      // countdown for the renew_loan round-trip. Flag it here, centrally,
+      // so every path (interaction during active reading, periodic
+      // checker, auto-return recovery) gets the same "renewing" signal
+      // instead of just looking frozen until handleLoanAutoRenewed() clears
+      // this and restarts the timer.
+      this.loanRenewInProgress = true;
       window.IALendingIntervals.clearAll();
     }
   }
@@ -283,11 +299,22 @@ export default class IABookActions extends LitElement {
 
     /**
      * tokenPoller determines if user has loan token for this book
-     * - if book is going to renew, need to wait until renew is completed
+     * - if book is going to renew, need to wait until renew is completed:
+     *   loanRenewInProgress is set before renew_loan is even dispatched
+     *   (including the optimistic pre-confirmation window) and only
+     *   clears once the renewal is confirmed, so starting the poller here
+     *   mid-renewal would call create_token against the loan record
+     *   before it's actually renewed.
      */
     setTimeout(() => {
-      if (!hasExpired && !window.IALendingIntervals.tokenPoller)
+      if (
+        !hasExpired &&
+        !this.loanRenewInProgress &&
+        !window.IALendingIntervals.tokenPoller
+      ) {
+        this.recoveringFromLoanExpiry = false;
         this.startLoanTokenPoller();
+      }
     }, 100);
 
     this.requestUpdate();
@@ -304,17 +331,27 @@ export default class IABookActions extends LitElement {
      * dispatched this event from bookreader page changed
      */
     window.addEventListener('BookReader:userAction', () => {
+      // Capture before autoRenewExpiredLoan() runs — it synchronously flips
+      // lendingStatus.browsingExpired to false as an optimistic UI update,
+      // so checking the live property afterward would always see it as
+      // false and wrongly let autoLoanRenewChecker() run too. That second
+      // call would then overwrite loanRenewResult.renewNow (set true by
+      // autoRenewExpiredLoan) back to false, since the loanTime cache entry
+      // was already deleted by browseHasExpired() — silently killing the
+      // in-flight renewal and leaving the countdown stuck.
+      const wasExpired = this.lendingStatus.browsingExpired;
+
       log('[IABookActions] BookReader:userAction received', {
         borrowType: this.borrowType,
-        browsingExpired: this.lendingStatus.browsingExpired,
+        browsingExpired: wasExpired,
       });
 
       // If the loan expired while the tab stayed visible, auto-renew on page turn
-      if (this.lendingStatus.browsingExpired) {
+      if (wasExpired) {
         this.autoRenewExpiredLoan();
       }
 
-      if (this.borrowType === 'browsed' && !this.lendingStatus.browsingExpired) {
+      if (this.borrowType === 'browsed' && !wasExpired) {
         this.autoLoanRenewChecker(true);
       }
     });
@@ -372,6 +409,16 @@ export default class IABookActions extends LitElement {
    * @param {Boolean} hasPageChanged
    */
   async autoLoanRenewChecker(hasPageChanged = false) {
+    // Guards against re-entrancy the same way autoRenewExpiredLoan() does.
+    // BookReader:userAction can fire several times in quick succession
+    // (e.g. a single scroll gesture), and this method has no debouncing of
+    // its own — without this guard, each event would spin up its own
+    // LoanRenewHelper concurrently, and whichever's async localCache reads
+    // resolve last would clobber this.loanRenewResult, potentially
+    // re-triggering the whole renew_loan/create_token flow while a
+    // renewal from an earlier event is already in flight or just landed.
+    if (this.loanRenewInProgress) return;
+
     this.loanRenewHelper = new LoanRenewHelper(
       hasPageChanged,
       this.identifier,
@@ -395,6 +442,7 @@ export default class IABookActions extends LitElement {
   autoRenewExpiredLoan() {
     if (this.loanRenewInProgress) return;
     this.loanRenewInProgress = true;
+    this.recoveringFromLoanExpiry = true;
 
     this.modal?.closeModal();
 
@@ -532,20 +580,21 @@ export default class IABookActions extends LitElement {
    * Show modal when the book can no longer be automatically renewed
    * because another patron has checked it out.
    */
-  async showLoanUnavailableModal() {
+  async showLoanUnavailableModal(errorMsg) {
     const config = new ModalConfig({
       headline: '',
       showCloseButton: false,
       closeOnBackdropClick: false,
-      headerColor: '#194880',
+      headerColor: '#d9534f',
       message:
+        errorMsg ||
         'Due to inactivity, this book was returned, and someone else has now borrowed it. Please try again later.',
     });
 
     const customModalContent = html`<br />
       <div style="text-align: center">
         <button
-          style="${modalButtonStyle.iaButton} ${modalButtonStyle.renew}"
+          style="${modalButtonStyle.iaButton} ${modalButtonStyle.return}"
           @click=${() => URLHelper.goToUrl(this.returnUrl, true)}
         >
           Okay
@@ -639,6 +688,7 @@ export default class IABookActions extends LitElement {
     const activeLoan = detail?.data?.loan;
     const errorMessage = `Whoops, seems we hit a hiccup with renewing this book. Please refresh & retry. --- (Debug: ${detail?.data?.error})`;
     if (!activeLoan) {
+      this.recoveringFromLoanExpiry = false;
       this.showErrorModal(errorMessage, 'handleLoanAutoRenewed');
       return;
     }
@@ -661,6 +711,23 @@ export default class IABookActions extends LitElement {
         ajaxResponse: detail?.data,
       });
 
+      if (this.recoveringFromLoanExpiry) {
+        // The loan genuinely lapsed, and renew_loan has now CONFIRMED it's
+        // renewed server-side — only now is it safe to let BookReader
+        // re-initialize (create_token was minting its access cookie off
+        // the loan's expiry; doing this before confirmation risked reading
+        // the still-expired record). loanRenewInProgress already kept the
+        // token poller from restarting early, so it'll pick up fresh here
+        // once lendingStatus below re-triggers setupLendingToolbarActions().
+        // recoveringFromLoanExpiry itself is consumed/reset there, not
+        // here — this ONLY applies to an actual recovery, not a routine
+        // renewal (re-running br.init() on every routine top-up would be
+        // needlessly disruptive). create_token's own retry logic (see
+        // LoanTokenPoller) handles the datanode write-propagation race
+        // for both recovery and routine renewals.
+        this.postInitComplete = false;
+      }
+
       const currStatus = {
         ...this.lendingStatus,
         user_has_browsed: true,
@@ -718,14 +785,15 @@ export default class IABookActions extends LitElement {
 
     if (resyncd.hasSynced) {
       secondsLeft = resyncd.whatShouldLeft;
-      log('[IABookActions] startTimerCountdown: timer re-synced', {
+      log('[IABookActions] timer: timer re-synced', {
         secondsLeft,
       });
     }
 
-    log('[IABookActions] startTimerCountdown', {
+    log('[IABookActions] timer', {
       secondsLeft,
       loanRenewAtLast: this.loanRenewTimeConfig.loanRenewAtLast,
+      pageChangedInLast: this.loanRenewTimeConfig.pageChangedInLast,
     });
 
     /**
@@ -881,50 +949,71 @@ export default class IABookActions extends LitElement {
   handleLendingActionError(event) {
     this.disableActionGroup = false;
 
-    // clear all intervals for lending system when error occured
-    window?.IALendingIntervals?.clearAll();
-
     const action = event?.detail?.action;
     const errorMsg = event?.detail?.data?.error;
 
-    // For renew_loan failures after auto-renew, show the patron-facing message
-    if (
-      errorMsg &&
-      action === 'renew_loan' &&
-      errorMsg.match(/not available/)
-    ) {
-      this.loanRenewInProgress = false;
-      this.showLoanUnavailableModal();
-    } else if (errorMsg && action !== 'create_token') {
-      this.showErrorModal(errorMsg, action);
-    }
-
-    // if error related to loan token
-    // - set user_has_browsed to `false`
     if (action === 'create_token') {
-      const currStatus = {
+      // A create_token hiccup only affects BookReader's page-image access
+      // token — it says nothing about how much time is left on the loan
+      // itself, so it must not stop the reading countdown. Only clear the
+      // token poller so it can be retried.
+      window?.IALendingIntervals?.clearTokenPoller();
+
+      // The loan itself is fine — just this token refresh failed — but
+      // the action bar must reflect that it isn't safely browsable right
+      // now rather than silently doing nothing.
+      this.lendingStatus = {
         ...this.lendingStatus,
         user_has_browsed: false,
         available_to_browse: true,
       };
-      this.lendingStatus = currStatus;
-    }
 
-    // update action bar state if book is not available to browse or borrow.
-    if (errorMsg && errorMsg.match(/not available to borrow/gm)) {
-      let currStatus = this.lendingStatus;
-      if (action === 'browse_book') {
-        currStatus = {
-          ...this.lendingStatus,
-          available_to_browse: false,
-        };
-      } else if (action === 'borrow_book') {
-        currStatus = {
-          ...this.lendingStatus,
-          available_to_borrow: false,
-        };
+      // By the time this handler runs, LoanTokenPoller has already
+      // exhausted its retries for the transient datanode-propagation
+      // race (or the error wasn't that in the first place) — this is a
+      // genuine failure, so let the patron know instead of doing this
+      // silently. showErrorModal has dedicated create_token messaging
+      // (refresh button + support email).
+      if (errorMsg) this.showErrorModal(errorMsg, action);
+    } else if (action === 'renew_loan') {
+      window?.IALendingIntervals?.clearAll();
+      this.loanRenewInProgress = false;
+      this.recoveringFromLoanExpiry = false;
+
+      // The loan was NOT actually renewed — reflect that immediately
+      // (show Borrow, and clear the stale timer value) instead of leaving
+      // the action bar showing "Return now" with a frozen countdown from
+      // before the failed attempt, which falsely implies the book is
+      // still actively being read.
+      this.lendingStatus = {
+        ...this.lendingStatus,
+        user_has_browsed: false,
+        available_to_browse: true,
+        secondsLeftOnLoan: 0,
+      };
+
+      // Show the real error and refresh the page on dismissal (the
+      // modal's Okay button) so the client picks up whatever the server
+      // now authoritatively considers true — matching on "not available"
+      // to guess the reason was fragile since the server can return any
+      // message (e.g. a lending limit).
+      this.showLoanUnavailableModal(errorMsg);
+    } else {
+      // Every other action failure genuinely affects loan state.
+      window?.IALendingIntervals?.clearAll();
+
+      if (!errorMsg) return;
+
+      this.showErrorModal(errorMsg, action);
+
+      // update action bar state if book is not available to browse or borrow.
+      if (errorMsg.match(/not available to borrow/gm)) {
+        if (action === 'browse_book') {
+          this.lendingStatus = { ...this.lendingStatus, available_to_browse: false };
+        } else if (action === 'borrow_book') {
+          this.lendingStatus = { ...this.lendingStatus, available_to_borrow: false };
+        }
       }
-      this.lendingStatus = currStatus;
     }
   }
 

package/test/core/services/actions-handler.test.js

@@ -1,7 +1,9 @@
-import { expect, fixture } from '@open-wc/testing';
+import { expect, fixture, aTimeout } from '@open-wc/testing';
 import sinon from 'sinon';
+import { LocalCache } from '@internetarchive/local-cache';
 
 import ActionsHandler from '../../../src/core/services/actions-handler/actions-handler.js';
+import { analyticsCategories, analyticsActions, analyticsLabels } from '../../../src/core/config/analytics-event-and-category.js';
 
 // Define a temporary tag for this element for testing
 const TEST_TAG = 'ia-actions-handler-test';
@@ -89,3 +91,110 @@ describe('ActionsHandler#setStickyAdminAccess', () => {
     expect(lastSetCookie).to.contain(`${encodeURIComponent('sticky-admin-access')}=${encodeURIComponent('false')}`);
   });
 });
+
+describe('ActionsHandler#handleLoanRenewNow (WEBDEV-8322)', () => {
+  let el;
+  let localCache;
+  const identifier = 'renew-now-test-book';
+
+  beforeEach(async () => {
+    // Make sure no other test in this run left ?error=true in the URL —
+    // ActionsHandlerService reads it directly off window.location.
+    const params = new URLSearchParams(window.location.search);
+    if (params.has('error')) {
+      params.delete('error');
+      const query = params.toString();
+      window.history.replaceState(
+        {},
+        '',
+        `${window.location.pathname}${query ? `?${query}` : ''}`
+      );
+    }
+
+    el = await fixture(`<${TEST_TAG}></${TEST_TAG}>`);
+    el.identifier = identifier;
+    el.loanTotalTime = 3600;
+    localCache = new LocalCache({ namespace: 'loanRenew' });
+    el.localCache = localCache;
+    // The demo/test environment's ActionsHandlerService fakes a renew_loan
+    // success after a 5s delay to simulate a real network round-trip.
+    await localCache.delete(`${identifier}-loanTime`);
+  });
+
+  afterEach(() => {
+    sinon.restore();
+  });
+
+  it('awaits the loanTime cache write before dispatching loanAutoRenewed, and fires the renew analytics event only on success', async function test() {
+    this.timeout(7000);
+
+    const storeStatsSpy = sinon.spy(el.loanAnanlytics, 'storeLoanStatsCount');
+    const sendEventSpy = sinon.spy(el.loanAnanlytics, 'sendEvent');
+
+    let loanTimeWhenEventFired;
+    el.addEventListener('loanAutoRenewed', () => {
+      loanTimeWhenEventFired = localCache.get(`${identifier}-loanTime`);
+    });
+
+    el.handleLoanRenewNow('auto');
+
+    // ActionsHandlerService fakes a 5s delay for renew_loan in this
+    // (localhost) test environment — wait it out, matching the existing
+    // pattern used elsewhere in this test suite for the same fake delay.
+    await aTimeout(5500);
+
+    // The race this guards against: loanAutoRenewed used to dispatch
+    // before setBrowseTimeSession()'s cache write landed, so a listener
+    // reading the cache immediately could still see the old/deleted value.
+    const resolvedLoanTime = await loanTimeWhenEventFired;
+    expect(resolvedLoanTime).to.exist;
+    expect(resolvedLoanTime.getTime()).to.be.greaterThan(Date.now());
+
+    expect(storeStatsSpy.calledWith(identifier, 'autorenew')).to.be.true;
+    // storeLoanStatsCount fires its own matrix-stats sendEvent internally,
+    // so assert on the specific renew-success event rather than call count.
+    expect(
+      sendEventSpy.calledWith(
+        analyticsCategories.browse,
+        analyticsActions.browseRenew,
+        analyticsLabels.browseAutoRenew,
+        identifier
+      )
+    ).to.be.true;
+  });
+
+  it('does not fire the renew analytics event when the renewal fails', async () => {
+    const sendEventSpy = sinon.spy(el.loanAnanlytics, 'sendEvent');
+    const storeStatsSpy = sinon.spy(el.loanAnanlytics, 'storeLoanStatsCount');
+
+    // Force ActionsHandlerService's shouldReturnError branch for this call.
+    const originalSearch = window.location.search;
+    const params = new URLSearchParams(originalSearch);
+    params.set('error', 'true');
+    window.history.pushState({}, '', `?${params.toString()}`);
+
+    let errorEventDetail;
+    el.addEventListener('lendingActionError', ({ detail }) => {
+      errorEventDetail = detail;
+    });
+
+    try {
+      el.handleLoanRenewNow('auto');
+      await aTimeout(200);
+
+      expect(errorEventDetail?.action).to.equal('renew_loan');
+      // dispatchActionError fires its own 'LendingServiceError' analytics
+      // event on any error — that's expected. What must NOT fire is the
+      // renew-success event this fix gates on `isRenewal`.
+      expect(
+        sendEventSpy.calledWith(
+          analyticsCategories.browse,
+          analyticsActions.browseRenew
+        )
+      ).to.be.false;
+      expect(storeStatsSpy.calledWith(identifier, 'autorenew')).to.be.false;
+    } finally {
+      window.history.pushState({}, '', `${window.location.pathname}${originalSearch}`);
+    }
+  });
+});

package/test/core/services/loan-token-poller.test.js

@@ -56,3 +56,79 @@ describe('Get Loan Token', () => {
     expect(tokenPoller.loanTokenInterval).to.equal(undefined);
   });
 });
+
+describe('handleTokenError retry (WEBDEV-8322 follow-up)', () => {
+  // Lending::do_renew() (backend) deletes the old loan record and writes
+  // a brand-new one on every renewal, so the initial create_token call
+  // right after a renewal can race that write's propagation and come
+  // back with this exact error even though the loan is genuinely valid.
+  const staleLoanReadError = {
+    error: 'You do not currently have this book borrowed.',
+  };
+
+  const makeTokenPoller = () =>
+    new LoanTokenPoller(
+      'identifier1',
+      'browsed',
+      () => {},
+      () => {},
+      2000
+    );
+
+  it('retries the initial call on a stale-loan-read error instead of failing immediately', () => {
+    const tokenPoller = makeTokenPoller();
+    const handleLoanTokenPollerSpy = Sinon.spy(
+      tokenPoller,
+      'handleLoanTokenPoller'
+    );
+    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
+    const clock = Sinon.useFakeTimers();
+
+    try {
+      tokenPoller.handleTokenError(staleLoanReadError, true, 0);
+
+      expect(errorCallbackSpy.called).to.be.false;
+
+      clock.tick(tokenPoller.initialTokenRetryDelay);
+
+      expect(handleLoanTokenPollerSpy.calledWith(true, 1)).to.be.true;
+    } finally {
+      clock.restore();
+    }
+  });
+
+  it('gives up and calls errorCallback after exhausting retries', () => {
+    const tokenPoller = makeTokenPoller();
+    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
+
+    tokenPoller.handleTokenError(
+      staleLoanReadError,
+      true,
+      tokenPoller.maxInitialTokenRetries
+    );
+
+    expect(errorCallbackSpy.calledOnce).to.be.true;
+  });
+
+  it('does not retry a routine (non-initial) poll on the same error', () => {
+    const tokenPoller = makeTokenPoller();
+    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
+
+    tokenPoller.handleTokenError(staleLoanReadError, false, 0);
+
+    expect(errorCallbackSpy.calledOnce).to.be.true;
+  });
+
+  it('does not retry a genuinely different error, even on the initial call', () => {
+    const tokenPoller = makeTokenPoller();
+    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
+
+    tokenPoller.handleTokenError(
+      { error: 'loan token not found. please try again later.' },
+      true,
+      0
+    );
+
+    expect(errorCallbackSpy.calledOnce).to.be.true;
+  });
+});

package/test/ia-book-actions.test.js

@@ -689,6 +689,149 @@ describe('autoRenewExpiredLoan', () => {
     expect(el.loanRenewInProgress).to.be.false;
   });
 
+  it('does not reset postInitComplete until renewal is confirmed, not on the optimistic flip (WEBDEV-8322 follow-up)', async () => {
+    // Regression: resetting postInitComplete (which lets BookReader
+    // re-initialize via create_token) as soon as autoRenewExpiredLoan()
+    // optimistically flips browsingExpired would let create_token race
+    // ahead of renew_loan's response, reading the still-expired loan
+    // record and minting a bad access cookie — breaking page images with
+    // CORS/auth errors until the next natural token refresh.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: true,
+        },
+      })
+    );
+    await el.updateComplete;
+    el.postInitComplete = true;
+    el.lendingBarPostInit = Sinon.spy();
+
+    await el.localCache.set({
+      key: 'foobar-loanTime',
+      value: new Date(new Date().getTime() + 3600 * 1000),
+      ttl: 3600,
+    });
+
+    el.autoRenewExpiredLoan();
+    await el.updateComplete;
+
+    // Still true right after the optimistic flip — must not reset early.
+    expect(el.postInitComplete).to.be.true;
+    expect(el.lendingBarPostInit.called).to.be.false;
+
+    await aTimeout(50);
+
+    const collapsibleActionGroupEl = el.shadowRoot.querySelector(
+      'collapsible-action-group'
+    );
+    collapsibleActionGroupEl.dispatchEvent(
+      new CustomEvent('loanAutoRenewed', {
+        detail: { data: { loan: { identifier: 'foobar' } } },
+      })
+    );
+
+    await aTimeout(200);
+    await el.updateComplete;
+
+    // The confirmed renewal must have forced a fresh create_token cycle
+    // that re-ran lendingBarPostInit() (BookReader re-init) — postInitComplete
+    // itself ends up true again once that cycle completes, so we assert on
+    // the re-init actually having fired instead of the transient flag.
+    expect(el.lendingBarPostInit.calledOnce).to.be.true;
+    expect(el.recoveringFromLoanExpiry).to.be.false;
+  });
+
+  it('does not start the token poller (create_token) on the optimistic flip, only after renewal is confirmed', async () => {
+    // Regression: even without re-running lendingBarPostInit early, the
+    // token poller restart in setupLendingToolbarActions() was ungated —
+    // it fired on the optimistic lendingStatus flip too, calling
+    // create_token against the still-expired loan. When that failed,
+    // handleLendingActionError cleared ALL lending intervals (including
+    // the countdown timer) and flipped user_has_browsed false, sometimes
+    // permanently killing the countdown if it lost the race against the
+    // real renewal confirming afterward.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: true,
+        },
+      })
+    );
+    await el.updateComplete;
+
+    await el.localCache.set({
+      key: 'foobar-loanTime',
+      value: new Date(new Date().getTime() + 3600 * 1000),
+      ttl: 3600,
+    });
+
+    const startTokenPollerSpy = Sinon.spy(el, 'startLoanTokenPoller');
+
+    el.autoRenewExpiredLoan();
+    await el.updateComplete;
+    await aTimeout(150); // let the 100ms token-poller-restart check run
+
+    expect(startTokenPollerSpy.called).to.be.false;
+
+    await aTimeout(50);
+    const collapsibleActionGroupEl = el.shadowRoot.querySelector(
+      'collapsible-action-group'
+    );
+    collapsibleActionGroupEl.dispatchEvent(
+      new CustomEvent('loanAutoRenewed', {
+        detail: { data: { loan: { identifier: 'foobar' } } },
+      })
+    );
+
+    await aTimeout(200);
+    await el.updateComplete;
+
+    expect(startTokenPollerSpy.calledOnce).to.be.true;
+  });
+
+  it('does not touch postInitComplete on a routine (non-expiry) renewal', async () => {
+    // A background top-up renewal (loan never actually lapsed) never
+    // interrupted BookReader, so it must not force a re-init.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: { user_has_browsed: true, browsingExpired: false },
+      })
+    );
+    await el.updateComplete;
+    el.postInitComplete = true;
+    el.loanRenewResult = { texts: '', renewNow: true, renewType: 'auto' };
+    el.lendingBarPostInit = Sinon.spy();
+
+    await el.localCache.set({
+      key: 'foobar-loanTime',
+      value: new Date(new Date().getTime() + 3600 * 1000),
+      ttl: 3600,
+    });
+
+    const collapsibleActionGroupEl = el.shadowRoot.querySelector(
+      'collapsible-action-group'
+    );
+    collapsibleActionGroupEl.dispatchEvent(
+      new CustomEvent('loanAutoRenewed', {
+        detail: { data: { loan: { identifier: 'foobar' } } },
+      })
+    );
+
+    await aTimeout(100);
+    await el.updateComplete;
+
+    expect(el.lendingBarPostInit.called).to.be.false;
+  });
+
   it('clears loanRenewInProgress and shows unavailable modal on renew_loan failure', async () => {
     const el = await fixture(
       container({
@@ -719,6 +862,358 @@ describe('autoRenewExpiredLoan', () => {
   });
 });
 
+describe('BookReader:userAction race regression (WEBDEV-8322)', () => {
+  it('does not let autoLoanRenewChecker clobber an in-flight expired-loan renewal', async () => {
+    // Get borrowType derived as 'browsed' first, same as the
+    // "Expiring book cancels interval" test above — hasExpired renders
+    // leave borrowType untouched, so it must already be 'browsed' before
+    // the loan is marked expired.
+    const baseStatus = {
+      is_lendable: true,
+      user_has_browsed: true,
+      browsingExpired: false,
+    };
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: baseStatus,
+      })
+    );
+    await el.updateComplete;
+    expect(el.borrowType).to.equal('browsed');
+
+    el.lendingStatus = { ...baseStatus, browsingExpired: true };
+    await el.updateComplete;
+
+    const autoLoanRenewCheckerSpy = Sinon.spy(el, 'autoLoanRenewChecker');
+
+    window.dispatchEvent(new CustomEvent('BookReader:userAction'));
+
+    // autoRenewExpiredLoan()'s setTimeout(0) sets renewNow=true. If the old
+    // bug were present, the still-live lendingStatus.browsingExpired check
+    // would (wrongly) also let autoLoanRenewChecker(true) run — which reads
+    // the already-deleted loanTime cache key and overwrites renewNow back
+    // to false. Give both paths plenty of time to resolve.
+    await aTimeout(300);
+
+    expect(autoLoanRenewCheckerSpy.called).to.be.false;
+    expect(el.loanRenewResult.renewNow).to.be.true;
+  });
+
+  it('ignores repeated BookReader:userAction events firing in quick succession (e.g. from a scroll)', async () => {
+    // Regression: a single scroll gesture can fire BookReader:userAction
+    // several times in rapid succession. autoLoanRenewChecker() had no
+    // guard against concurrent/repeated invocation, unlike
+    // autoRenewExpiredLoan() — each event spun up its own LoanRenewHelper,
+    // racing to overwrite this.loanRenewResult and potentially
+    // re-triggering renew_loan/create_token while a prior call from an
+    // earlier event was still in flight or had just landed.
+    const baseStatus = {
+      is_lendable: true,
+      user_has_browsed: true,
+      browsingExpired: false,
+    };
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: baseStatus,
+      })
+    );
+    await el.updateComplete;
+    expect(el.borrowType).to.equal('browsed');
+
+    el.loanRenewInProgress = true;
+
+    const loanRenewHelperSpy = Sinon.spy(el, 'autoLoanRenewChecker');
+
+    // Simulate a scroll firing the event several times back to back.
+    window.dispatchEvent(new CustomEvent('BookReader:userAction'));
+    window.dispatchEvent(new CustomEvent('BookReader:userAction'));
+    window.dispatchEvent(new CustomEvent('BookReader:userAction'));
+    await aTimeout(50);
+
+    // The method is still called each time (the guard is inside it), but
+    // must no-op instead of spinning up a new LoanRenewHelper each time.
+    expect(loanRenewHelperSpy.callCount).to.equal(3);
+    expect(el.loanRenewHelper).to.be.undefined;
+  });
+});
+
+describe('handleLendingActionError - loanRenewInProgress reset', () => {
+  it('clears loanRenewInProgress on any renew_loan failure, not just "not available"', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: { user_has_browsed: true, browsingExpired: true },
+      })
+    );
+    await el.updateComplete;
+
+    el.loanRenewInProgress = true;
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'renew_loan',
+        data: { error: 'some other unrelated failure' },
+      },
+    });
+
+    expect(el.loanRenewInProgress).to.be.false;
+  });
+});
+
+describe('handleLendingActionError - create_token failures must not stop the countdown (WEBDEV-8322 follow-up)', () => {
+  it('does not clear the reading countdown on a create_token failure', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+    expect(window.IALendingIntervals.timerCountdown).to.not.equal(0);
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'create_token',
+        data: { error: 'loan token not found. please try again later.' },
+      },
+    });
+
+    // The countdown must keep running — a token refresh hiccup says
+    // nothing about how much time is left on the loan itself.
+    expect(window.IALendingIntervals.timerCountdown).to.not.equal(0);
+  });
+
+  it('shows the error modal for a create_token failure that reaches here (retries already exhausted)', async () => {
+    // By the time handleLendingActionError runs for a create_token
+    // failure, LoanTokenPoller has already retried and given up (see
+    // loan-token-poller.js's handleTokenError) — this is a genuine
+    // failure, so the patron must be told instead of it happening
+    // silently.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+
+    const showErrorModalSpy = Sinon.spy(el, 'showErrorModal');
+    const errorMsg = 'loan token not found. please try again later.';
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'create_token',
+        data: { error: errorMsg },
+      },
+    });
+
+    expect(showErrorModalSpy.calledOnceWith(errorMsg, 'create_token')).to.be
+      .true;
+    expect(el.lendingStatus.user_has_browsed).to.be.false;
+  });
+
+  it('still clears everything on a renew_loan failure', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+    expect(window.IALendingIntervals.timerCountdown).to.not.equal(0);
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'renew_loan',
+        data: { error: 'some other unrelated failure' },
+      },
+    });
+
+    expect(window.IALendingIntervals.timerCountdown).to.equal(0);
+  });
+
+  it('shows the same unavailable-modal-and-refresh path for any renew_loan failure, regardless of message text', async () => {
+    // Regression: branching on errorMsg.match(/not available/) to decide
+    // how to recover was fragile — the server can return any message
+    // (e.g. a lending limit hit), and guessing which lendingStatus fields
+    // are now accurate client-side is error-prone. Every renew_loan
+    // failure now shows the real error and refreshes the page on
+    // dismissal (showLoanUnavailableModal's Okay button), rather than
+    // trying to patch up state without reloading from the server.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          is_lendable: true,
+          user_has_browsed: true,
+          browsingExpired: false,
+          available_to_browse: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+
+    const showUnavailableSpy = Sinon.spy(el, 'showLoanUnavailableModal');
+    const lendingLimitMsg =
+      'Your account has hit a lending limit. Please try again later or contact info@archive.org.';
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'renew_loan',
+        data: { error: lendingLimitMsg },
+      },
+    });
+    await el.updateComplete;
+
+    expect(showUnavailableSpy.calledOnceWith(lendingLimitMsg)).to.be.true;
+  });
+
+  it('updates lendingStatus immediately on a renew_loan failure — Borrow state, timer cleared', async () => {
+    // The modal's Okay button refreshes the page, but that shouldn't be
+    // the only thing correcting the UI — while the modal is still open,
+    // the action bar must already show Borrow instead of "Return now"
+    // with a stale countdown value from before the failed renewal.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          is_lendable: true,
+          user_has_browsed: true,
+          browsingExpired: false,
+          available_to_browse: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'renew_loan',
+        data: {
+          error:
+            'Your account has hit a lending limit. Please try again later or contact info@archive.org.',
+        },
+      },
+    });
+    await el.updateComplete;
+
+    expect(el.lendingStatus.user_has_browsed).to.be.false;
+    expect(el.lendingStatus.available_to_browse).to.be.true;
+    expect(el.lendingStatus.secondsLeftOnLoan).to.equal(0);
+    expect(el.primaryActions[0].text).to.not.equal('Return now');
+  });
+
+  it('also shows the unavailable modal for the "not available" message, with its own text', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          is_lendable: true,
+          user_has_browsed: true,
+          browsingExpired: false,
+          secondsLeftOnLoan: 100,
+        },
+      })
+    );
+    await el.updateComplete;
+
+    const showUnavailableSpy = Sinon.spy(el, 'showLoanUnavailableModal');
+    const notAvailableMsg = 'This book is not available to borrow at this time.';
+
+    el.handleLendingActionError({
+      detail: {
+        action: 'renew_loan',
+        data: { error: notAvailableMsg },
+      },
+    });
+    await el.updateComplete;
+
+    expect(showUnavailableSpy.calledOnceWith(notAvailableMsg)).to.be.true;
+  });
+});
+
+describe('showWarningModal', () => {
+  it('shows a headline, one Okay button, and an info-icon help link; Okay dismisses without renewing', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: { user_has_browsed: true, secondsLeftOnLoan: 100 },
+      })
+    );
+    await el.updateComplete;
+
+    await el.showWarningModal();
+
+    const modalManagerEl = document.body.querySelector('modal-manager');
+    const modalTemplateEl =
+      modalManagerEl.shadowRoot.querySelector('modal-template');
+    const headline =
+      modalTemplateEl.shadowRoot.querySelector('.headline')?.textContent;
+    expect(headline).to.contain('Are you still there?');
+
+    const helpLink = modalTemplateEl.shadowRoot.querySelector(
+      'a[href="https://help.archive.org/help/borrowing-from-the-lending-library"]'
+    );
+    expect(helpLink).to.exist;
+
+    const buttons = modalManagerEl.shadowRoot.querySelectorAll(
+      '#book-action-bar-custom-buttons button'
+    );
+    expect(buttons.length).to.equal(1);
+    expect(buttons[0].textContent).to.contain('Okay');
+
+    buttons[0].click();
+
+    expect(el.warningModalOpen).to.be.false;
+    expect(el.warningModalDismissed).to.be.true;
+    expect(el.loanRenewResult.renewNow).to.be.false;
+  });
+
+  it('does not reopen while already open', async () => {
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: { user_has_browsed: true, secondsLeftOnLoan: 100 },
+      })
+    );
+    await el.updateComplete;
+
+    await el.showWarningModal();
+    const showModalSpy = Sinon.spy(el.modal, 'showModal');
+
+    await el.showWarningModal();
+
+    expect(showModalSpy.called).to.be.false;
+  });
+});
+
 describe('Shared Resize Observer', () => {
   it('can receive a Shared Resize Observer', async () => {
     const sharedObserverStub = new SharedResizeObserver();