Skip to content

fix(core)!: navigate at each move of a user scroll - #808

Open
mbret wants to merge 9 commits into
developfrom
claude/intelligent-volta-lhxz83-follow-scroll
Open

mbret wants to merge 9 commits into
developfrom
claude/intelligent-volta-lhxz83-follow-scroll

Conversation

@mbret

@mbret mbret commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Why

In a book that scrolls, a page turn or a "next spine item" made right after a scroll moves the book back. The user scrolls from the first page to the third one and presses "next". The reader shows the second page.

The reader navigated for a scroll only once the scroll was over, half a second after its last move. Until then, a navigation that starts from where the reader is started from where the scroll began.

  • Change: the scroll navigates at each move, so the current navigation is where the user is.
  • Gain: a page turn and a "next spine item" start from where the scroll has taken the book.
  • Cost: each move of a scroll takes about 0.1 ms more script time, or 0.7 ms on a CPU six times slower.

Fixes #779. It applies decision 3, option a, of #807: the scroll navigates at each move.

Reviewer guide

Changes

  • UserScrollNavigation makes a navigation at each move that the browser reports.
  • A change of page turn mode during a scroll lands on the page of the last move, not on the next page.
  • In a book that scrolls, the direction of a navigation says by which end the reader came into its spine item.

Other changes

  • No user scroll begins before the first layout, so none replaces the target the reader opens at.
  • scrollPositionKnownToReader$ is removed from the scroll controller: its one reader is gone.
  • Unit cases for each change, and for a scroll move made during a layout pass.
  • Two browser tests: "next spine item" during a scroll, and a mode change inside a page.
  • Docs: core-api/navigation, learn/navigation, learn/page-turn-mode and learn/pagination.

Public API

Breaking: this needs a semver major. One name is removed: reader.navigation.scrollNavigationController.scrollPositionKnownToReader$. It was released in v44. No docs page names it. One commit of the branch carries the BREAKING CHANGE note that the release reads.

Four documented behaviours change during a scroll of the user's, in a book that scrolls:

  • reader.navigation.navigation$ and navigationRequest$ emit at each move.
  • reader.navigation.getNavigation() and position$ follow the scroll.
  • reader.pagination.state.isSettled is false from the first move until the scroll is over.
  • A change of page turn mode during a scroll gives no "user" navigation. The reader lands the navigation of the last move, as a "restoration".

reader.navigation.readingPosition$ does not change: it moves once the scroll is over.

Validation

  • Ran the checks this change touches
  • Added or updated tests
  • Updated the docs in apps/docs, or checked that the documentation still holds

Details

What a scroll event costs

Script time for each scroll event in Chromium. The test makes one scroll event for each frame during 4 s, and each one is a move:

Book Without a navigation at each move With this change Added
Webtoon 0.12 ms 0.20 ms 0.08 ms
Webtoon, CPU slowed 6 times 0.64 ms 1.28 ms 0.64 ms
EPUB that scrolls 0.14 ms 0.25 ms 0.11 ms
EPUB that scrolls, CPU slowed 6 times 0.69 ms 1.45 ms 0.76 ms
  • Chromium reports no layout time and no style time during the scroll, with or without the change.
  • No frame took more than 25 ms in any run. One frame at 60 Hz lasts 16.7 ms.
  • Firefox and WebKit report no script time. With a timer around the call, the navigation of one move took 0.28 ms in Firefox and 0.15 to 0.18 ms in WebKit.
  • The time does not grow with the number of spine items: 0.05 ms in jsdom for 4, 100 and 1000 spine items.

The scroll itself

The same wheel input, 60 moves of 100 px, with and without a navigation at each move, in Chromium, Firefox and WebKit:

  • The scroll ends at the same offset.
  • The page writes the scroll offsets zero times during the scroll.
  • WebKit animates the wheel scroll, and the animation reaches its end.

The end of a scroll

With a navigation at each move, the navigation says where the user is. The end of a scroll no longer finds that place again:

The scroll ends when Before Now
Nothing has moved for 500 ms It navigates to where the element is. The same. A move of less than a pixel is not told, so the element can rest off the last navigation.
The page turn mode changes It navigates to the last place the reader knew. It makes no navigation. The release of the lock lands the navigation of the last move.
Something else navigates It makes no navigation. The same.

The navigation made at a mode change was resolved by the rule for pages that turn. From a quarter of a page scrolled past, that rule took the next page. This bug is on develop too.

The direction of a scroll

A spine item can change height where it is. A book that scrolls then keeps its distance to the top of the item or to its bottom. The direction of the navigation decides which one. It was guessed from the position of the navigation before.

With a navigation at each move, that position is the move before. A last move of one pixel the other way then turned the direction round, and the book jumped by as much as the item grew. The direction now says by which end the reader came into the spine item, and a move inside the item keeps it.

Why not read the scroll element when a page turn is asked for

That design adds no work to a scroll event. Every piece of code that reads the current navigation then has to read the scroll element too. navigation$ and position$ stay on the place from before the scroll. #777 (load while the user scrolls) needs the navigation to follow the scroll.

