Faster Update Book; update only when a tool needs it (BL-16893) by hatton · Pull Request #8407 · BloomBooks/BloomDesktop

hatton · 2026-09-25T17:16:23Z

Why a book's pages need updating

Bloom's editing code fixes up and measures each page when the page is laid out on screen:

It converts old-style pictures into the form the current version uses.
It records how much of the page each picture occupies. The AI image editor relies on this to choose sizes.
It records the size of each picture's drawing area.

Pages that nobody opens in the Edit tab never get this work, so a book whose pages were never opened in this version is missing it.

The measurements also depend on the shape of the page. When the page size or orientation changes, or the theme or margins change, the numbers recorded on every page are wrong until the pages are measured again.

So Bloom has to update every page of a book at certain moments. That work should be fast, and it should happen at the moment something needs it, without the user having to ask.

How Bloom knows a book needs updating

Each book carries a pageLayoutUpdateLevel value in its HTML.

Updated: once every page has been updated, Bloom writes the current level. A book made from one of Bloom's own templates, or from one of the Sample Shells that ship with Bloom, starts at that level.
Needs updating: Bloom sets the value to 0 when any of these happens:
- the page size or orientation changes;
- Bloom has to change the page size because the book's branding or front and back matter does not support it;
- any Appearance setting changes in Book Settings;
- a spreadsheet is imported, since the import makes and fills pages without showing them.

A book with no value, or with a value below the current level, needs its pages updated.

When the update happens

Changing the page size or the theme does not start the update. Bloom waits until something needs the whole book:

The AI image editor updates the pages before it opens.
The Publish tab: choosing one of its tools, such as PDF & Print, Web or ePUB, updates the pages first, and the tool opens when that is done. Merely opening the Publish tab does nothing.
Update Book on the book's menu in the Collections tab, and BloomBridge, always update every page.

If a second request arrives while an update is running, it waits for that update to finish.

Making it fast

Bloom updates the pages in a hidden browser. It loads every page into the same browser, so the editing code is prepared once for the whole book instead of once per page. That browser also skips the search for a network proxy, which can stall for several seconds.

On the 19-page The Moon and the Cap, updating takes about 6 seconds. Version6.5 without this change takes about 10.

The progress dialog

The progress bar only moves forward, and it stays full for half a second before the dialog closes. BloomBridge shows the same dialog, with its own sentence.

If the update fails, the dialog turns red and shows the problem, with Report and Close buttons. When the user clicks Close, the tool they chose opens with the book as it is. The book still needs updating, so the next Publish tool or AI image editor launch tries again.

Case	Screenshot
BloomBridge
Update Book, from the book's menu
Choosing Publish > Web after a page size change
A failed update (simulated)

The E2E tests for this behavior are in #8412. They are stacked on this PR because the E2E suite exists only on master.

Ref: https://issues.bloomlibrary.org/youtrack/issue/BL-16893

🤖 Generated with Claude Code

This change is

Devin review

greptile-apps · 2026-09-25T17:22:03Z

[Medium risk] Refactors book update logic to defer page layout work.

The PR does not appear safe to merge until newly inserted pages remain eligible for updating and Publish selection preserves the latest choice.

Findings

Inserted pages skip updating ▶
Older reply overrides tool choice ▶

Summary

The PR moves page-layout updating to the point where a Publish tool or the AI Image Editor needs it, uses a reusable off-screen browser to speed up the pass, and adds book-wide update metadata and progress handling. The update decision can miss newly inserted pages, and rapid Publish-tool selections can open an earlier choice.

_{Reviews (2) · Last reviewed commit: "Faster Update Book; update only when a t..."}

hatton · 2026-09-25T17:27:42Z

