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

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-alpha11",
   "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

@@ -61,6 +61,7 @@ export default class IABookActions extends LitElement {
       modal: { Object },
       tokenDelay: { type: Number },
       timerExecutionSeconds: { type: Number },
+      userActionGracePeriod: { type: Number },
       localCache: { type: Object },
       loanRenewTimeConfig: { type: Object },
       loanRenewResult: { type: Object },
@@ -83,6 +84,14 @@ export default class IABookActions extends LitElement {
     this.tokenDelay = 120; // in seconds
     this.timerExecutionSeconds = 30;
 
+    /**
+     * How long (ms) after bindLoanRenewEvents() runs to ignore
+     * BookReader:userAction events — BookReader fires that event on its
+     * own init-time jump to the last-read page, not just on genuine
+     * interaction. @see bindLoanRenewEvents
+     */
+    this.userActionGracePeriod = 2000;
+
     // private props
     this.postInitComplete = false;
     this.primaryActions = [];
@@ -96,6 +105,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 +198,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();
     }
   }
@@ -267,7 +292,14 @@ export default class IABookActions extends LitElement {
 
     this.borrowType = actions.borrowType ? actions.borrowType : null;
 
-    if (this.borrowType === 'browsed') {
+    // Don't (re)start the countdown while a renewal is in flight — the
+    // optimistic browsingExpired flip in autoRenewExpiredLoan() (which
+    // triggers this same setupLendingToolbarActions() call) happens before
+    // renewal is confirmed, so secondsLeftOnLoan could still be a stale
+    // value from before the renewal. Wait for handleLoanAutoRenewed() to
+    // confirm the real value and clear loanRenewInProgress before showing
+    // a countdown again.
+    if (this.borrowType === 'browsed' && !this.loanRenewInProgress) {
       // start timer for loan-renew
       await this.startTimerCountdown();
 
@@ -283,11 +315,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();
@@ -300,21 +343,40 @@ export default class IABookActions extends LitElement {
    * 2. IABookActions:loanRenew - dispatched from timer-countdown component
    */
   bindLoanRenewEvents() {
+    this.userActionReadyAt = Date.now() + this.userActionGracePeriod;
+
     /**
      * dispatched this event from bookreader page changed
      */
     window.addEventListener('BookReader:userAction', () => {
+      if (Date.now() < this.userActionReadyAt) {
+        log(
+          '[IABookActions] BookReader:userAction ignored — within startup grace period'
+        );
+        return;
+      }
+
+      // 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 +434,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,16 +467,23 @@ export default class IABookActions extends LitElement {
   autoRenewExpiredLoan() {
     if (this.loanRenewInProgress) return;
     this.loanRenewInProgress = true;
+    this.recoveringFromLoanExpiry = true;
 
     this.modal?.closeModal();
 
     // Optimistically flip browsingExpired back to false so the action bar
     // stays red (patronIsReadingAction) while the renew_loan request is in
-    // flight, instead of showing the blue "Borrow" state.
+    // flight, instead of showing the blue "Borrow" state. Deliberately NOT
+    // resetting secondsLeftOnLoan here — the renewal hasn't been confirmed
+    // yet (it can take several seconds, or genuinely fail), so showing a
+    // full hour before we know the outcome would be misleading. The real
+    // value is set once handleLoanAutoRenewed() confirms success;
+    // loanRenewInProgress (already true above) is the signal consumers
+    // should use to show a "renewing" state instead of trusting the
+    // countdown during this window.
     this.lendingStatus = {
       ...this.lendingStatus,
       browsingExpired: false,
-      secondsLeftOnLoan: this.loanRenewTimeConfig.loanTotalTime,
     };
 
     // Defer renewNow until after lendingStatus timer setup completes.
@@ -457,19 +536,14 @@ export default class IABookActions extends LitElement {
       headerColor: '#194880',
       showCloseButton: false,
       closeOnBackdropClick: false,
-      message: html`<span
-        style="display:inline-flex;align-items:center;flex-wrap:nowrap;gap:4px;"
-      >
-        <span>${this.loanRenewHelper?.getMessageTexts(
-          warningTexts,
-          secondsLeft
-        )}</span>
+      message: html`<span>
+        ${this.loanRenewHelper?.getMessageTexts(warningTexts, secondsLeft)}
         <a
           href="https://help.archive.org/help/borrowing-from-the-lending-library"
           target="_blank"
           title="Get more info on borrowing from The Lending Library"
           data-event-click-tracking="BookReader|BrowsableMoreInfo"
-          style="display:inline-flex;flex-shrink:0;line-height:0;"
+          style="display:inline-block;vertical-align:middle;line-height:0;margin-left:4px;"
         >
           ${infoIcon}
         </a>
@@ -532,20 +606,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 +714,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 +737,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 +811,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 +975,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;
     }
   }