@prose-reader/core 1.15.0 → 1.17.0

package/dist/prose.umd.cjs

@@ -2127,7 +2127,15 @@
     });
     const reader = next(options);
     const getStyle = () => `
-    ${``}
+    ${/*
+          Ideally, we would like to use !important but it could break publisher specific
+          cases.
+          Also right now we do not apply it to * since it would also break publisher
+          more specific scaling down the tree.
+    
+          body *:not([class^="mjx-"]) {
+        */
+    ``}
     body {
       ${settingsSubject$.value.fontScale !== 1 ? `font-size: ${settingsSubject$.value.fontScale}em !important;` : ``}
       ${settingsSubject$.value.lineHeight !== `publisher` ? `line-height: ${settingsSubject$.value.lineHeight} !important;` : ``}
@@ -2169,6 +2177,9 @@
     );
     return {
       ...reader,
+      /**
+       * Absorb current enhancer settings and passthrough the rest to reader
+       */
       setSettings: (settings) => {
         const {
           fontJustification: fontJustification2 = settingsSubject$.value.fontJustification,
@@ -2182,6 +2193,9 @@
         }
         reader.setSettings(passthroughSettings);
       },
+      /**
+       * Combine reader settings with enhancer settings
+       */
       settings$
     };
   };
@@ -2449,6 +2463,7 @@
     };
   };
   const createReport = (namespace) => ({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     log: (...data) => {
       if (window.__PROSE_READER_DEBUG) {
         if (namespace)
@@ -2457,6 +2472,7 @@
           console.log(wrap(ROOT_NAMESPACE), ...data);
       }
     },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     warn: (...data) => {
       if (window.__PROSE_READER_DEBUG) {
         if (namespace)
@@ -2465,9 +2481,22 @@
           console.warn(wrap(ROOT_NAMESPACE), ...data);
       }
     },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     error: (...data) => {
       console.error(...data);
     },
+    // time: (label?: string | undefined) => {
+    //   if (window.__PROSE_READER_DEBUG) {
+    //     // eslint-disable-next-line no-console
+    //     console.time(`[prose-reader] [metric] ${label}`);
+    //   }
+    // },
+    // timeEnd: (label?: string | undefined) => {
+    //   if (window.__PROSE_READER_DEBUG) {
+    //     // eslint-disable-next-line no-console
+    //     console.timeEnd(`[prose-reader] [metric] ${label}`);
+    //   }
+    // },
     time,
     logMetric: (performanceEntry, targetDuration = 0) => {
       if (window.__PROSE_READER_DEBUG) {
@@ -2481,6 +2510,7 @@
         }
       }
     },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     measurePerformance: (name, targetDuration = 10, functionToMeasure, { disable } = {}) => {
       if (disable || !window.__PROSE_READER_DEBUG)
         return functionToMeasure;
@@ -2675,15 +2705,37 @@
         beginPageIndexInChapter: paginationInfo.beginPageIndex,
         beginNumberOfPagesInChapter: paginationInfo.beginNumberOfPages,
         beginChapterInfo: beginItem ? chaptersInfo[beginItem.item.id] : void 0,
+        // chapterIndex: number;
+        // pages: number;
+        // pageIndexInBook: number;
+        // pageIndexInChapter: number;
+        // pagesOfChapter: number;
+        // pagePercentageInChapter: number;
+        // offsetPercentageInChapter: number;
+        // domIndex: number;
+        // charOffset: number;
+        // serializeString?: string;
         beginSpineItemIndex: paginationInfo.beginSpineItemIndex,
+        // spineItemPath: beginItem?.item.path,
+        // spineItemId: beginItem?.item.id,
         beginCfi: paginationInfo.beginCfi,
         beginSpineItemReadingDirection: beginItem == null ? void 0 : beginItem.getReadingDirection(),
         endChapterInfo: endItem ? chaptersInfo[endItem.item.id] : void 0,
         endPageIndexInChapter: paginationInfo.endPageIndex,
         endNumberOfPagesInChapter: paginationInfo.endNumberOfPages,
         endSpineItemIndex: paginationInfo.endSpineItemIndex,
+        // spineItemPath: endItem?.item.path,
+        // spineItemId: endItem?.item.id,
         endSpineItemReadingDirection: endItem == null ? void 0 : endItem.getReadingDirection(),
         endCfi: paginationInfo.endCfi,
+        // end: ReadingLocation;
+        // spineItemReadingDirection: focusedSpineItem?.getReadingDirection(),
+        /**
+         * This percentage is based of the weight (kb) of every items and the number of pages.
+         * It is not accurate but gives a general good idea of the overall progress.
+         * It is recommended to use this progress only for reflow books. For pre-paginated books
+         * the number of pages and current index can be used instead since 1 page = 1 chapter.
+         */
         percentageEstimateOfBook: endItem ? reader.progression.getPercentageEstimate(
           context,
           paginationInfo.endSpineItemIndex ?? 0,
@@ -2693,6 +2745,11 @@
           endItem
         ) : 0,
         isUsingSpread: context.shouldDisplaySpread()
+        // chaptersOfBook: number;
+        // chapter: string;
+        // hasNextChapter: (reader.spine.spineItemIndex || 0) < (manifest.readingOrder.length - 1),
+        // hasPreviousChapter: (reader.spine.spineItemIndex || 0) < (manifest.readingOrder.length - 1),
+        // numberOfSpineItems: context.getManifest()?.readingOrder.length,
       };
     };
     const getSpineItemNumberOfPages = (spineItem) => {
@@ -2732,6 +2789,9 @@
         const numberOfPagesPerItems = getNumberOfPagesPerItems();
         return {
           numberOfPagesPerItems,
+          /**
+           * This may be not accurate for reflowable due to dynamic load / unload.
+           */
           numberOfTotalPages: numberOfPagesPerItems.reduce((acc, numberOfPagesForItem) => acc + numberOfPagesForItem, 0)
         };
       }),
@@ -2822,7 +2882,11 @@
       }
       ${(foundTheme == null ? void 0 : foundTheme.foregroundColor) ? `
           body * {
-            ${``}
+            ${/*
+        Ideally, we would like to use !important but it could break publisher specific
+        cases
+      */
+      ``}
             color: ${foundTheme.foregroundColor};
           }
         ` : ``}
@@ -3420,6 +3484,8 @@
       take(1)
     );
     const unload$ = unloadSubject$.asObservable().pipe(
+      // @todo remove iframe when viewport is free
+      // @todo use takeUntil(load$) when it's the case to cancel
       withLatestFrom(frameElementSubject$),
       filter(([_, frame]) => !!frame),
       map(([, frame]) => {
@@ -3440,13 +3506,16 @@
     const load$ = loadSubject$.asObservable().pipe(
       withLatestFrom(isLoadedSubject$),
       filter(([_, isLoaded]) => !isLoaded),
+      // let's ignore later load as long as the first one still runs
       exhaustMap(() => {
         return createFrame$().pipe(
           mergeMap((frame) => waitForViewportFree$.pipe(map(() => frame))),
           mergeMap((frame) => {
             parent.appendChild(frame);
             frameElementSubject$.next(frame);
-            if (!fetchResource && item.href.startsWith(window.location.origin) && (item.mediaType && [`application/xhtml+xml`, `application/xml`, `text/html`, `text/xml`].includes(item.mediaType) || !item.mediaType && ITEM_EXTENSION_VALID_FOR_FRAME_SRC.some((extension) => item.href.endsWith(extension)))) {
+            if (!fetchResource && item.href.startsWith(window.location.origin) && // we have an encoding and it's a valid html
+            (item.mediaType && [`application/xhtml+xml`, `application/xml`, `text/html`, `text/xml`].includes(item.mediaType) || // no encoding ? then try to detect html
+            !item.mediaType && ITEM_EXTENSION_VALID_FOR_FRAME_SRC.some((extension) => item.href.endsWith(extension)))) {
               frame == null ? void 0 : frame.setAttribute(`src`, item.href);
               return rxjs.of(frame);
             } else {
@@ -3502,6 +3571,7 @@
               })
             );
           }),
+          // we stop loading as soon as unload is requested
           takeUntil(unloadSubject$)
         );
       }),
@@ -3628,6 +3698,12 @@
       getHtmlFromResource,
       load,
       unload,
+      /**
+       * Upward layout is used when the parent wants to manipulate the iframe without triggering
+       * `layout` event. This is a particular case needed for iframe because the parent can layout following
+       * an iframe `layout` event. Because the parent `layout` may change some of iframe properties we do not
+       * want the iframe to trigger a new `layout` even and have infinite loop.
+       */
       staticLayout: (size) => {
         const frame = frameElement$.getValue();
         if (frame) {
@@ -3638,6 +3714,8 @@
           }
         }
       },
+      // @todo block access, only public API to manipulate / get information (in order to memo / optimize)
+      // manipulate() with cb and return boolean whether re-layout or not
       getManipulableFrame,
       getReadingDirection: () => {
         var _a;
@@ -3659,6 +3737,10 @@
         loaded$,
         ready$,
         isReady$: isReadySubject$.asObservable(),
+        /**
+         * This is used as upstream layout change. This event is being listened to by upper app
+         * in order to layout again and adjust every element based on the new content.
+         */
         contentLayoutChange$
       }
     };
@@ -3937,6 +4019,8 @@
       const rect = containerElement.getBoundingClientRect();
       const normalizedValues = {
         ...rect,
+        // we want to round to first decimal because it's possible to have half pixel
+        // however browser engine can also gives back x.yyyy based on their precision
         width: Math.round(rect.width * 10) / 10,
         height: Math.round(rect.height * 10) / 10
       };
@@ -4016,6 +4100,8 @@
       return {
         columnHeight,
         columnWidth,
+        // horizontalMargin,
+        // verticalMargin,
         width
       };
     };
@@ -4333,22 +4419,37 @@
         justify-content: ${spreadPosition === `left` ? `flex-end` : spreadPosition === `right` ? `flex-start` : `center`};
       ` : ``}
     }
