@papyrus-sdk/ui-react-native 0.2.24 → 0.2.27

package/runtime/runtime.js

@@ -139,8 +139,18 @@
   const COMIC_PREVIEW_CACHE_LIMIT = 8;
   const comicHelpers = window.PapyrusComicRuntime || {};
   const runtimeConfig = window.__PAPYRUS_RUNTIME_CONFIG__ || {};
+  const epubDiagnosticsEnabled =
+    runtimeConfig.epubDiagnostics === true ||
+    runtimeConfig.epubDiagnostics === 'true';
+  const EPUB_STAGE_TIMEOUT_MS = 10000;
   let comicDispose = null;
   let comicGeneration = 0;
+  let epubInteractionCleanup = null;
+  const epubSelectionCleanups = new Set();
+  let epubScrollDiagnostics = null;
+  // Shared generation for all document formats. The historical variable name
+  // is kept because the shipped runtime tests and diagnostics refer to it.
+  let epubLoadGeneration = 0;
 
   const sendMessage = (payload) => {
     if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
@@ -246,6 +256,223 @@
     sendMessage({ type: 'event', name, payload });
   };
 
+  const sendEpubDiagnostic = (name, payload) => {
+    if (!epubDiagnosticsEnabled) return;
+    sendEvent(name, {
+      loadId: payload.loadId,
+      timestamp: Date.now(),
+      sourceKind: payload.sourceKind,
+      byteLength: payload.byteLength,
+      currentType: currentType,
+      durationMs: payload.durationMs,
+      uri: payload.uri,
+      status: payload.status,
+      contentLength: payload.contentLength,
+      contentType: payload.contentType,
+      transferEncoding: payload.transferEncoding,
+      error: payload.error,
+    });
+  };
+
+  const withEpubStageTimeout = (promise, stage, payload) =>
+    new Promise((resolve, reject) => {
+      let settled = false;
+      const startedAt = performance.now();
+      const timeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        const error = new Error(`EPUB ${stage} excedeu ${EPUB_STAGE_TIMEOUT_MS}ms`);
+        sendEpubDiagnostic('epub.load.timeout', {
+          ...payload,
+          error: { message: error.message, stage },
+          durationMs: performance.now() - startedAt,
+        });
+        reject(error);
+      }, EPUB_STAGE_TIMEOUT_MS);
+
+      Promise.resolve(promise).then(
+        (value) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          resolve(value);
+        },
+        (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          reject(error);
+        },
+      );
+    });
+
+  const isEpubDiagnosticsEnabled = () => {
+    const configured = runtimeConfig.epubScrollDiagnostics;
+    return configured === true || configured === '1' || configured === 'true' ||
+      Boolean(window.__PAPYRUS_EPUB_SCROLL_DIAGNOSTICS__);
+  };
+
+  const createEpubScrollDiagnostics = (manager) => {
+    if (!isEpubDiagnosticsEnabled()) return null;
+
+    const state = {
+      lastScrollTop: null,
+      lastTouchY: null,
+      lastTouchX: null,
+      lastInputDeltaY: 0,
+      touchActive: false,
+      selectionActive: false,
+      gestureLock: false,
+      consecutiveStallSamples: 0,
+      firstStallTimestamp: null,
+      stallReported: false,
+    };
+    const container = manager && manager.container;
+
+    const getSnapshot = () => {
+      const scrollTop = Number(container && container.scrollTop) || 0;
+      const scrollHeight = Number(container && container.scrollHeight) || 0;
+      const clientHeight = Number(container && container.clientHeight) || 0;
+      let scrollEnabled = true;
+      try {
+        const overflowY = window.getComputedStyle(container).overflowY;
+        scrollEnabled = overflowY !== 'hidden' && overflowY !== 'clip';
+      } catch (_) {}
+      return { scrollTop, scrollHeight, clientHeight, scrollEnabled };
+    };
+
+    const emit = (name, payload) => {
+      sendEvent(name, {
+        timestamp: Date.now(),
+        documentType: currentType,
+        currentPage,
+        spineIndex: Math.max(0, currentPage - 1),
+        progress: pageCount > 0 ? currentPage / pageCount : null,
+        ...(payload || {}),
+      });
+    };
+
+    const resetStall = () => {
+      state.consecutiveStallSamples = 0;
+      state.firstStallTimestamp = null;
+      state.stallReported = false;
+    };
+
+    const recordScroll = (event) => {
+      const snapshot = getSnapshot();
+      const previousScrollTop = state.lastScrollTop === null
+        ? snapshot.scrollTop
+        : state.lastScrollTop;
+      const deltaY = state.lastInputDeltaY;
+      const inputDirection = deltaY > 4 ? 'up' : deltaY < -4 ? 'down' : 'none';
+      const offsetUnchanged = Math.abs(snapshot.scrollTop - previousScrollTop) <= 1;
+      const validStallSample = inputDirection === 'up' &&
+        snapshot.scrollTop > 2 &&
+        snapshot.scrollEnabled &&
+        !state.selectionActive &&
+        !state.gestureLock &&
+        offsetUnchanged;
+
+      if (validStallSample) {
+        state.consecutiveStallSamples += 1;
+        if (state.firstStallTimestamp === null) {
+          state.firstStallTimestamp = Date.now();
+        }
+        const durationMs = Date.now() - state.firstStallTimestamp;
+        if (!state.stallReported && state.consecutiveStallSamples >= 3 && durationMs >= 150) {
+          state.stallReported = true;
+          emit('epub.scroll.stall', {
+            ...snapshot,
+            previousScrollTop,
+            deltaY,
+            direction: 'up',
+            consecutiveSamples: state.consecutiveStallSamples,
+            durationMs,
+            selectionActive: state.selectionActive,
+            gestureLock: state.gestureLock,
+          });
+        }
+      } else if (!offsetUnchanged || inputDirection !== 'up') {
+        resetStall();
+      }
+
+      state.lastScrollTop = snapshot.scrollTop;
+      emit('epub.scroll', {
+        ...snapshot,
+        previousScrollTop,
+        deltaY,
+        direction: snapshot.scrollTop < previousScrollTop ? 'up' :
+          snapshot.scrollTop > previousScrollTop ? 'down' : 'none',
+        touchActive: state.touchActive,
+        selectionActive: state.selectionActive,
+        gestureLock: state.gestureLock,
+      });
+    };
+
+    return {
+      setSelectionActive(active) {
+        state.selectionActive = Boolean(active);
+        emit('epub.selection', { selectionActive: state.selectionActive });
+      },
+      setGestureLock(active) {
+        state.gestureLock = Boolean(active);
+        emit('epub.gesture-lock', { gestureLock: state.gestureLock });
+      },
+      touchStart(event) {
+        const touch = event && event.touches && event.touches[0];
+        state.touchActive = true;
+        state.lastTouchY = touch ? Number(touch.clientY) : null;
+        state.lastTouchX = touch ? Number(touch.clientX) : null;
+        state.lastInputDeltaY = 0;
+        resetStall();
+        emit('epub.touch.start', { x: state.lastTouchX, y: state.lastTouchY });
+      },
+      touchMove(event) {
+        const touch = event && event.touches && event.touches[0];
+        if (!touch) return;
+        const previousY = state.lastTouchY;
+        const previousX = state.lastTouchX;
+        state.lastTouchY = Number(touch.clientY);
+        state.lastTouchX = Number(touch.clientX);
+        state.lastInputDeltaY = previousY === null ? 0 : previousY - state.lastTouchY;
+        emit('epub.touch.move', {
+          x: state.lastTouchX,
+          y: state.lastTouchY,
+          deltaY: previousY === null ? 0 : previousY - state.lastTouchY,
+          deltaX: previousX === null ? 0 : previousX - state.lastTouchX,
+        });
+        recordScroll();
+      },
+      touchEnd(event) {
+        const touch = event && event.changedTouches && event.changedTouches[0];
+        state.touchActive = false;
+        emit('epub.touch.end', {
+          x: touch ? Number(touch.clientX) : state.lastTouchX,
+          y: touch ? Number(touch.clientY) : state.lastTouchY,
+        });
+        state.lastTouchY = null;
+        state.lastTouchX = null;
+        state.lastInputDeltaY = 0;
+        resetStall();
+      },
+      scroll: recordScroll,
+      relocated(location) {
+        emit('epub.relocated', {
+          href: location && location.start ? location.start.href || null : null,
+          cfi: location && location.start ? location.start.cfi || null : null,
+        });
+      },
+      settled(event) {
+        emit('epub.momentum.settled', {
+          scrollTop: Number(event && event.top) || 0,
+        });
+      },
+      command(name, payload) {
+        emit('epub.programmatic-scroll', { command: name, ...(payload || {}) });
+      },
+    };
+  };
+
   const reportError = (error, context) => {
     const message = error && error.message ? error.message : String(error);
     const stack = error && error.stack ? error.stack : null;
@@ -296,42 +523,98 @@
   };
 
   const clearViewer = () => {
+    if (epubInteractionCleanup) {
+      epubInteractionCleanup();
+      epubInteractionCleanup = null;
+    }
+    epubSelectionCleanups.forEach((cleanup) => cleanup());
+    epubSelectionCleanups.clear();
     clearComicState();
     while (viewer.firstChild) {
       viewer.removeChild(viewer.firstChild);
     }
   };
 
