Scroll Books shows a book one passage at a time, on a card you swipe through like a social feed. When I built it, I treated splitting the books into passages as an import job. Run a script, upload the files, get back to building the app. This week I found out what that cost me. In a reading app the passages are the product. The rule I'd given the script was to aim for roughly the same length every time, and it was the wrong rule.
210 cards that didn't fit
I'd started to suspect some passages were too long. So I measured all 40,935 passages across the 11 books. I laid each one out on the app's real reader card at seven phone sizes and three text sizes.
At the default text size, 210 passages were taller than the card. On a standard iPhone or a mid-range Android, only The Great Gatsby had any. On an iPhone SE, all 210 overflowed. One text size up, nearly 1,500 did.
210 out of 40,935 sounds like a rounding error. Where they sat made it matter. Moby Dick had 27 of them, and 117 of the 226 people who opened a book in the previous 90 days had opened Moby Dick.
A long passage trapped the swipe
In vertical reading, the default, a passage taller than its card scrolls inside the card. That inner scroll kept every upward swipe for itself, even after the reader reached the end of the text. The page wouldn't turn, however many times you swiped. The only way on was to swipe on the margin or the page number, which nobody would guess. So "too long" wasn't a matter of taste. A reader on a small phone, or with larger text, could get stuck with no visible way forward.
Where the long passages came from
The script aimed for about 400 characters a passage, and its own quality check let a few run past 500. An iPhone SE card holds about 425. When a passage ran long, the script cut it at the comma nearest the middle, so hundreds of cards started mid-sentence. In Moby Dick alone, 475 began with a lower-case letter. The Great Gatsby had been split by paragraph, with cards of up to 1,093 characters.
Measuring length turned up other damage. Pride and Prejudice had lost the first letter of 48 of its 61 chapters ("HE ladies of Longbourn"), because the edition draws each opening capital as an image and the script threw the images away. Beowulf had verse line numbers inside sentences on 539 of its 1,140 cards.
Length should follow the text
The old rule was a target. The new rule is a 380-character ceiling, measured on the card itself, with less on a chapter's opening card. Below the ceiling, the book decides. A short line of dialogue gets a card to itself. A speech stays on the same card as the line that introduces it. Only a sentence longer than the card gets split, at a semicolon or a dash before a comma.
The new chunker reads each Project Gutenberg edition by its structure, so chapters, verse and stage directions survive. A validator fails a book on any defect the audit found. It also warns if passage lengths become too uniform, which is exactly what the old script was aiming for.
AI agents reviewed every re-chunked book over three rounds, and the first round confirmed 69 defects. All 11 books now pass, with no card overflowing on any phone at the default text size.
Moving readers' places mid-book
Re-chunking changes how many cards come before any given sentence. Scroll Books stores reading progress as a card position, so swapping the files as they were would have dropped every reader in the wrong place.
On paper there was a safer route. The app could split long passages into extra pages as it lays out a book, so no saved position ever moves. It's also the only fix that helps at larger text sizes. But an app fix reaches readers after store review, and only once they update. The app fetches a book each time someone opens it, so a new file reaches readers as soon as the server's cache refreshes.
So I'm doing both. On Thursday night all 11 re-chunked books went live, with a script that moved each saved position to the card holding the same words. It mapped all 353 reading positions, and 311 of them had to move. There's a backup of every position and a rollback script if anything looks wrong.
The remap also found something I wasn't looking for. Six saved passages had been pointing at the wrong card since I re-uploaded books in March and May. I'd broken them myself and never noticed. They now point at their own words.
The app fix lets a swipe carry on past the end of a long card and turn the page. It works on the simulator and ships in the next release.
The text is the product
I'd spent months on the app and treated the books as content that sits behind it. Nobody opens Scroll Books to admire the swipe. They open it to read Moby Dick. For months my script had been cutting Melville off at the nearest comma, and on a small phone the app could leave a reader stuck on a page.
A passage should be as long as the book needs, and never longer than the card can show.