Evidence

  • Unit: 601 tests pass. With the scroll code of develop, 12 new or changed cases fail, each on the assertion it was written for.
  • Unit, for each fix: with the old direction rule, 2 cases and 4 rows of its table fail. One case fails without the navigation to where the element rests, and one without the rule for a scroll before the first layout.
  • Browser: both new tests fail without their change in Chromium. "Next spine item" goes to spine item 1, not 12. The mode change shows the tenth page, not the ninth.
  • Browser, whole suite: it passes in CI on macOS on the commit before the last fix. With that fix, the 205 tests about scrolling and restoration pass on Linux in Chromium, Firefox and WebKit.
  • Size: 186 source lines changed in 6 files. In code: 49 lines added, 46 removed.

Limits

  • The navigation of a move is as late as the browser's report of that move. A page turn made while the book still moves starts from the last place reported.
  • Each navigation of a move reads the scale of the viewport twice, with getBoundingClientRect. Chromium reports no layout time for it during a scroll.
  • The loader now measures at the instant a scroll is over, 100 ms sooner than before.
  • The direction rule has unit cases only. They drive the real spine and restoration with set sizes. No browser test scrolls up into a spine item that loads.
  • Nothing loads while the user scrolls without a pause: Scroll mode: nothing loads while the user scrolls without a pause #777. This pull request does not change it.

🔍 Self-reviewed with selfcorrect-review
🤖 Made within harness coverage

In a book that scrolls, the reader navigated for a scroll of the
user's once the scroll was over, half a second after its last move.
Until then the current navigation was from before the scroll. A page
turn or a "next spine item" made in that time started from where the
scroll began, so the book moved back.

The scroll now navigates at each move. It still navigates to where
the element is as a layout starts: a browser reports a move a frame
or more after it happens. The reading position still moves once the
scroll is over.

Fixes #779.
`navigation$` and `navigationRequest$` emit at each move of a scroll
of the user's, and pagination is not settled until the scroll is over.
The guides said that a navigation made during a scroll ends it: only
one that the scroll did not make does.
With a navigation at each move, the navigation says where the user is.
The end of a scroll no longer works that out again.

When the page turn mode changes during a scroll, the scroll only ends:
the release of the lock lands the navigation of the last move. It
navigated once more, by the rule for pages that turn, and landed on
the next page from a quarter of a page scrolled past.

When nothing has moved for a while, the scroll still navigates to where
the element rests: a scroll of less than a pixel is not told as a move.

`scrollPositionKnownToReader$` had this one reader, and goes.
When a spine item changes height where it is, a book that scrolls keeps
its distance to the top of the item or to its bottom, by the direction
of the navigation. The direction was guessed from the position of the
navigation before. With a navigation at each move, a last move of one
pixel the other way turned it round, and the book jumped by as much as
the item grew.

In a book that scrolls, the direction now says by which end the reader
came into the spine item: forward from an item before it, backward from
one after it. A position in the same spine item keeps the direction.
…yout

Two cases hold the direction of a scroll: the user comes into a spine
item by one end, the last move goes a pixel the other way, and the item
grows. One case holds a move that the user makes while a layout pass
is in progress: the book ends where that move took it.

The renderer of set sizes can hold the layout of one item.
The scroll makes one when the scrolling has stopped for half a second.
A change of page turn mode or another navigation ends it with none.
…layout

A navigation asked for before the book is first laid out replaces the
one the reader opens with. With a navigation at each move, a scroll of
the user's during that first layout did so too, and the book never
went to its target. A navigation that follows a scroll no longer
replaces it: the book is not laid out yet, so the scroll took the user
to no place in it.
One case for each way a position gets its direction: inside the spine
item of the navigation before, into another spine item, over several,
in none, and where the pages turn, where the rule did not change.

BREAKING CHANGE: `reader.navigation.scrollNavigationController.scrollPositionKnownToReader$` is removed. The end of a scroll of the user's was its one reader and no longer needs it. Commit d8afac2 removed it without this note.
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
prose-reader-docs Skipped Skipped Nov 16, 2026 9:14pm UTC

@mbret
mbret marked this pull request as ready for review November 16, 2026 21:03
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T21:07:21.301410Z 50513bd Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50513bdfe7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

… out

A scroll that began before the first layout kept the lock after the
reader opened at its target. Its last navigation, half a second after
its last move, then replaced that target. A place in a spine item that
was not loaded yet was lost: the reader finds it from the target.

The user's scroll now begins at the first move after the spine items
are first laid out. The navigator no longer needs a rule of its own
for a scroll made before it opens.
@vercel
vercel Bot temporarily deployed to Preview – prose-reader-docs November 16, 2026 21:14 Inactive

This branch was previously deployed

1 inactive deployment
Preview – prose-reader-docs — 803d7b8b Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scroll mode: a page turn or a "next spine item" made right after a scroll starts from where the scroll began

2 participants