-  const decodeBase64 = (value) => {
-    const clean = value.replace(/\s/g, '');
-    const binary = atob(clean);
-    const len = binary.length;
-    const bytes = new Uint8Array(len);
+   const decodeBase64 = (value) => {
+     const clean = value.replace(/\s/g, '');
+     const binary = atob(clean);
+     const len = binary.length;
+     const bytes = new Uint8Array(len);
     for (let i = 0; i < len; i += 1) {
       bytes[i] = binary.charCodeAt(i);
     }
-    return bytes;
-  };
+     return bytes;
+   };
+
+   const toExactArrayBuffer = (bytes) => {
+     if (
+       bytes.byteOffset === 0 &&
+       bytes.byteLength === bytes.buffer.byteLength
+     ) {
+       return bytes.buffer;
+     }
+     return bytes.buffer.slice(
+       bytes.byteOffset,
+       bytes.byteOffset + bytes.byteLength
+     );
+   };
 
   const decodeBase64ToText = (value) => {
     const bytes = decodeBase64(value);
     return new TextDecoder('utf-8').decode(bytes);
   };
 
+  const isMetroAssetUri = (value) => {
+    try {
+      const url = new URL(value);
+      return (
+        (url.protocol === 'http:' || url.protocol === 'https:') &&
+        url.pathname.startsWith('/assets/') &&
+        url.searchParams.has('platform') &&
+        url.searchParams.has('hash')
+      );
+    } catch {
+      return false;
+    }
+  };
+
   const sourceToArrayBuffer = async (source) => {
     if (source.kind === 'uri') {
-      if (/^(?:file|content):\/\//i.test(source.uri)) {
+      if (/^(?:file|content|android\.resource):\/\//i.test(source.uri)) {
         return readLocalFile(source.uri);
       }
+      const isEpubHttpSource = isMetroAssetUri(source.uri);
+      if (isEpubHttpSource) {
+        sendEpubDiagnostic('epub.source.fetch.start', {uri: source.uri});
+      }
       const response = await fetch(source.uri);
+      if (isEpubHttpSource) {
+        sendEpubDiagnostic('epub.source.fetch.response', {
+          uri: source.uri,
+          status: response.status,
+          contentLength: response.headers.get('content-length'),
+          contentType: response.headers.get('content-type'),
+          transferEncoding: response.headers.get('transfer-encoding'),
+        });
+      }
       if (!response.ok && response.status !== 0) {
         throw new Error(`Falha ao carregar quadrinho (${response.status})`);
       }
-      return response.arrayBuffer();
-    }
-    if (source.kind === 'base64') {
-      return decodeBase64(source.data).buffer;
-    }
+      if (isEpubHttpSource) {
+        sendEpubDiagnostic('epub.source.body.start', {uri: source.uri});
+      }
+      const body = await response.arrayBuffer();
+      if (isEpubHttpSource) {
+        sendEpubDiagnostic('epub.source.body.end', {
+          uri: source.uri,
+          byteLength: body.byteLength,
+        });
+      }
+      return body;
+     }
+     if (source.kind === 'base64') {
+       return toExactArrayBuffer(decodeBase64(source.data));
+     }
     throw new Error('Fonte de quadrinho inválida.');
   };
 
