Persistent per-book setting from a scripted EPUB in calibre viewer

[lvbruessem]

EPUB author API for a persistent per-book preference in the desktop viewer?

Question

We are preparing an offline educational EPUB with an in-book switch between two terminology variants. The requirement is to preserve the selected variant across XHTML/spine documents and a complete desktop-reader restart, without changing the user's general reader settings.

Is there a supported public API or viewer extension point that an EPUB may use to read and write one small, book-scoped persistent preference in stock calibre? I have not found one in the viewer, plugin, URL-scheme or command-line documentation. Please correct this if I have missed an interface or configuration option.

Reproduction and observed versions

The attached neutral two-page EPUB is an isolated reproducer, not the textbook. It has no fonts, private content, network requests, external file access or calls to calibre internals. It reads its own localStorage key on startup and writes only after an explicit button click; it never writes a default on load.

Open PublicationPreference_A1_Minimal_v1_0_2026-09-23.epub with a fresh/separate reader profile.

Click Save B and confirm Stored choice: B.

Follow Open page 2 and confirm B is still present.

Quit the complete reader normally; verify its process ended.

Reopen the identical file using the same reader profile, without clearing reader data.

Observed in native Linux x86_64 applications, X11/xcb with Xvfb/Openbox and software display:

Reader

After page change

After complete restart

calibre 9.13.0 official Linux binary

B

EMPTY/null; last page still restored

Thorium 3.5.1 Linux

B

B

The EPUB passes EPUBCheck 5.3.0 with zero errors/warnings. SHA-256: 9ff8c572e258f8a4e5db43321394a14426f26823d179202c03 3902c78e53f58a. This minimal test establishes the storage behavior, not full fixed-layout or accessibility compatibility. Windows has not been retested with this reproducer.

Read-only inspection of the supplied calibre 9.13.0 application points to an unnamed/off-the-record WebEngine profile. A separate earlier test of the same bundled Qt version retained a value using a named profile. I understand that this does not justify blindly making the reader's shared publication origin persistent.

Narrow integration question

The viewer has its own durable settings path, including set_local_storage / native preferences. I am not treating those private method names as an EPUB API, and have not called them from book content or weakened reader permissions. User styles/saved reading profiles also retain a choice, but selecting a reader profile is a different interaction from the in-book switch.

If no supported book-facing channel currently exists:

Is this an intentional restriction for EPUB-authored preferences, or a feature that could be considered?

Would a small opt-in per-publication preference service be acceptable, and which supported extension point or upstream design should be used? It should isolate books, enforce limits, report failed writes, and allow users to clear the state. It need not grant general file access, expose reader-global settings, or make arbitrary web storage persistent.

How should that service identify a book independently of a self-asserted identifier in untrusted content, including reimports/updates?

This is an architecture/support inquiry, not a claim that calibre violates EPUB requirements, and not a request for a project-specific fork. A pointer to an existing supported route, or a clear statement of the current extension policy, would determine the next implementation step.

References consulted: https://manual.calibre-ebook.com/viewer.html ; https://manual.calibre-ebook.com/plugins.html ; https://manual.calibre-ebook.com/url_scheme.html ; https://manual.calibre-ebook.com/develop.html .

[kovidgoyal]

There is none and as far as I know, there is no such feature mandated by the spec. That said I am not opposed to adding one, in principle, at least localStorage if not IndexedDB.