@internetarchive/ia-book-actions 1.4.4-alpha9 → 1.4.5

package/src/ia-book-actions.js

@@ -20,7 +20,7 @@ import { LoanTokenPoller } from './core/services/loan-token-poller.js';
 import { LoanRenewHelper } from './core/services/loan-renew-helper.js';
 import log from './core/services/log.js';
 import { URLHelper } from './core/config/url-helper.js';
-import { infoIcon } from './assets/data/info.js';
+import { infoIcon } from './assets/data/info-icon.js';
 
 export const events = {
   browseExpired: 'IABookReader:BrowsingHasExpired',
@@ -55,12 +55,15 @@ export default class IABookActions extends LitElement {
         type: Function,
         attribute: false,
       },
+      reloadPageImages: {
+        type: Function,
+        attribute: false,
+      },
       barType: { type: String },
       sharedObserver: { attribute: false },
       disableActionGroup: { type: Boolean },
       modal: { Object },
       tokenDelay: { type: Number },
-      tokenPollerRenewalDelay: { type: Number },
       timerExecutionSeconds: { type: Number },
       localCache: { type: Object },
       loanRenewTimeConfig: { type: Object },
@@ -78,6 +81,7 @@ export default class IABookActions extends LitElement {
     this.width = 0;
     this.bwbPurchaseUrl = '';
     this.lendingBarPostInit = () => {};
+    this.reloadPageImages = () => {};
     this.barType = 'action'; // 'title'|'action'
     this.sharedObserver = undefined;
     this.disableActionGroup = false;
@@ -98,34 +102,26 @@ 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
+     * True while 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 — see
      * handleLoanAutoRenewed.
      */
     this.recoveringFromLoanExpiry = false;
 
     /**
-     * Buffer (ms) before the first create_token call that follows a
-     * confirmed recovery renewal — Lending::do_renew() (backend) deletes
-     * the old loan and writes a brand-new one to the datanode storage, so
-     * create_token's lookup can otherwise race that write's propagation.
-     * Exposed as a property (rather than a hardcoded constant) so it's
-     * configurable per-deployment and overridable to 0 in tests.
+     * True right after a confirmed renewal (any kind), until the token
+     * poller restarts. renew_loan's own response already carries a valid
+     * access token, so that restart should skip its normal immediate
+     * create_token call — see handleLoanAutoRenewed/
+     * setupLendingToolbarActions.
      */
-    this.tokenPollerRenewalDelay = 2000;
+    this.skipNextInitialTokenCall = false;
 
     this.warningModalOpen = false;
 
-    /**
-     * Once the patron has seen & dismissed the informational warning modal,
-     * don't nag them again with the same modal every timer tick — only a
-     * real renewal (via interacting with the book) clears this, giving the
-     * next pre-expiry window its own single warning.
-     * @see loanRenewAttempt
-     * @see handleLoanAutoRenewed
-     */
+    /** Once dismissed, don't re-show the warning modal every tick — only
+     * a real renewal (handleLoanAutoRenewed) re-arms it. */
     this.warningModalDismissed = false;
 
     /**
@@ -159,9 +155,9 @@ export default class IABookActions extends LitElement {
   }
 
   disconnectedCallback() {
-    // clear all intervals for lending system
+    super.disconnectedCallback();
     window?.IALendingIntervals?.clearAll();
-
+    this.tokenPoller?.disconnectedCallback();
     this.sentryCaptureMsg(sentryLogs.disconnectedCallback);
     this.disconnectResizeObserver();
   }
@@ -200,12 +196,8 @@ 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.
+      // Pause the countdown for the renew_loan round-trip, for every
+      // renewal path — cleared by handleLoanAutoRenewed().
       this.loanRenewInProgress = true;
       window.IALendingIntervals.clearAll();
     }
@@ -243,17 +235,53 @@ export default class IABookActions extends LitElement {
   }
   /** End SharedObserver resize handler */
 
+  /**
+   * Recompute the action bar (title, buttons, colors, borrowType) from the
+   * current lendingStatus.
+   *
+   * @returns {boolean} false when there are no actions to apply, in which
+   *   case callers should bail out rather than continue with stale state.
+   */
+  applyLendingActions() {
+    this.lendingOptions = new GetLendingActions(
+      this.userid,
+      this.identifier,
+      this.lendingStatus,
+      this.bwbPurchaseUrl
+    );
+    const actions = this.lendingOptions.getCurrentLendingActions();
+
+    if (!actions) return false;
+
+    this.primaryTitle = actions.primaryTitle;
+    this.primaryActions = actions.primaryActions?.filter(action => {
+      return action != null;
+    });
+    this.primaryColor = actions.primaryColor;
+    this.secondaryActions = actions.secondaryActions?.filter(action => {
+      return action != null;
+    });
+
+    this.borrowType = actions.borrowType ? actions.borrowType : null;
+
+    return true;
+  }
+
   async setupLendingToolbarActions() {
     const hasExpired =
       'browsingExpired' in this.lendingStatus &&
       this.lendingStatus?.browsingExpired;
     if (hasExpired) {
-      // Intentionally do NOT recompute primaryActions/primaryColor/borrowType
-      // here — per the ticket, auto-return must not visibly change anything.
-      // The action bar stays exactly as it looked while reading; only a
-      // successful silent renewal or the "unavailable" error modal are
-      // allowed to change what's shown next.
-      log('[IABookActions] browsing expired — leaving action bar untouched');
+      // Auto-return must not visibly change the bar — unless nothing's
+      // rendered yet (fresh load of an already-expired loan).
+      if (this.primaryActions?.length) {
+        log('[IABookActions] browsing expired — leaving action bar untouched');
+      } else {
+        log(
+          '[IABookActions] browsing expired on first render — populating action bar'
+        );
+        this.applyLendingActions();
+      }
 
       if (!this.tokenPoller) {
         this.sentryCaptureMsg(sentryLogs.bookWasExpired);
@@ -273,32 +301,20 @@ export default class IABookActions extends LitElement {
       return;
     }
 
-    this.lendingOptions = new GetLendingActions(
-      this.userid,
-      this.identifier,
-      this.lendingStatus,
-      this.bwbPurchaseUrl
-    );
-    const actions = this.lendingOptions.getCurrentLendingActions();
-
-    if (!actions) return;
+    if (!this.applyLendingActions()) return;
 
-    this.primaryTitle = actions.primaryTitle;
-    this.primaryActions = actions.primaryActions?.filter(action => {
-      return action != null;
-    });
-    this.primaryColor = actions.primaryColor;
-    this.secondaryActions = actions.secondaryActions?.filter(action => {
-      return action != null;
-    });
-
-    this.borrowType = actions.borrowType ? actions.borrowType : null;
+    // primaryActions/borrowType/etc are plain fields, not reactive
+    // properties, so nothing pushes them to the rendered template (and
+    // from there to <collapsible-action-group>) on its own. Do that now,
+    // unconditionally — the early returns below (not borrowed, title bar)
+    // must not skip it, or the action bar visibly goes stale (e.g. a
+    // create_token failure resetting to Borrow never actually shows it).
+    this.requestUpdate();
 
-    if (this.borrowType === 'browsed') {
-      // start timer for loan-renew
+    // Don't (re)start the countdown mid-renewal — secondsLeftOnLoan could
+    // still be stale until handleLoanAutoRenewed() confirms it.
+    if (this.borrowType === 'browsed' && !this.loanRenewInProgress) {
       await this.startTimerCountdown();
-
-      // start timer for browsed.
       await this.startBrowseTimer();
     }
 
@@ -308,40 +324,35 @@ export default class IABookActions extends LitElement {
       return;
     }
 
-    /**
-     * tokenPoller determines if user has loan token for this book
-     * - 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.
-     */
+    // Wait until any in-flight renewal is confirmed before (re)starting the
+    // poller, so create_token isn't called against a not-yet-renewed loan.
     setTimeout(() => {
       if (
         !hasExpired &&
         !this.loanRenewInProgress &&
         !window.IALendingIntervals.tokenPoller
       ) {
-        // Lending::do_renew() (backend) doesn't extend the existing loan —
-        // it DELETES it and writes a brand-new loan record to the datanode
-        // storage. create_token's lookup for that record can race the
-        // write's propagation and come back empty ("you do not currently
-        // have this book borrowed"), even though the renewal that was just
-        // confirmed genuinely succeeded moments earlier. Give the write a
-        // moment to settle before the first create_token call that follows
-        // a real recovery — same underlying datanode-propagation concern
-        // the existing 50-second buffer in loanRenewAttempt() guards
-        // against for the routine renewal path.
-        const tokenPollerDelay = this.recoveringFromLoanExpiry
-          ? this.tokenPollerRenewalDelay
-          : 0;
+        // Any confirmed renewal's response already minted a valid access
+        // token (see handleLoanAutoRenewed) — the poller only needs to
+        // start its recurring check, not fire an immediate confirming
+        // create_token call too.
+        const skipInitialCall = this.skipNextInitialTokenCall;
+        this.skipNextInitialTokenCall = false;
         this.recoveringFromLoanExpiry = false;
-        setTimeout(() => this.startLoanTokenPoller(), tokenPollerDelay);
+        this.startLoanTokenPoller(skipInitialCall);
       }
     }, 100);
+  }
 
-    this.requestUpdate();
+  /**
+   * Is this BookReader's own init-time jump to the last-read page, rather
+   * than a real patron interaction (which fires the identical event)? Only
+   * an explicit `false` counts; a missing flag must be treated as real.
+   * @param {Event} event - the BookReader:userAction event
+   * @returns {boolean}
+   */
+  isBookReaderInitAction(event) {
+    return event?.detail?.props?.init?.initComplete === false;
   }
 
   /**
@@ -354,15 +365,17 @@ 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.
+    window.addEventListener('BookReader:userAction', event => {
+      if (this.isBookReaderInitAction(event)) {
+        log(
+          '[IABookActions] BookReader:userAction ignored — fired by BookReader init'
+        );
+        return;
+      }
+
+      // Capture before autoRenewExpiredLoan() runs — it optimistically
+      // flips browsingExpired to false, which would otherwise also let
+      // autoLoanRenewChecker() run and clobber the in-flight renewal.
       const wasExpired = this.lendingStatus.browsingExpired;
 
       log('[IABookActions] BookReader:userAction received', {
@@ -370,7 +383,6 @@ export default class IABookActions extends LitElement {
         browsingExpired: wasExpired,
       });
 
-      // If the loan expired while the tab stayed visible, auto-renew on page turn
       if (wasExpired) {
         this.autoRenewExpiredLoan();
       }
@@ -380,18 +392,18 @@ export default class IABookActions extends LitElement {
       }
     });
 
-    /**
-     * auto-renew interval may stale when tab is in background,
-     * so when user open that tab again,
-     * the [visibilitychange] event can trigger timer to show relavent messages
-     */
+    // A tab in the background can have its intervals throttled/paused, so
+    // re-check status when the patron comes back to it.
     document.addEventListener('visibilitychange', async () => {
       if (document.hidden) {
         log('[IABookActions] visibilitychange: tab backgrounded');
         return;
       }
 
-      log('[IABookActions] visibilitychange: tab foregrounded', this.borrowType);
+      log(
+        '[IABookActions] visibilitychange: tab foregrounded',
+        this.borrowType
+      );
 
       try {
         // Loan already expired while tab was hidden — try to silently renew
@@ -413,9 +425,11 @@ export default class IABookActions extends LitElement {
           if (secondsLeft >= this.timerExecutionSeconds) {
             this.loanStatusCheckInterval(Number(secondsLeft));
           } else {
-            // Loan expired while user was away — try to silently renew
+            // Loan expired while away — silently renew. Only clear
+            // intervals; disconnectedCallback() would drop the resize
+            // observer for a session that's still continuing.
+            window?.IALendingIntervals?.clearAll();
             this.autoRenewExpiredLoan();
-            this.disconnectedCallback();
           }
         }
       } catch (error) {
@@ -433,14 +447,8 @@ 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.
+    // Re-entrancy guard against rapid BookReader:userAction events (e.g. a
+    // single scroll firing several in quick succession).
     if (this.loanRenewInProgress) return;
 
     this.loanRenewHelper = new LoanRenewHelper(
@@ -455,28 +463,31 @@ export default class IABookActions extends LitElement {
   }
 
   /**
-   * Attempt to automatically renew a browse loan that has expired.
-   * Called on visibilitychange (user returns to tab) or on page turn when
-   * the loan has expired but the book may still be available.
-   *
-   * Reuses the same renew_loan path as the automatic loan-renew checker.
-   * On success: handleLoanAutoRenewed() resets the timer seamlessly.
-   * On error: handleLendingActionError() shows showLoanUnavailableModal().
+   * Silently attempt to renew a browse loan that has expired, on
+   * visibilitychange or a page turn. handleLoanAutoRenewed()/
+   * handleLendingActionError() handle the outcome either way.
    */
   autoRenewExpiredLoan() {
-    if (this.loanRenewInProgress) return;
+    if (this.loanRenewInProgress) {
+      log(
+        '[IABookActions] autoRenewExpiredLoan: skipped, renewal already in progress',
+        { identifier: this.identifier }
+      );
+      return;
+    }
+    log('[IABookActions] autoRenewExpiredLoan: starting silent renewal', {
+      identifier: this.identifier,
+    });
     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.
+    // Optimistically flip browsingExpired so the bar stays in the reading
+    // state during the renew_loan round-trip, instead of showing "Borrow".
     this.lendingStatus = {
       ...this.lendingStatus,
       browsingExpired: false,
-      secondsLeftOnLoan: this.loanRenewTimeConfig.loanTotalTime,
     };
 
     // Defer renewNow until after lendingStatus timer setup completes.
@@ -507,7 +518,6 @@ export default class IABookActions extends LitElement {
 
     log('[IABookActions] showWarningModal');
 
-    // Capture texts and secondsLeft before resetting loanRenewResult
     const {
       texts: warningTexts,
       secondsLeft: rawSecondsLeft,
@@ -519,7 +529,6 @@ export default class IABookActions extends LitElement {
       secondsLeft = secondsLeft > 60 ? secondsLeft : 60;
     }
 
-    // clear modal and reset renew state
     this.modal.customModalContent = nothing;
     this.modal?.closeModal();
     this.loanRenewResult = { texts: '', renewNow: false };
@@ -529,19 +538,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>
@@ -559,7 +563,8 @@ export default class IABookActions extends LitElement {
         >
           Okay
         </button>
-      </div> `;
+      </div>
+    `;
 
     this.modal.setAttribute('aria-live', 'assertive');
     await this.modal?.showModal({ config, customModalContent });
@@ -576,7 +581,10 @@ export default class IABookActions extends LitElement {
    * Execute when loan is expired
    */
   async browseHasExpired() {
-    log('[IABookActions] browseHasExpired');
+    log('[IABookActions] browseHasExpired', {
+      identifier: this.identifier,
+      loanRenewInProgress: this.loanRenewInProgress,
+    });
     window?.IALendingIntervals?.clearAll();
 
     const currStatus = {
@@ -589,6 +597,12 @@ export default class IABookActions extends LitElement {
     // remove respected key:value for loan-renew
     await this.localCache.delete(`${this.identifier}-loanTime`);
     await this.localCache.delete(`${this.identifier}-pageChangedTime`);
+    log(
+      '[IABookActions] browseHasExpired: cleared loanTime/pageChangedTime cache',
+      {
+        identifier: this.identifier,
+      }
+    );
 
     // show message after browsed book is expired.
     this.loanRenewResult.renewNow = false;
@@ -596,6 +610,9 @@ export default class IABookActions extends LitElement {
       'This book has been returned due to inactivity.';
 
     this.modal?.closeModal();
+    // Release the warning-modal re-entrancy guard, or it stays latched for
+    // the life of the component.
+    this.warningModalOpen = false;
 
     this.sentryCaptureMsg(sentryLogs.browseHasExpired);
   }
@@ -702,23 +719,31 @@ export default class IABookActions extends LitElement {
   }
 
   /**
-   * Execute after auto loan renewed is completed
-   * - show success message
-   * - then change the remaining time
-   * - reset timer state
+   * Runs after a loan renewal completes (successfully or not): shows the
+   * outcome, updates the remaining time, and resets renewal-in-flight state.
    * @param {object} event
    */
   async handleLoanAutoRenewed({ detail }) {
     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) {
+
+    // Treat anything but a confirmed renewal as a failure, or
+    // loanRenewInProgress stays latched forever (autoLoanRenewChecker/
+    // autoRenewExpiredLoan both no-op on it).
+    if (!activeLoan?.renewal) {
+      this.loanRenewInProgress = false;
       this.recoveringFromLoanExpiry = false;
-      this.showErrorModal(errorMessage, 'handleLoanAutoRenewed');
+      this.warningModalOpen = false;
+
+      // dispatchActionError() has already reported this and shown the
+      // relevant modal; don't stack a second one on top.
+      log('[IABookActions] handleLoanAutoRenewed: not a confirmed renewal', {
+        identifier: this.identifier,
+        activeLoan,
+      });
       return;
     }
 
     if (this.loanRenewResult.renewNow) {
-      // Now, let's reset loan duration & this.lendingStatus
       const loanTime = await this.localCache.get(`${this.identifier}-loanTime`);
 
       // number of seconds left in current loan
@@ -735,18 +760,28 @@ export default class IABookActions extends LitElement {
         ajaxResponse: detail?.data,
       });
 
+      // BookLoanService::attempt_to_renew_loan() mints a valid access
+      // token as part of EVERY renew_loan response, not just a recovery
+      // from expiry — so the poller restart below never needs to fire a
+      // redundant confirming create_token call, regardless of which path
+      // triggered this renewal.
+      this.skipNextInitialTokenCall = true;
+
+      // A page image requested in the gap between expiry and this renewal
+      // landing can come back broken — browsers don't retry a failed <img>
+      // on their own. Retry once, right when access is confirmed good
+      // again, rather than leaving it broken until the patron reloads.
+      this.reloadPageImages();
+
       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().
-        // NOTE: recoveringFromLoanExpiry itself is consumed/reset there,
-        // not here — it decides whether that restart needs a datanode
-        // propagation buffer (see setupLendingToolbarActions).
-        this.postInitComplete = false;
+        // Only now is it safe to re-initialize BookReader — not for a
+        // routine top-up, where that would be disruptive. Call it
+        // directly rather than waiting on a confirming create_token
+        // success: BookLoanService::attempt_to_renew_loan() already
+        // minted a valid access token as part of this renew_loan
+        // response, so there's nothing left to confirm.
+        this.lendingBarPostInit();
+        this.postInitComplete = true;
       }
 
       const currStatus = {
@@ -769,67 +804,55 @@ export default class IABookActions extends LitElement {
     this.loanRenewInProgress = false;
   }
 
-  /**
-   * start timer countdown interval after loan auto-renewed
-   *
-   * @memberof IABookActions
-   */
+  /** Start the countdown interval; ticks read the live secondsLeftOnLoan
+   * each time rather than a value frozen at start, so drift can't compound
+   * across ticks (see loanStatusCheckInterval). */
   async startTimerCountdown() {
     window?.IALendingIntervals?.clearTimerCountdown();
-
-    const secondsLeft = Number(this.lendingStatus.secondsLeftOnLoan);
     this.timeWhenTimerStart = new Date();
 
     window.IALendingIntervals.timerCountdown = setInterval(async () => {
-      // interval execution block
-      await this.loanStatusCheckInterval(secondsLeft);
+      await this.loanStatusCheckInterval(
+        Number(this.lendingStatus.secondsLeftOnLoan)
+      );
     }, this.timerExecutionSeconds * 1000);
   }
 
   /**
-   * setInterval execution function do following things
-   * - if setInterval timer gone off, let's resync
-   * - loan-renew attempt to renew the loan OR show relavant message
-   * - if loan has expired, clear interval timers
-   *
+   * Runs on every countdown tick: resyncs against wall-clock time, attempts
+   * a renewal near expiry, and clears the timers once the loan expires.
    * @param {Number} secondsLeftOnLoan
    */
   async loanStatusCheckInterval(secondsLeftOnLoan) {
     let secondsLeft = secondsLeftOnLoan;
     secondsLeft -= this.timerExecutionSeconds;
-    secondsLeft = Math.round(secondsLeft); // round number
+    secondsLeft = Math.round(secondsLeft);
 
-    // re-sync timer if gone off because of background window
-    // side effect: updates this.lendingStatus & kicks off lifecycle,
-    // if really updated, escape from here
     const resyncd = this.reSyncTimerIfGoneOff(secondsLeft);
-
     if (resyncd.hasSynced) {
       secondsLeft = resyncd.whatShouldLeft;
-      log('[IABookActions] timer: timer re-synced', {
-        secondsLeft,
-      });
+      log('[IABookActions] timer: timer re-synced', { secondsLeft });
     }
 
     log('[IABookActions] timer', {
-      secondsLeft,
-      loanRenewAtLast: this.loanRenewTimeConfig.loanRenewAtLast,
-      pageChangedInLast: this.loanRenewTimeConfig.pageChangedInLast,
+      whatShouldLeft: resyncd.whatShouldLeft,
+      whatIsleft: secondsLeft,
     });
 
-    /**
-     * execute from last 10th minutes to 0th minute
-     * - 10th - to check if user has viewed
-     * - till 0th - to show warning msg with remaining time to auto expired
-     * @see IABookActions::bindLoanRenewEvents
-     */
+    // Re-anchor every tick so drift from wall-clock time can't compound
+    // across ticks that don't happen to trigger a resync above.
+    this.timeWhenTimerStart = new Date();
+    this.lendingStatus = { ...this.lendingStatus, secondsLeftOnLoan: secondsLeft };
+
+    // 10 minutes out: start checking for a renewal. 0: show the "about to
+    // auto-return" warning. @see IABookActions::bindLoanRenewEvents
     if (secondsLeft <= this.loanRenewTimeConfig.loanRenewAtLast) {
       await this.loanRenewAttempt(secondsLeft);
     }
 
-    // clear interval in secondsLeft if less
     if (secondsLeft <= this.timerExecutionSeconds) {
-      this.disconnectedCallback();
+      window?.IALendingIntervals?.clearAll();
+      this.tokenPoller?.disconnectedCallback();
       this.sentryCaptureMsg(sentryLogs.clearOneHourTimer);
     }
   }
@@ -843,6 +866,15 @@ export default class IABookActions extends LitElement {
   reSyncTimerIfGoneOff(timerSecondsLeft) {
     const currentTime = new Date();
 
+    // No prior anchor to compare against -- e.g. visibilitychange calling
+    // loanStatusCheckInterval() directly before startTimerCountdown() ever
+    // ran, which setupLendingToolbarActions() now skips while a renewal is
+    // in flight. Nothing to resync yet; anchor now and report no drift.
+    if (!this.timeWhenTimerStart) {
+      this.timeWhenTimerStart = currentTime;
+      return { hasSynced: false, whatShouldLeft: Math.round(timerSecondsLeft) };
+    }
+
     // current time - loan time
     const diffInSeconds =
       currentTime.getTime() / 1000 - this.timeWhenTimerStart.getTime() / 1000;
@@ -884,13 +916,8 @@ export default class IABookActions extends LitElement {
    */
   async loanRenewAttempt(secondsLeft) {
     let loanSecondsLeft = secondsLeft;
-    /**
-     * auto-renew is not possible in last seconds (let say 50 second) because,
-     * 1. less time to execute ajax call
-     * 2. less time to write loan on datanodes
-     * 3. less time to load images by create_token api
-     * so if seconds left is < 50, just expire the loan
-     */
+    // Under 50s left there isn't enough time for the renew_loan round-trip
+    // and create_token to load images, so just expire the loan.
     if (loanSecondsLeft < 50) {
       log('[IABookActions] loanRenewAttempt: < 50s left, expiring loan');
       await this.browseHasExpired();
@@ -899,14 +926,13 @@ export default class IABookActions extends LitElement {
 
     await this.autoLoanRenewChecker(false);
 
-    // show warning modal with remaining time to auto returned it.
-    // once the patron has dismissed it, don't re-show it on every subsequent
-    // tick — only an actual renewal (see handleLoanAutoRenewed) re-arms it.
-    if (this.loanRenewResult.renewNow === false && !this.warningModalDismissed) {
-      /**
-       * so compensate for the 50 second buffer to handle above race conditions
-       * let's reduce 1 min from warning texts and early return the book when 1 min left.
-       */
+    // Once dismissed, don't re-show the warning on every subsequent tick —
+    // only an actual renewal (handleLoanAutoRenewed) re-arms it.
+    if (
+      this.loanRenewResult.renewNow === false &&
+      !this.warningModalDismissed
+    ) {
+      // Compensate for the 50s buffer above by warning a minute early.
       loanSecondsLeft -= 60;
       this.loanRenewResult.secondsLeft = loanSecondsLeft;
 
@@ -916,9 +942,10 @@ export default class IABookActions extends LitElement {
 
   /**
    * enable access of borrowed/browsed books
+   * @param {boolean} [skipInitialCall] - see LoanTokenPoller's constructor doc
    * @see LoanTokenPoller
    */
-  startLoanTokenPoller() {
+  startLoanTokenPoller(skipInitialCall = false) {
     const successCallback = () => {
       if (!this.postInitComplete) {
         this.lendingBarPostInit();
@@ -929,24 +956,17 @@ export default class IABookActions extends LitElement {
       this.handleLendingActionError(eventObj);
     };
 
-    /**
-     * LoanTokenPoller is a class that polls the loan token
-     * it takes 5 params
-     * 1. this.identifier
-     * 2. this.borrowType
-     * 3. successCallback - it used to
-     *    - disptach lendingFlow::PostInit event
-     *    - initialize bookreader using br.init()
-     * 4. errorCallback
-     * 5. tokenPollerDelay
-     */
-    this.tokenPoller = new LoanTokenPoller(
-      this.identifier,
-      this.borrowType,
+    // Tear down any previous poller first, so only one is ever controlling
+    // window.IALendingIntervals.tokenPoller at a time.
+    this.tokenPoller?.disconnectedCallback();
+    this.tokenPoller = new LoanTokenPoller({
+      identifier: this.identifier,
+      borrowType: this.borrowType,
       successCallback,
       errorCallback,
-      this.tokenDelay // in seconds
-    );
+      pollerDelay: this.tokenDelay, // in seconds
+      skipInitialCall,
+    });
   }
 
   /*
@@ -959,45 +979,63 @@ export default class IABookActions extends LitElement {
   }
 
   /**
-   * handle lending errors occure during different operation like
-   * browse book, borrow book, borrowed book token etc...
-   *
+   * Handles lending errors from any action (browse_book, borrow_book,
+   * create_token, renew_loan, etc).
    * @event IABookActions#lendingActionError
-   * @param {Object} event - The employee who is responsible for the project
-   *  @param {string} event.detail.action - action when error occurred like 'browseBook', 'borrowBook'
-   *  @param {string} event.detail.data.error - error message
+   * @param {Object} event
+   * @param {string} event.detail.action
+   * @param {string} event.detail.data.error
    */
   handleLendingActionError(event) {
     this.disableActionGroup = false;
 
     const action = event?.detail?.action;
-    const errorMsg = event?.detail?.data?.error;
+    // handleLoanRenewNow's failure path sets `.error` to a boolean flag and
+    // puts the real text in `.message` — only take `.error` when it's
+    // actually a string, or the modal renders the literal word "true".
+    const rawErrorMsg = event?.detail?.data?.error;
+    const errorMsg =
+      typeof rawErrorMsg === 'string' ? rawErrorMsg : undefined;
+    const isInitial = event?.detail?.isInitial === true;
+
+    log('[IABookActions] handleLendingActionError', {
+      identifier: this.identifier,
+      action,
+      errorMsg,
+      isInitial,
+      loanRenewInProgress: this.loanRenewInProgress,
+      recoveringFromLoanExpiry: this.recoveringFromLoanExpiry,
+    });
 
     if (action === 'create_token') {
-      // 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.
+      // Any create_token failure — initial or a routine interval refresh —
+      // means access can no longer be confirmed (e.g. a stale loan-record
+      // cache on some other node can make this request fail even though
+      // the loan is fine, or the loan may genuinely have just been
+      // returned via BookReaderImages.php's revokeAccess()). Don't retry
+      // and don't stay silent either way: reset the bar to Borrow and the
+      // timer to 0 rather than leaving a stale countdown for a session
+      // that isn't accessible.
+      window?.IALendingIntervals?.clearAll();
+      this.tokenPoller?.disconnectedCallback();
       this.lendingStatus = {
         ...this.lendingStatus,
         user_has_browsed: false,
         available_to_browse: true,
+        secondsLeftOnLoan: 0,
       };
+
+      // showErrorModal has dedicated create_token messaging (refresh
+      // button + support email) and shows regardless of whether a
+      // specific error string came back.
+      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.
+      // The loan was NOT renewed — reflect that immediately (show Borrow,
+      // clear the stale timer) rather than leaving a frozen "Return now".
       this.lendingStatus = {
         ...this.lendingStatus,
         user_has_browsed: false,
@@ -1005,11 +1043,8 @@ export default class IABookActions extends LitElement {
         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).
+      // Refresh the page on dismissal so the client picks up whatever the
+      // server now authoritatively considers true (any error message).
       this.showLoanUnavailableModal(errorMsg);
     } else {
       // Every other action failure genuinely affects loan state.
@@ -1022,9 +1057,15 @@ export default class IABookActions extends LitElement {
       // 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 };
+          this.lendingStatus = {
+            ...this.lendingStatus,
+            available_to_browse: false,
+          };
         } else if (action === 'borrow_book') {
-          this.lendingStatus = { ...this.lendingStatus, available_to_borrow: false };
+          this.lendingStatus = {
+            ...this.lendingStatus,
+            available_to_borrow: false,
+          };
         }
       }
     }
@@ -1055,7 +1096,7 @@ export default class IABookActions extends LitElement {
             .identifier}"
           >info@archive.org</a
         ><br /><br />
-        <code>errorLog: ${errorMsg}</code>`;
+        ${errorMsg ? html`<code>errorLog: ${errorMsg}</code>` : nothing}`;
     }
 
     await this.modal?.showModal({
@@ -1109,6 +1150,10 @@ export default class IABookActions extends LitElement {
         justify-content: center;
         flex-wrap: wrap;
       }
+
+      #action-bar-modal {
+        --modalWidth: 36rem;
+      }
     `;
   }
 }