currentPage is not correct when the viewport's height is a lot higher than the page's

[songkeys]

when the viewport's height is a lot higher than the page's height,

• the currentPage will be 2 from the start (should be 1)
• the currentPage cannot be 1 anymore

(setting viewportGap: 0 solves the above two issues but no the following.)

• when call scrollToNextPage(), the page jumps to 3 then immediately to 4 (which is 1-off for every page)
• when call scrollToPreviousPage(), the page does not jump
• when call scrollToPreviousPage(), it only scrolls if we scroll the pdf manually just before, and it does not scroll to the correct previous page but the current page

anyway, the behavior is so strange i believe there is something wrong with the height calculation.

[songkeys]

Follow-up after deeper debugging (generated by ai, might not accurate, just for reference):

Environment

• @embedpdf/plugin-scroll v1.4.1 (from npm default install)
• Viewer running with the default plugin chain (Loader, Viewport, Scroll, Render, Zoom, etc.) inside a React 19 application
• Reproduced on Chrome 129 on macOS, but the math in the bundled code is deterministic so the browser doesn’t seem to matter

Baseline behaviour (default config, viewport gap = 10px)

1. Load any multipage PDF with a tall viewport (e.g. browser height ≥ 2× the page height + gap).
2. The Scroll plugin immediately reports currentPage = 2 even though the first physical page is aligned to the top of the viewport.
3. scrollToNextPage() jumps from 2 → 3 → 4 (two pages at a time).
4. scrollToPreviousPage() either does nothing or snaps back to the same page unless you manually scroll first.

Root cause: the area-based heuristic in BaseScrollStrategy.calculatePageVisibility penalises the first page because the Viewport plugin injects padding equal to its viewportGap into the scroll container. The Scroll plugin also adds that gap when computing scroll targets (getScrollPositionForPage). The result is that page 1 is considered partially off-screen (its visible height = pageHeight − gap), while page 2 is fully visible. With page 2 showing more square pixels, determineCurrentPage picks 2 as “most visible”.

Behaviour with Viewport gap forced to 0

createPluginRegistration(ViewportPluginPackage, { viewportGap: 0 })

• Page 1 now starts as currentPage = 1 (the padding bias is gone).
• However, any viewport that is tall enough to show more than one page still trips the pagination helpers: scrollToNextPage() overshoots and scrollToPreviousPage() refuses to move.

Root cause (gap-independent): even without padding, the “most visible area” heuristic still favours whichever page is lower in the viewport. After a programmatic scroll, the lower page has slightly more visible area (no blank space above it), so determineCurrentPage immediately advances to the next page when the smooth scroll finishes. On the next refresh tick, the following page wins, so the reported currentPage advances twice. The previous-page helper sees that you are “already” before the requested page and stops.

Code references

• Viewport padding is defined in packages/plugin-viewport/src/shared/components/viewport.tsx lines 7–27. The component reads the configured gap from viewportProvides.getViewportGap() and applies it directly as padding: ${viewportGap}px on the scroll container.
• The scroll strategy’s area heuristic lives in packages/plugin-scroll/src/lib/strategies/base-strategy.ts:
  • calculatePageVisibility (lines 89–140) computes the intersection between each page and the viewport, producing the visiblePercentage metric.
  • determineCurrentPage (lines 141–149) picks the page with the highest percentage, breaking ties by the lowest page number.
  • getScrollPositionForPage (lines 181–214) adds this.viewportGap to both x and y when returning the scroll target, which is why the first page appears shortened whenever the viewport gap is non-zero.
• The pagination helpers that overshoot are in packages/plugin-scroll/src/lib/scroll-plugin.ts:
  • The constructor (lines 61–103) pulls viewport.getViewportGap() into the strategy config, so the gap value above flows straight into the scroll math.
  • scrollToNextPage (lines 273–295) and scrollToPreviousPage (lines 296–318) just call scrollToPage and rely on the currentPage emitted by the strategy to settle, which is why the area heuristic directly affects their behaviour.

Suggested fixes

1. When calculating visibility, account for the viewport padding (subtract viewportGap from the intersection height) so the first page isn’t artificially shortened.
2. Consider redefining determineCurrentPage so a page is considered “active” when its midpoint crosses the viewport midpoint (or centreline) instead of “largest visible area”. That would make scrollToNextPage/scrollToPreviousPage stable regardless of viewport height.
3. Alternatively, during a programmatic page change keep currentPage pinned to pageChangeState.targetPage until the animation completes, then fall back to the area heuristic.

Happy to help test a patch once there’s a proposed fix.