v2.4.0: re-ordered downloads take the new order on the next online start

docs-developers/architecture/cross-repo-contract.md

@@ -246,7 +246,9 @@ book is the only additive marker (mirrored as `Book.chapters_source` /
 `ChaptersResponse.chapters_source`, the `ChaptersSource` union): the player's book
 page captions such chapters (an older app shows them as ordinary chapters), and a downloaded book replaces its
 saved chapters with a newer server answer while its audio files are unchanged
-(same paths, order and sizes; `startChapterRefresh`). Podcasts additionally
+(same paths, order and sizes; `startChapterRefresh`). The same files in a new
+order (the server's natural file order, 2.4.0) are taken only by a start that
+loads them that way (`adoptStartedChapters`), never from a background answer. Podcasts additionally
 return `id3_chap` from the server's CHAP attachments; the player (2.2.0 and
 later, first released in 2.4.0) captions it "Chapters from the episode file". See [podcasts](#17-podcast-shows-feeds-and-client-visibility).
 

docs-developers/frontend/offline.md

@@ -236,6 +236,21 @@ with no network.
   never touched, and a queue already playing keeps its chapters until the book
   is next started. Before this, a downloaded copy kept the chapters it was
   downloaded with.
+- **A new file order** (server 2.4.0 plays a folder book's files in natural
+  order, `2-` before `10-`, and re-indexes a book stored in byte order): the
+  same files in another order are **not** taken from a background answer
+  (`refreshedChapters` returns null for them), because JS sees only the queue
+  it loaded, not a book the Android service or a Cast receiver holds before
+  `adoptLoaded` maps the engine's track index through the manifest. They are
+  taken only by a start that loads the engine in the new order:
+  `adoptStartedChapters`, called by `playBook` once its load landed and it
+  still owns the engine, replaces `manifest.chapters` (same set of paths, same
+  sizes where both answers know them) and saves the registry at once. The
+  chapters carry the play order; `manifest.files` keeps the order the download
+  wrote it in, since a file's index there is its name on disk. An offline
+  start, Android's no-JS car start and `adoptLoaded` keep the manifest's order
+  until an online start plays the new one. A place saved on the old timeline
+  reads as moved once the new order is taken (nothing remaps it).
 
 ### Hydrate and the iOS container-move problem
 

docs-developers/server/scanner.md

@@ -426,8 +426,9 @@ Before 2.4.0 a folder book's files played in byte order (`os.ReadDir`'s), so
 scan although no file changed: `Signature.FileOrder` (`catalog.FileOrderKey`,
 an FNV-64a of the stored file paths in order) differs from the new order's.
 Nothing remaps a listener's place: a whole-book position on such a book can
-land elsewhere in the story (offline copies take the new chapters through the
-player's `refreshedChapters`). Move detection still finds such a book by the
+land elsewhere in the story (an offline copy takes the new order and chapters
+the next time it is started online, the player's `adoptStartedChapters`; until
+then it plays the order it was downloaded in). Move detection still finds such a book by the
 file byte order put first (`byteFirstFingerprint`, in `detectMoves` and
 `IndexMoved`), and a Bridge `chapters.json` made while it played in byte order
 still applies, its chapters moved with their files (`movedChapters`, see

docs-users/listening/offline-downloads.md

@@ -86,6 +86,7 @@ Honestly? Barely at all - that's the point:
 - A downloaded book **plays from local files**, so it starts instantly and never buffers, whether or not the server is reachable.
 - Chapters, the sleep timer, speed, bookmarks, and notes all work the same.
 - **Chapters stay up to date.** If a book's chapters change on the server after you downloaded it (your admin switched it to the [community's chapters](book-page.md#chapters), or back, or a rescan found new ones), the downloaded copy picks up the new chapters the next time the app loads that book's chapters while online, as long as its audio files are the same. A book that is already playing keeps its chapters until you next start it. The audio on your device is never re-downloaded for this.
+- **A new file order.** If your server now plays a downloaded book's files in a different order (from 2.4.0 a file named "2" plays before one named "10"), the downloaded copy takes the new order the next time you start the book while online. Until then, and whenever you start it offline, it plays in the order it was downloaded in. Your place in such a book can move once, because the new order changes where each part sits in the book.
 - Your listening progress is saved on the device while you're offline and **synced to the server automatically** the next time the app can reach it - so even offline listening ends up on your other devices' *Continue listening* shelf.
 - The book's page still opens offline for downloaded books, community notes and all ([below](#community-notes-offline)), and its **Details** tab says the book **Plays from this device**.