@prose-reader/core 1.14.0 → 1.16.0

package/dist/prose.js

@@ -2125,7 +2125,15 @@ const fontsEnhancer = (next) => (options) => {
   });
   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;` : ``}
@@ -2167,6 +2175,9 @@ const fontsEnhancer = (next) => (options) => {
   );
   return {
     ...reader,
+    /**
+     * Absorb current enhancer settings and passthrough the rest to reader
+     */
     setSettings: (settings) => {
       const {
         fontJustification: fontJustification2 = settingsSubject$.value.fontJustification,
@@ -2180,6 +2191,9 @@ const fontsEnhancer = (next) => (options) => {
       }
       reader.setSettings(passthroughSettings);
     },
+    /**
+     * Combine reader settings with enhancer settings
+     */
     settings$
   };
 };
@@ -2447,6 +2461,7 @@ const time = (name, targetDuration = 0) => {
   };
 };
 const createReport = (namespace) => ({
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   log: (...data) => {
     if (window.__PROSE_READER_DEBUG) {
       if (namespace)
@@ -2455,6 +2470,7 @@ const createReport = (namespace) => ({
         console.log(wrap(ROOT_NAMESPACE), ...data);
     }
   },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   warn: (...data) => {
     if (window.__PROSE_READER_DEBUG) {
       if (namespace)
@@ -2463,9 +2479,22 @@ const createReport = (namespace) => ({
         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) {
@@ -2479,6 +2508,7 @@ const createReport = (namespace) => ({
       }
     }
   },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   measurePerformance: (name, targetDuration = 10, functionToMeasure, { disable } = {}) => {
     if (disable || !window.__PROSE_READER_DEBUG)
       return functionToMeasure;
@@ -2673,15 +2703,37 @@ const paginationEnhancer = (next) => (options) => {
       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,
@@ -2691,6 +2743,11 @@ const paginationEnhancer = (next) => (options) => {
         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) => {
@@ -2730,6 +2787,9 @@ const paginationEnhancer = (next) => (options) => {
       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)
       };
     }),
@@ -2760,28 +2820,34 @@ const paginationEnhancer = (next) => (options) => {
 const buildChapterInfoFromSpineItem = (manifest, item) => {
   var _a;
   const { href } = item;
-  return getChapterInfo(href, ((_a = manifest.nav) == null ? void 0 : _a.toc) ?? []);
+  return getChapterInfo(href, ((_a = manifest.nav) == null ? void 0 : _a.toc) ?? [], manifest);
 };
-const getChapterInfo = (href, tocItems) => {
-  return tocItems.reduce((acc, tocItem) => {
-    const indexOfHash = tocItem.href.indexOf(`#`);
-    const tocItemPathWithoutAnchor = indexOfHash > 0 ? tocItem.href.substr(0, indexOfHash) : tocItem.href;
+const getChapterInfo = (href, tocItem, manifest) => {
+  const spineItemIndex = manifest.spineItems.findIndex((item) => item.href === href);
+  return tocItem.reduce((acc, tocItem2) => {
+    const indexOfHash = tocItem2.href.indexOf(`#`);
+    const tocItemPathWithoutAnchor = indexOfHash > 0 ? tocItem2.href.substr(0, indexOfHash) : tocItem2.href;
     const tocItemHrefWithoutFilename = tocItemPathWithoutAnchor.substring(0, tocItemPathWithoutAnchor.lastIndexOf("/"));
     const hrefWithoutFilename = href.substring(0, href.lastIndexOf("/"));
     const hrefIsChapterHref = href.endsWith(tocItemPathWithoutAnchor);
     const hrefIsWithinChapter = hrefWithoutFilename !== "" && hrefWithoutFilename.endsWith(tocItemHrefWithoutFilename);
-    if (hrefIsChapterHref || hrefIsWithinChapter) {
+    const isPossibleTocItemCandidate = hrefIsChapterHref || hrefIsWithinChapter;
+    if (isPossibleTocItemCandidate) {
+      const spineItemIndexOfPossibleCandidate = manifest.spineItems.findIndex((item) => item.href === tocItem2.href);
+      const spineItemIsBeforeThisTocItem = spineItemIndex < spineItemIndexOfPossibleCandidate;
+      if (spineItemIsBeforeThisTocItem)
+        return acc;
       return {
-        title: tocItem.title,
-        path: tocItem.path
+        title: tocItem2.title,
+        path: tocItem2.path
       };
     }
-    const subInfo = getChapterInfo(href, tocItem.contents);
+    const subInfo = getChapterInfo(href, tocItem2.contents, manifest);
     if (subInfo) {
       return {
         subChapter: subInfo,
-        title: tocItem.title,
-        path: tocItem.path
+        title: tocItem2.title,
+        path: tocItem2.path
       };
     }
     return acc;
@@ -2814,7 +2880,11 @@ const themeEnhancer = (next) => (options) => {
       }
       ${(foundTheme == null ? void 0 : foundTheme.foregroundColor) ? `
           body * {
-            ${``}
+            ${/*
+      Ideally, we would like to use !important but it could break publisher specific
+      cases
+    */
+    ``}
             color: ${foundTheme.foregroundColor};
           }
         ` : ``}
@@ -3412,6 +3482,8 @@ const createLoader = ({
     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]) => {
@@ -3432,13 +3504,16 @@ const createLoader = ({
   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 of(frame);
           } else {
@@ -3494,6 +3569,7 @@ const createLoader = ({
             })
           );
         }),
+        // we stop loading as soon as unload is requested
         takeUntil(unloadSubject$)
       );
     }),
@@ -3620,6 +3696,12 @@ const createFrameItem = ({
     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) {
@@ -3630,6 +3712,8 @@ const createFrameItem = ({
         }
       }
     },
+    // @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;
@@ -3651,6 +3735,10 @@ const createFrameItem = ({
       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$
     }
   };
@@ -3929,6 +4017,8 @@ const createCommonSpineItem = ({
     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
     };
@@ -4008,6 +4098,8 @@ const createCommonSpineItem = ({
     return {
       columnHeight,
       columnWidth,
+      // horizontalMargin,
+      // verticalMargin,
       width
     };
   };
@@ -4325,22 +4417,37 @@ const buildDocumentStyle = ({
         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;
@@ -4348,9 +4455,18 @@ const buildDocumentStyle = ({
       -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%;
@@ -4481,7 +4597,10 @@ const buildStyleForViewportFrame = () => {
       height: 100%;
       margin: 0;
     }
-    ${``}
+    ${/*
+  * @see https://hammerjs.github.io/touch-action/
+  */
+  ``}
     html, body {
       touch-action: none;
     }
@@ -4489,7 +4608,10 @@ const buildStyleForViewportFrame = () => {
 };
 const buildStyleForReflowableImageOnly = ({ isScrollable, enableTouch }) => {
   return `
-    ${``}
+    ${/*
+  * @see https://hammerjs.github.io/touch-action/
+  */
+  ``}
     html, body {
       width: 100%;
       margin: 0;
@@ -4504,9 +4626,14 @@ const buildStyleForReflowableImageOnly = ({ isScrollable, enableTouch }) => {
         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;
       }
     ` : ``}
@@ -4521,13 +4648,28 @@ const buildStyleWithMultiColumn = ({
     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;
@@ -4543,18 +4685,33 @@ const buildStyleWithMultiColumn = ({
       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;
@@ -4573,7 +4730,17 @@ const buildStyleWithMultiColumn = ({
       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;
@@ -4770,7 +4937,11 @@ class CFI {
     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 || {}
@@ -4890,6 +5061,7 @@ class CFI {
       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;
@@ -4906,11 +5078,13 @@ class CFI {
     }
     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();
@@ -4930,6 +5104,7 @@ class CFI {
       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;
@@ -4971,6 +5146,7 @@ class CFI {
       return str;
     }
   }
+  // decode HTML/XML entities and compute length
   trueLength(dom, str) {
     return this.decodeEntities(dom, str).length;
   }
@@ -5236,6 +5412,9 @@ class CFI {
       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)
@@ -5314,6 +5493,7 @@ class CFI {
     }
     return false;
   }
+  // Use a Text Location Assertion to correct and offset
   correctOffset(dom, node, offset, assertion) {
     let curNode = node;
     let matchStr;
@@ -5411,6 +5591,15 @@ class CFI {
     }
     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) {
@@ -5422,7 +5611,8 @@ class CFI {
     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`);
@@ -5469,6 +5659,9 @@ class CFI {
       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(
       {
@@ -5726,7 +5919,22 @@ const createSpine = ({
             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
             }
@@ -5735,7 +5943,10 @@ const createSpine = ({
             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
             }
@@ -5765,7 +5976,16 @@ const createSpine = ({
     takeUntil(context.$.destroy$)
   ).subscribe();
   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(() => {
@@ -5964,7 +6184,10 @@ const createSpineItemManager = ({ context }) => {
     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();
@@ -6170,7 +6393,8 @@ const createLocationResolver$1 = ({ context }) => {
     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,
@@ -6740,8 +6964,14 @@ const createManualViewportNavigator = ({
     chapterPageNavigation$,
     leftPageNavigation$,
     rightPageNavigation$,
+    // for some reason after too much item ts complains
     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)
@@ -6916,6 +7146,9 @@ const createViewportNavigator = ({
     }
     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
     };
@@ -7126,6 +7359,14 @@ const createViewportNavigator = ({
       const animationDuration = currentEvent.animation === `snap` ? context.getSettings().computedSnapAnimationDuration : context.getSettings().computedPageTurnAnimationDuration;
       const pageTurnAnimation = currentEvent.animation === `snap` ? `slide` : context.getSettings().computedPageTurnAnimation;
       return 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, animationFrameScheduler) : identity$1,
         tap((data) => {
           const noAdjustmentNeeded = false;
@@ -7142,6 +7383,14 @@ const createViewportNavigator = ({
             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`) {
@@ -7180,6 +7429,12 @@ const createViewportNavigator = ({
     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(
@@ -7187,6 +7442,24 @@ const createViewportNavigator = ({
     take$1(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(() => {
@@ -7256,10 +7529,18 @@ const createLocationResolver = ({
       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)
       };
@@ -7271,6 +7552,7 @@ const createLocationResolver = ({
     if (context.isRTL()) {
       return {
         x: leftEnd - spineItemPosition.x - context.getPageSize().width,
+        // y: (topEnd - spineItemPosition.y) - context.getPageSize().height,
         y: topStart + spineItemPosition.y
       };
     }
@@ -7611,10 +7893,23 @@ const createReader = ({ containerElement, hooks: initialHooks, ...settings }) =>
     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$,
@@ -7866,6 +8161,10 @@ const resourcesEnhancer = (next) => (options) => {
   };
   return {
     ...reader,
+    // $: {
+    //   ...reader.$,
+    //   errors$: merge(reader.$.errors$, errorsSubject$.asObservable())
+    // },
     destroy,
     load
   };
@@ -8004,7 +8303,11 @@ const accessibilityEnhancer = (next) => (options) => {
       `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;
       }
     `
@@ -8159,23 +8462,27 @@ const defaultLoadingElementCreate = ({ container, item }) => {
   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
+                                )
                               )
                             )
                           )