[Claude Opus 5.5 from Hatton's machine during preflight] Consulted Devin on 2026-09-25 17:32 UTC up to commit 19643ca. First review (cd9613d): 3 bugs and 1 flag, all mirrored as review threads above. The duplicate-close and held-tool bugs were fixed in 19643ca and Devin now marks both resolved; the overlapping-caller bug and the localization flag were answered as not issues. Re-review of 19643ca found nothing new.

hatton · 2026-09-25T20:57:10Z

[Claude Opus 5.5 from Hatton's machine during preflight]

Consulted Devin on this PR up to d7b9b2d5ea. Its earlier findings are all answered in their threads. It raised two new Investigate flags:

The description said the book's due-check still compared the page size. The description Devin read was stale; it has been updated. Answered and resolved in its thread.
A localization entry was deleted from BloomMediumPriority.xlf. Not part of this PR: the diff against Version6.5 touches nothing under DistFiles, so GitHub would not take an inline comment on that file. The entry (BookProcessor.AutoUpdateExplanation) was removed by edaca2f, which is already on Version6.5, and it was marked translate="no", so it was never sent to Crowdin and no translations depended on it.

hatton

@hatton reviewed 20 files and all commit messages, and made 1 comment.
Reviewable status: 0 of 31 files reviewed, 8 unresolved discussions.

hatton

@hatton reviewed 9 files.
Reviewable status: 0 of 31 files reviewed, 8 unresolved discussions.

hatton

@hatton partially reviewed 17 files.
Reviewable status: 0 of 34 files reviewed, 8 unresolved discussions.

Bloom's editing code fixes up and measures each page when it lays the page out. Pages nobody opens never get that work, and a new page size, orientation, theme or margins leaves the recorded measurements wrong. So Bloom updates every page of a book at certain moments. - The book records a pageLayoutUpdateLevel meta. The update, and making a book from Bloom's own templates or Sample Shells, set it to the current level (BookStorage.kPageLayoutUpdateLevel). A page size or orientation change, a size forced by the branding or xmatter, and any Appearance change in Book Settings set it to 0. It replaces browserMaintenanceLevel and browserMaintenanceLayout, which the update removes. The shipped Sample Shells carry it. - The update runs when something needs the whole book: launching the AI image editor, or choosing a Publish tool, which opens once the update is done. Changing the page size no longer runs it. Update Book and BloomBridge always update every page. A second request while an update runs waits for it. - The update loads every page into one off-screen browser, which keeps the compiled editing code, and that browser skips the proxy lookup, since its pages only contact Bloom's own server. The Moon and the Cap: about 10 s to about 6 s. - The progress bar only moves forward and shows full for half a second before closing. BloomBridge's process-book uses the same dialog in place of ExternalBusyOverlay, with its replies and status unchanged. After a failure the dialog shows only the problem; Close opens the chosen tool, and the next attempt tries again. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

greptile-apps · 2026-09-25T22:59:41Z

+                                    (result) => {
+                                        if (result.data.pagesBeingUpdated) {
+                                            return;
+                                        }
+                                        toolWaitingForPages.current = undefined;
+                                        setTabIndex(newIndex);


Older reply overrides tool choice If a user selects two Publish tools before both requests finish, the first request's reply can arrive after the second selection. This callback then clears the shared pending choice and opens the tool from the first click, overriding the user's latest choice. On the no-update path, the server sends pagesUpToDate before its HTTP reply, so that event does not prevent this ordering.

andrew-polk

@andrew-polk partially reviewed 34 files and all commit messages, made 2 comments, and resolved 14 discussions.
Reviewable status: all files reviewed, 3 unresolved discussions (waiting on hatton).

…6893) The import makes pages and puts pictures on them without ever showing them in the Edit tab, so they lack what the editing code records when it lays a page out. It now sets pageLayoutUpdateLevel to 0, so the next Publish tool or AI image editor launch updates every page. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

andrew-polk

@andrew-polk reviewed 2 files and all commit messages, and resolved 1 discussion.
Reviewable status: all files reviewed, 2 unresolved discussions (waiting on hatton).

greptile-apps Bot reviewed Sep 25, 2026

View reviewed changes

Comment thread src/BloomBrowserUI/bookEdit/js/bloomEditing.ts Outdated

Comment thread src/BloomExe/Book/BookProcessor.cs Outdated