@@ -809,7 +1092,7 @@
     return pages.length > 0 ? pages : [''];
   };
 
-  const loadText = async (source) => {
+  const loadText = async (source, isCurrentLoad = () => true) => {
     let text = '';
     if (source.kind === 'uri') {
       const res = await fetch(source.uri);
@@ -820,6 +1103,9 @@
       text = source.text || '';
     }
 
+    if (!isCurrentLoad()) {
+      throw new Error('Document load superseded by a newer load');
+    }
     clearViewer();
     textPages = paginateText(text);
     pageCount = textPages.length;
@@ -829,7 +1115,18 @@
     return { pageCount };
   };
 
-  const loadEpub = async (source) => {
+  const loadEpub = async (source, loadId, generation) => {
+    const diagnosticPayload = {
+      loadId,
+      sourceKind: source.kind,
+    };
+    const isCurrentLoad = () => generation === epubLoadGeneration;
+    sendEpubDiagnostic('epub.load.start', diagnosticPayload);
+
+    if (epubInteractionCleanup) {
+      epubInteractionCleanup();
+      epubInteractionCleanup = null;
+    }
     if (rendition && typeof rendition.destroy === 'function') {
       rendition.destroy();
     }
@@ -839,28 +1136,56 @@
 
     let data = null;
     if (source.kind === 'uri') {
-      data = source.uri;
+      data = await withEpubStageTimeout(
+        sourceToArrayBuffer(source),
+        'source',
+        diagnosticPayload,
+      );
     } else if (source.kind === 'base64') {
-      data = decodeBase64(source.data);
+      // epub.js expects an ArrayBuffer for binary books. Passing the decoded
+      // Uint8Array directly can leave `book.ready` pending in Android WebView.
+      data = toExactArrayBuffer(decodeBase64(source.data));
     } else if (source.kind === 'text') {
       const encoder = new TextEncoder();
       data = encoder.encode(source.text || '').buffer;
     }
 
+    if (!isCurrentLoad()) throw new Error('EPUB load superseded by a newer load');
+    sendEpubDiagnostic('epub.source.received', {
+      ...diagnosticPayload,
+      byteLength: data?.byteLength,
+    });
+    sendEpubDiagnostic('epub.source.decoded', {
+      ...diagnosticPayload,
+      byteLength: data?.byteLength,
+    });
     book = ePub(data);
-    await book.ready;
+    sendEpubDiagnostic('epub.book.created', {
+      ...diagnosticPayload,
+      byteLength: data?.byteLength,
+    });
+    sendEpubDiagnostic('epub.book.ready.start', diagnosticPayload);
+    await withEpubStageTimeout(book.ready, 'book.ready', diagnosticPayload);
+    if (!isCurrentLoad()) throw new Error('EPUB load superseded by a newer load');
+    sendEpubDiagnostic('epub.book.ready.end', diagnosticPayload);
 
     spineItems = book.spine && book.spine.items ? book.spine.items : [];
     pageCount = spineItems.length;
     currentPage = 1;
+    sendEpubDiagnostic('epub.spine.ready', {
+      ...diagnosticPayload,
+      pageCount,
+    });
 
     clearViewer();
     rendition = book.renderTo(viewer, {
+      manager: 'continuous',
       width: '100%',
       height: '100%',
-      flow: 'paginated',
+      flow: 'scrolled-continuous',
       spread: 'none',
     });
+    sendEpubDiagnostic('epub.rendition.created', diagnosticPayload);
 
     if (rendition && rendition.hooks && rendition.hooks.content) {
       rendition.hooks.content.register((contents) => {
@@ -868,6 +1193,41 @@
         if (frame) {
           frame.setAttribute('sandbox', 'allow-scripts allow-same-origin');
         }
+        const selectionDocument = contents && contents.document;
+        const selectionWindow = contents && contents.window;
+        if (
+          selectionDocument &&
+          typeof selectionDocument.addEventListener === 'function' &&
+          selectionWindow &&
+          typeof selectionWindow.getSelection === 'function'
+        ) {
+          const handleSelectionChange = () => {
+            const selection = selectionWindow.getSelection();
+            const text = selection ? selection.toString().trim() : '';
+            epubScrollDiagnostics && epubScrollDiagnostics.setSelectionActive(Boolean(text));
+          };
+          selectionDocument.addEventListener('selectionchange', handleSelectionChange);
+          const selectionCleanup = () => {
+            selectionDocument.removeEventListener('selectionchange', handleSelectionChange);
+            epubSelectionCleanups.delete(selectionCleanup);
+          };
+          epubSelectionCleanups.add(selectionCleanup);
+          if (contents && typeof contents === 'object') {
+            contents.__papyrusSelectionCleanup = selectionCleanup;
+          }
+        }
+      });
+    }
+
+    if (
+      rendition &&
+      rendition.hooks &&
+      rendition.hooks.unloaded &&
+      typeof rendition.hooks.unloaded.register === 'function'
+    ) {
+      rendition.hooks.unloaded.register((view) => {
+        const cleanup = view && view.contents && view.contents.__papyrusSelectionCleanup;
+        if (typeof cleanup === 'function') cleanup();
       });
     }
 
@@ -875,6 +1235,7 @@
       rendition.on('selected', (cfiRange, contents) => {
         const selection = contents && contents.window ? contents.window.getSelection() : null;
         const text = selection ? selection.toString().trim() : '';
+        epubScrollDiagnostics && epubScrollDiagnostics.setSelectionActive(Boolean(text));
         if (text) {
           sendEvent('TEXT_SELECTED', { text, pageIndex: Math.max(0, currentPage - 1) });
         }
@@ -882,12 +1243,177 @@
           rendition.annotations.remove(cfiRange, 'highlight');
         }
       });
+      rendition.on('relocated', (location) => {
+        const start = location && location.start;
+        let index = start && Number.isInteger(start.index) ? start.index : -1;
+        if (index < 0 && start && start.href) index = getSpineIndexByHref(start.href);
+        if (index < 0 || index >= spineItems.length) return;
+        epubScrollDiagnostics && epubScrollDiagnostics.relocated(location);
+        const nextPage = index + 1;
+        if (nextPage === currentPage) return;
+        currentPage = nextPage;
+        sendState();
+      });
     }
 
-    await displayEpubPage(0);
+    sendEpubDiagnostic('epub.display.start', diagnosticPayload);
+    await withEpubStageTimeout(
+      displayEpubPage(0),
+      'rendition.display',
+      diagnosticPayload,
+    );
+    if (!isCurrentLoad()) throw new Error('EPUB load superseded by a newer load');
+    sendEpubDiagnostic('epub.display.end', diagnosticPayload);
+    if (
+      rendition &&
+      rendition.manager &&
+      typeof rendition.manager.on === 'function' &&
+      typeof rendition.on === 'function'
+    ) {
+      let touchStart = null;
+      let lastScrollOffset = -1;
+      const manager = rendition.manager;
+      epubScrollDiagnostics = createEpubScrollDiagnostics(manager);
+
+      // ContinuousManager schedules checks through its serial queue. Observe
+      // the queue itself so diagnostics can distinguish queued work from the
+      // check currently being executed without changing epub.js semantics.
+      const originalCheck = typeof manager.check === 'function' ? manager.check : null;
+      const queue = manager.q;
+      const originalEnqueue = queue && typeof queue.enqueue === 'function'
+        ? queue.enqueue
+        : null;
+      let checkRequestId = 0;
+      if (originalCheck) {
+        manager.check = function (...args) {
+          const requestId = ++checkRequestId;
+          const checkContext = this;
+          if (epubScrollDiagnostics) {
+            epubScrollDiagnostics.command('manager.check.request', {
+              requestId,
+              queueLength: manager.q && typeof manager.q.length === 'function'
+                ? manager.q.length()
+                : null,
+            });
+          }
+          epubScrollDiagnostics && epubScrollDiagnostics.command('manager.check.start', {
+            requestId,
+            queueLength: queue && typeof queue.length === 'function'
+              ? queue.length()
+              : null,
+          });
+          let result;
+          try {
+            result = originalCheck.apply(checkContext, args);
+          } catch (error) {
+            epubScrollDiagnostics && epubScrollDiagnostics.command('manager.check.end', {
+              requestId,
+              status: 'error',
+              message: error && error.message ? error.message : String(error),
+            });
+            throw error;
+          }
+          return Promise.resolve(result)
+            .then(
+              (result) => {
+                epubScrollDiagnostics && epubScrollDiagnostics.command('manager.check.end', {
+                  requestId,
+                  status: 'ready',
+                });
+                return result;
+              },
+              (error) => {
+                epubScrollDiagnostics && epubScrollDiagnostics.command('manager.check.end', {
+                  requestId,
+                  status: 'error',
+                  message: error && error.message ? error.message : String(error),
+                });
+                throw error;
+              },
+            );
+        };
+      }
+      if (originalEnqueue) {
+        queue.enqueue = function (...args) {
+          const queueLengthBefore = typeof queue.length === 'function' ? queue.length() : null;
+          const result = originalEnqueue.apply(this, args);
+          epubScrollDiagnostics && epubScrollDiagnostics.command('manager.queue.enqueue', {
+            queueLengthBefore,
+            queueLengthAfter: typeof queue.length === 'function' ? queue.length() : null,
+            running: Boolean(queue.running),
+          });
+          return result;
+        };
+      }
+      const getTouchPoint = (event) => {
+        const touch =
+          (event && event.changedTouches && event.changedTouches[0]) ||
+          (event && event.touches && event.touches[0]);
+        if (!touch) return null;
+        const x = Number(touch.screenX ?? touch.clientX);
+        const y = Number(touch.screenY ?? touch.clientY);
+        return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
+      };
+      const handleScroll = (event) => {
+        const offsetY = Math.max(0, Number(event && event.top) || 0);
+        epubScrollDiagnostics && epubScrollDiagnostics.scroll(event);
+        if (Math.abs(offsetY - lastScrollOffset) < 1) return;
+        lastScrollOffset = offsetY;
+        sendEvent('VIEWER_SCROLL', { offsetY });
+      };
+      const handleTouchStart = (event) => {
+        touchStart = getTouchPoint(event);
+        epubScrollDiagnostics && epubScrollDiagnostics.touchStart(event);
+      };
+      const handleTouchMove = (event) => {
+        epubScrollDiagnostics && epubScrollDiagnostics.touchMove(event);
+      };
+      const handleTouchEnd = (event) => {
+        const end = getTouchPoint(event);
+        const start = touchStart;
+        touchStart = null;
+        if (start && end && Math.hypot(end.x - start.x, end.y - start.y) <= 12) {
+          sendEvent('VIEWER_TAP', {});
+        }
+        epubScrollDiagnostics && epubScrollDiagnostics.touchEnd(event);
+      };
+
+      manager.on('scroll', handleScroll);
+      const handleScrolled = (event) => {
+        epubScrollDiagnostics && epubScrollDiagnostics.settled(event);
+      };
+      manager.on('scrolled', handleScrolled);
+      rendition.on('touchstart', handleTouchStart);
+      rendition.on('touchmove', handleTouchMove);
+      rendition.on('touchend', handleTouchEnd);
+      epubInteractionCleanup = () => {
+        epubSelectionCleanups.forEach((cleanup) => cleanup());
+        epubSelectionCleanups.clear();
+        epubScrollDiagnostics && epubScrollDiagnostics.setSelectionActive(false);
+        if (originalCheck) manager.check = originalCheck;
+        if (originalEnqueue) queue.enqueue = originalEnqueue;
+        if (typeof manager.off === 'function') manager.off('scroll', handleScroll);
+        if (typeof manager.off === 'function') manager.off('scrolled', handleScrolled);
+        if (typeof rendition.off === 'function') {
+          rendition.off('touchstart', handleTouchStart);
+          rendition.off('touchmove', handleTouchMove);
+          rendition.off('touchend', handleTouchEnd);
+        }
+        epubScrollDiagnostics = null;
+      };
+    }
     applyEpubZoom();
 
-    const outline = await buildOutline();
+    const outline = await withEpubStageTimeout(
+      buildOutline(),
+      'outline',
+      diagnosticPayload,
+    );
+    if (!isCurrentLoad()) throw new Error('EPUB load superseded by a newer load');
+    sendEpubDiagnostic('epub.load.ready', {
+      ...diagnosticPayload,
+      pageCount,
+    });
     return { pageCount, outline };
   };
 