-    ${``}
+    ${/*
+      might be html * but it does mess up things like figure if so.
+      check accessible_epub_3
+    */
+    ``}
     html, body {
       height: 100%;
       width: 100%;
     }
-    ${``}
+    ${/*
+      This one is important for preventing 100% img to resize above
+      current width. Especially needed for cbz conversion
+    */
+    ``}
     html, body {
       -max-width: ${columnWidth}px !important;
     }
-    ${``}
+    ${/*
+    * @see https://hammerjs.github.io/touch-action/
+    * It needs to be disabled when using free scroll
+    */
+    ``}
     html, body {
       ${enableTouch ? `
         touch-action: none
       ` : ``}
     }
-    ${``}
+    ${/*
+      prevent drag of image instead of touch on firefox
+    */
+    ``}
     img {
       user-select: none;
       -webkit-user-drag: none;
@@ -4356,9 +4457,18 @@
       -moz-user-drag: none;
       -o-user-drag: none;
       user-drag: none;
-      ${``}
+      ${/*
+      prevent weird overflow or margin. Try `block` if `flex` has weird behavior
+    */
+    ``}
       display: flex;
-      ${``}
+      ${/*
+      If the document does not have viewport, we cannot scale anything inside.
+      This should never happens with a valid epub document however it will happens if
+      we load .jpg, .png, etc directly in the iframe. This is expected, in this case we force
+      the inner content to display correctly.
+    */
+    ``}
       ${!viewportDimensions ? `
         -width: 100%;
         max-width: 100%;
@@ -4489,7 +4599,10 @@
       height: 100%;
       margin: 0;
     }
-    ${``}
+    ${/*
+    * @see https://hammerjs.github.io/touch-action/
+    */
+    ``}
     html, body {
       touch-action: none;
     }
@@ -4497,7 +4610,10 @@
   };
   const buildStyleForReflowableImageOnly = ({ isScrollable, enableTouch }) => {
     return `
-    ${``}
+    ${/*
+    * @see https://hammerjs.github.io/touch-action/
+    */
+    ``}
     html, body {
       width: 100%;
       margin: 0;
@@ -4512,9 +4628,14 @@
         margin: 0;
         padding: 0;
         box-sizing: border-box;
-        ${``}
+        ${// we make sure img spread on entire screen
+    ``}
         width: 100%;
-        ${``}
+        ${/**
+    * line break issue
+    * @see https://stackoverflow.com/questions/37869020/image-not-taking-up-the-full-height-of-container
+    */
+    ``}
         display: block;
       }
     ` : ``}
@@ -4529,13 +4650,28 @@
     parsererror {
       display: none !important;
     }
-    ${``}
+    ${/*
+      might be html * but it does mess up things like figure if so.
+      check accessible_epub_3
+    */
+    ``}
     html, body {
       margin: 0;
       padding: 0 !important;
       -max-width: ${columnWidth}px !important;
     }
-    ${``}
+    ${/*
+      body {
+        height: ${columnHeight}px !important;
+        width: ${columnWidth}px !important;
+        -margin-left: ${horizontalMargin}px !important;
+        -margin-right: ${horizontalMargin}px !important;
+        -margin: ${verticalMargin}px ${horizontalMargin}px !important;
+        -padding-top: ${horizontalMargin}px !important;
+        -padding-bottom: ${horizontalMargin}px !important;
+      }
+    */
+    ``}
     body {
       padding: 0 !important;
       width: ${width}px !important;
@@ -4551,18 +4687,33 @@
       margin: 0;
     }
     body:focus-visible {
-      ${``}
+      ${/*
+      we make sure that there are no outline when we focus something inside the iframe
+    */
+    ``}
       outline: none;
     }
-    ${``}
+    ${/*
+    * @see https://hammerjs.github.io/touch-action/
+    */
+    ``}
     html, body {
       touch-action: none;
     }
-    ${``}
+    ${/*
+      this messes up hard, be careful with this
+    */
+    ``}
     * {
       -max-width: ${columnWidth}px !important;
     }
-    ${``}
+    ${/*
+      this is necessary to have a proper calculation when determining size
+      of iframe content. If an img is using something like width:100% it would expand to
+      the size of the original image and potentially gives back a wrong size (much larger)
+      @see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns/Handling_Overflow_in_Multicol
+    */
+    ``}
     img, video, audio, object, svg {
       max-width: 100%;
       max-width: ${columnWidth}px !important;
@@ -4581,7 +4732,17 @@
       box-sizing: border-box;
       d-max-width: ${columnWidth}px !important;
     }
-    ${``}
+    ${/*
+      img, video, audio, object, svg {
+        max-height: ${columnHeight}px !important;
+        box-sizing: border-box;
+        object-fit: contain;
+        -webkit-column-break-inside: avoid;
+        page-break-inside: avoid;
+        break-inside: avoid;
+      }
+    */
+    ``}
     table {
       max-width: ${columnWidth}px !important;
       table-layout: fixed;
@@ -4778,7 +4939,11 @@
       this.isRange = false;
       this.opts = Object.assign(
         {
+          // If CFI is a Simple Range, pretend it isn't
+          // by parsing only the start of the range
           flattenRange: false,
+          // Strip temporal, spatial, offset and textLocationAssertion
+          // from places where they don't make sense
           stricter: true
         },
         opts || {}
@@ -4898,6 +5063,7 @@
         return cfi.get();
       }
     }
+    // Takes two CFI paths and compares them
     static comparePath(a, b) {
       const max = Math.max(a.length, b.length);
       let i, cA, cB, diff;
@@ -4914,11 +5080,13 @@
       }
       return 0;
     }
+    // Sort an array of CFI objects
     static sort(a) {
       a.sort((a2, b) => {
         return this.compare(a2, b);
       });
     }
+    // Takes two CFI objects and compares them.
     static compare(a, b) {
       let oA = a.get();
       let oB = b.get();
@@ -4938,6 +5106,7 @@
         return this.comparePath(oA, oB);
       }
     }
+    // Takes two parsed path parts (assuming path is split on '!') and compares them.
     static compareParts(a, b) {
       const max = Math.max(a.length, b.length);
       let i, cA, cB, diff;
@@ -4979,6 +5148,7 @@
         return str;
       }
     }
+    // decode HTML/XML entities and compute length
     trueLength(dom, str) {
       return this.decodeEntities(dom, str).length;
     }
@@ -5244,6 +5414,9 @@
         throw new Error(`Missing child node index in CFI`);
       return { parsed: o, offset: i, newDoc: state === `!` };
     }
+    // The CFI counts child nodes differently from the DOM
+    // Retrieve the child of parentNode at the specified index
+    // according to the CFI standard way of counting
     getChildNodeByCFIIndex(dom, parentNode, index, offset) {
       const children = parentNode.childNodes;
       if (!children.length)
@@ -5322,6 +5495,7 @@
       }
       return false;
     }
+    // Use a Text Location Assertion to correct and offset
     correctOffset(dom, node, offset, assertion) {
       let curNode = node;
       let matchStr;
@@ -5419,6 +5593,15 @@
       }
       return o;
     }
+    // Each part of a CFI (as separated by '!')
+    // references a separate HTML/XHTML/XML document.
+    // This function takes an index specifying the part
+    // of the CFI and the appropriate Document or XMLDocument
+    // that is referenced by the specified part of the CFI
+    // and returns the URI for the document referenced by
+    // the next part of the CFI
+    // If the opt `ignoreIDs` is true then IDs
+    // will not be used while resolving
     resolveURI(index, dom, opts) {
       opts = opts || {};
       if (index < 0 || index > this.parts.length - 2) {
@@ -5430,7 +5613,8 @@
       const o = this.resolveNode(index, subparts, dom, opts);
       let node = o.node;
       const tagName = node.tagName.toLowerCase();
-      if (tagName === `itemref` && node.parentNode.tagName.toLowerCase() === `spine`) {
+      if (tagName === `itemref` && // @ts-ignore
+      node.parentNode.tagName.toLowerCase() === `spine`) {
         const idref = node.getAttribute(`idref`);
         if (!idref)
           throw new Error(`Referenced node had not 'idref' attribute`);
@@ -5477,6 +5661,9 @@
         delete o.offset;
       return { ...lastPart, ...o };
     }
+    // Takes the Document or XMLDocument for the final
+    // document referenced by the CFI
+    // and returns the node and offset into that node
     resolveLast(dom, opts) {
       opts = Object.assign(
         {
@@ -5734,7 +5921,22 @@
               spineItem: beginSpineItem,
               spineItemIndex: beginItemIndex,
               pageIndex: beginPageIndex,
-              cfi: (lastExpectedNavigation == null ? void 0 : lastExpectedNavigation.type) === `navigate-from-cfi` && spineItemToFocus === beginSpineItem ? lastExpectedNavigation.data : data.triggeredBy === `adjust` && context.getSettings().computedPageTurnMode === `controlled` ? pagination.getInfo().beginCfi : beginItemIndex !== pagination.getInfo().beginSpineItemIndex ? cfiLocator.getRootCfi(beginSpineItem) : cfiLocator.getRootCfi(beginSpineItem),
+              /**
+               * Because the start of a navigation may involve animations and interactions we don't resolve heavy CFI here.
+               * We do want to have certain information correct in the pagination right after a navigation (same tick) but we just
+               * defer heavy non vital stuff for later.
+               * There are only 4 different cfi update at this stage:
+               * - navigation comes from cfi, we simply affect the cfi to the pagination
+               * - navigation comes from adjustment with controlled mode, we don't update the cfi, just pass the previous one
+               * - navigation comes from adjustment with free mode, we will update with root cfi if needed because we could be on new page
+               * - navigation is not from adjustment, this means we are on either new page or new reading item, we use light cfi with root (no dom lookup)
+               *
+               * The cfi is later adjusted with heavy dom lookup once the viewport is free.
+               */
+              cfi: (lastExpectedNavigation == null ? void 0 : lastExpectedNavigation.type) === `navigate-from-cfi` && spineItemToFocus === beginSpineItem ? lastExpectedNavigation.data : data.triggeredBy === `adjust` && context.getSettings().computedPageTurnMode === `controlled` ? pagination.getInfo().beginCfi : beginItemIndex !== pagination.getInfo().beginSpineItemIndex ? cfiLocator.getRootCfi(beginSpineItem) : (
+                /* @todo check ? */
+                cfiLocator.getRootCfi(beginSpineItem)
+              ),
               options: {
                 isAtEndOfChapter: false
               }
@@ -5743,7 +5945,10 @@
               spineItem: endSpineItem,
               spineItemIndex: endItemIndex,
               pageIndex: endPageIndex,
-              cfi: (lastExpectedNavigation == null ? void 0 : lastExpectedNavigation.type) === `navigate-from-cfi` && spineItemToFocus === endSpineItem ? lastExpectedNavigation.data : data.triggeredBy === `adjust` && context.getSettings().computedPageTurnMode === `controlled` ? pagination.getInfo().endCfi : endItemIndex !== pagination.getInfo().endSpineItemIndex ? cfiLocator.getRootCfi(endSpineItem) : cfiLocator.getRootCfi(endSpineItem),
+              cfi: (lastExpectedNavigation == null ? void 0 : lastExpectedNavigation.type) === `navigate-from-cfi` && spineItemToFocus === endSpineItem ? lastExpectedNavigation.data : data.triggeredBy === `adjust` && context.getSettings().computedPageTurnMode === `controlled` ? pagination.getInfo().endCfi : endItemIndex !== pagination.getInfo().endSpineItemIndex ? cfiLocator.getRootCfi(endSpineItem) : (
+                /* @todo check ? */
+                cfiLocator.getRootCfi(endSpineItem)
+              ),
               options: {
                 isAtEndOfChapter: false
               }
@@ -5773,7 +5978,16 @@
       takeUntil(context.$.destroy$)
     ).subscribe();
     rxjs.merge(
+      /**
+       * We want to update content after navigation since we are at a different place.
+       * We also wait for navigated items to be updated so that we have access to correct focus.
+       * which is why we use this observer rather than `navigation$`.
+       */
       itemUpdateOnNavigation$,
+      /**
+       * This one make sure we also listen for layout change and that we execute the code once the navigation
+       * has been adjusted (whether it's needed or not).
+       */
       navigationAdjusted$
     ).pipe(
       switchMap(() => {
@@ -5972,7 +6186,10 @@
       const isPrePaginated = ((_a = context.getManifest()) == null ? void 0 : _a.renditionLayout) === `pre-paginated`;
       const isUsingFreeScroll = context.getSettings().computedPageTurnMode === `scrollable`;
       orderedSpineItemsSubject$.value.forEach((orderedSpineItem, index) => {
-        const isBeforeFocusedWithPreload = index < leftIndex && !isPrePaginated && isUsingFreeScroll ? true : index < leftIndex - numberOfAdjacentSpineItemToPreLoad;
+        const isBeforeFocusedWithPreload = (
+          // we never want to preload anything before on free scroll on flow because it could offset the cursor
+          index < leftIndex && !isPrePaginated && isUsingFreeScroll ? true : index < leftIndex - numberOfAdjacentSpineItemToPreLoad
+        );
         const isAfterTailWithPreload = index > rightIndex + numberOfAdjacentSpineItemToPreLoad;
         if (!isBeforeFocusedWithPreload && !isAfterTailWithPreload) {
           orderedSpineItem.loadContent();
@@ -6178,7 +6395,8 @@
       var _a, _b, _c;
       const pageSize = context.getPageSize();
       const frame = (_b = (_a = spineItem.spineItemFrame) == null ? void 0 : _a.getManipulableFrame()) == null ? void 0 : _b.frame;
-      if (((_c = frame == null ? void 0 : frame.contentWindow) == null ? void 0 : _c.document) && frame.contentWindow.document.body !== null) {
+      if (((_c = frame == null ? void 0 : frame.contentWindow) == null ? void 0 : _c.document) && // very important because it is being used by next functions
+      frame.contentWindow.document.body !== null) {
         const { x: left, y: top } = getSpineItemPositionFromPageIndex(pageIndex, spineItem);
         const viewport = {
           left,
@@ -6748,8 +6966,14 @@
       chapterPageNavigation$,
       leftPageNavigation$,
       rightPageNavigation$,
+      // for some reason after too much item ts complains
       rxjs.merge(cfiNavigation$, pageNavigation$)
     ).pipe(
+      /**
+       * Ideally when manually navigating we expect the navigation to be different from the previous one.
+       * This is because manual navigation is not used with scroll where you can move within the same item. A manual
+       * navigation would theoretically always move to different items.
+       */
       withLatestFrom(currentNavigationSubject$),
       filter(([navigation, currentNavigation]) => navigator2.areNavigationDifferent(navigation, currentNavigation)),
       map(([navigation]) => navigation)
@@ -6924,6 +7148,9 @@
       }
       const { x, y } = element.getBoundingClientRect();
       const newValue = {
+        // we want to round to first decimal because it's possible to have half pixel
+        // however browser engine can also gives back x.yyyy based on their precision
+        // @see https://stackoverflow.com/questions/13847053/difference-between-and-math-floor for ~~
         x: ~~(Math.abs(x) * 10) / 10,
         y: ~~(Math.abs(y) * 10) / 10
       };
@@ -7134,6 +7361,14 @@
         const animationDuration = currentEvent.animation === `snap` ? context.getSettings().computedSnapAnimationDuration : context.getSettings().computedPageTurnAnimationDuration;
         const pageTurnAnimation = currentEvent.animation === `snap` ? `slide` : context.getSettings().computedPageTurnAnimation;
         return rxjs.of(currentEvent).pipe(
+          /**
+           * @important
+           * Optimization:
+           * When the adjustment does not need animation it means we want to be there as fast as possible
+           * One example is when we adjust position after layout. In this case we don't want to have flicker or see
+           * anything for x ms while we effectively adjust. We want it to be immediate.
+           * However when user is repeatedly turning page, we can improve smoothness by delaying a bit the adjustment
+           */
           currentEvent.shouldAnimate ? delay(1, rxjs.animationFrameScheduler) : rxjs.identity,
           tap((data) => {
             const noAdjustmentNeeded = false;
@@ -7150,6 +7385,14 @@
               element.style.setProperty(`opacity`, `1`);
             }
           }),
+          /**
+           * @important
+           * We always need to adjust the reading offset. Even if the current viewport value
+           * is the same as the payload position. This is because an already running animation could
+           * be active, meaning the viewport is still adjusting itself (after animation duration). So we
+           * need to adjust to anchor to the payload position. This is because we use viewport computed position,
+           * not the value set by `setProperty`
+           */
           withLatestFrom(hooks$),
           tap(([data, hooks]) => {
             if (pageTurnAnimation !== `fade`) {
@@ -7188,6 +7431,12 @@
       map((states) => states.every((state) => state === `end`) ? `free` : `busy`),
       distinctUntilChanged(),
       shareReplay(1),
+      /**
+       * @important
+       * Since state$ is being updated from navigation$ and other exported streams we need it to be
+       * hot so it always have the correct value no matter when someone subscribe later.
+       * We cannot wait for the cold stream to start after a navigation already happened for example.
+       */
       makeItHot
     );
     const waitForViewportFree$ = state$.pipe(
@@ -7195,6 +7444,24 @@
       rxjs.take(1)
     );
     const navigationAdjustedAfterLayout$ = spine.$.layout$.pipe(
+      /**
+       * @important
+       * Careful with using debounce / throttle here since it can decrease user experience
+       * when layout happens it can means an item before the current one has been unloaded, at current code
+       * we unload and size back each item to the screen so it will have the effect of flicker for user.
+       * Consider this workflow:
+       * - user navigate to page 2
+       * - viewport move to item 2
+       * - page 1 unload and goes back from 2000px to 500px
+       * - layout triggered
+       * - viewport is now on an item far after item 2 because item 1 shrink (PROBLEM)
+       * - sometime after viewport is adjusted back to item 2.
+       *
+       * Two solution to fix this issue:
+       * - maybe later try to implement a different strategy and never shrink back item unless they are loaded
+       * - do not use debounce / throttle and navigate back to the item right on the same tick
+       */
+      // debounceTime(10, animationFrameScheduler),
       switchMap(
         () => waitForViewportFree$.pipe(
           switchMap(() => {
@@ -7264,10 +7531,18 @@
         if (context.isRTL()) {
           return {
             x: leftEnd - position.x - context.getPageSize().width,
+            // y: (topEnd - position.y) - context.getPageSize().height,
             y: Math.max(0, position.y - topStart)
           };
         }
         return {
+          /**
+           * when using spread the item could be on the right and therefore will be negative
+           * @example
+           * 400 (position = viewport), page of 200
+           * 400 - 600 = -200.
+           * However we can assume we are at 0, because we in fact can see the beginning of the item
+           */
           x: Math.max(0, position.x - leftStart),
           y: Math.max(0, position.y - topStart)
         };
@@ -7279,6 +7554,7 @@
       if (context.isRTL()) {
         return {
           x: leftEnd - spineItemPosition.x - context.getPageSize().width,
+          // y: (topEnd - spineItemPosition.y) - context.getPageSize().height,
           y: topStart + spineItemPosition.y
         };
       }
@@ -7619,10 +7895,23 @@
       destroy,
       setSettings: context.setSettings,
       settings$: context.$.settings$,
+      /**
+       * @important
+       * BehaviorSubject
+       */
       pagination$: pagination.$.info$,
       $: {
         state$: stateSubject$.asObservable(),
+        /**
+         * Dispatched when the reader has loaded a book and is displayed a book.
+         * Using navigation API and getting information about current content will
+         * have an effect.
+         * It can typically be used to hide a loading indicator.
+         */
         ready$: readySubject$.asObservable(),
+        /**
+         * Dispatched when a change in selection happens
+         */
         selection$: selectionSubject$.asObservable(),
         viewportState$: viewportNavigator.$.state$,
         layout$: spine.$.layout$,
@@ -7874,6 +8163,10 @@
     };
     return {
       ...reader,
+      // $: {
+      //   ...reader.$,
+      //   errors$: merge(reader.$.errors$, errorsSubject$.asObservable())
+      // },
       destroy,
       load
     };
@@ -8012,7 +8305,11 @@
         `prose-reader-accessibility`,
         `
       :focus-visible {
-        ${``}
+        ${/*
+          Some epubs remove the outline, this is not good practice since it reduce accessibility.
+          We will try to restore it by force.
+        */
+        ``}
         outline: -webkit-focus-ring-color auto 1px;
       }
     `
@@ -8167,23 +8464,27 @@
     container.appendChild(detailsElement);
     return container;
   };
-  const createReaderWithEnhancers = loadingEnhancer(
-    webkitEnhancer(
-      fontsEnhancer(
-        linksEnhancer(
-          accessibilityEnhancer(
-            resourcesEnhancer(
-              utilsEnhancer(
-                layoutEnhancer(
-                  zoomEnhancer(
-                    mediaEnhancer(
-                      chromeEnhancer(
-                        navigationEnhancer(
-                          themeEnhancer(
-                            hotkeysEnhancer(
-                              paginationEnhancer(
-                                progressionEnhancer(
-                                  createReader
+  const createReaderWithEnhancers = (
+    //__
+    loadingEnhancer(
+      webkitEnhancer(
+        fontsEnhancer(
+          linksEnhancer(
+            accessibilityEnhancer(
+              resourcesEnhancer(
+                utilsEnhancer(
+                  layoutEnhancer(
+                    zoomEnhancer(
+                      mediaEnhancer(
+                        chromeEnhancer(
+                          navigationEnhancer(
+                            themeEnhancer(
+                              hotkeysEnhancer(
+                                paginationEnhancer(
+                                  progressionEnhancer(
+                                    // __
+                                    createReader
+                                  )
                                 )
                               )
                             )