@@ -896,6 +1422,10 @@
     const item = spineItems[pageIndex];
     if (!item) return;
     const target = item.href || item.idref || item.cfiBase || pageIndex;
+    epubScrollDiagnostics && epubScrollDiagnostics.command('display', {
+      target,
+      pageIndex,
+    });
     await rendition.display(target);
     currentPage = pageIndex + 1;
     sendState();
@@ -1004,18 +1534,33 @@
 
     try {
       if (kind === 'load') {
+        const generation = (epubLoadGeneration += 1);
         currentType = payload.type;
         zoom = 1.0;
 
         if (currentType === 'text') {
-          const result = await loadText(payload.source);
+          const result = await loadText(
+            payload.source,
+            () => generation === epubLoadGeneration,
+          );
+          if (generation !== epubLoadGeneration) {
+            throw new Error('Document load superseded by a newer load');
+          }
+          sendEvent('document.ready', {
+            loadId: id,
+            pageCount: result.pageCount,
+          });
           sendState();
           sendResponse(id, true, result);
           return;
         }
 
         if (currentType === 'epub') {
-          const result = await loadEpub(payload.source);
+          const result = await loadEpub(payload.source, id, generation);
+          sendEvent('document.ready', {
+            loadId: id,
+            pageCount: result.pageCount,
+          });
           sendState({ outline: result.outline || [] });
           sendResponse(id, true, result);
           return;
@@ -1132,7 +1677,28 @@
 
       sendResponse(id, false, null, 'Unknown command');
     } catch (err) {
-      sendResponse(id, false, null, err && err.message ? err.message : String(err));
+      const errorMessage = err && err.message ? err.message : String(err);
+      const isSuperseded = /superseded by a newer load/i.test(errorMessage);
+      if (kind === 'load' && isSuperseded) {
+        sendEvent('document.stale', { loadId: id, error: errorMessage });
+      } else if (kind === 'load') {
+        sendEvent('document.error', {
+          loadId: id,
+          error: { message: errorMessage, stack: err?.stack || null },
+        });
+      }
+      if (kind === 'load' && payload?.type === 'epub') {
+        sendEpubDiagnostic('epub.load.error', {
+          loadId: id,
+          sourceKind: payload.source?.kind,
+          error: { message: errorMessage, stack: err?.stack || null },
+        });
+        sendEvent('document.error', {
+          loadId: id,
+          error: { message: errorMessage, stack: err?.stack || null },
+        });
+      }
+      sendResponse(id, false, null, errorMessage);
     }
   };