Changes from KOReader and ZenOS

GZreader is a fork of KOReader (currently v2026.07.1) with ZenOS (currently 4.3.2) as its interface. Most of what it adds is its own plugin, gzreader.koplugin; where it had to change KOReader or ZenOS, the changes are marked in the code and checked by a test (tools/gzreader/tests/keeps.py), so an upstream update can't drop them unnoticed. Upstream updates are merged with tools/gzreader/upstream.sh.

Compared with KOReader

Left out (What's in GZreader): all bundled plugins except Cover browser, Statistics and Auto suspend (KOReader's own progress sync, OPDS, news downloader, SSH, terminal and the rest); KOReader's OTA updater; the CJK fallback font; UI translations; the first-run quickstart document.

Added:

• Grimmory: library browser, background downloads, sync of position, bookmarks, highlights, notes, ratings and reading sessions through Grimmory's own API (not its KOReader-compatible endpoint), audiobooks. → Grimmory library, Grimmory sync
• The setup page served by the device, copying connections between devices, sync with a computer for Kindles without Wi‑Fi. → Setup page and connections, Sync with a computer
• Notes (Memos), Calendar (links and CalDAV), Music (Plex), read aloud with the Kindle's own voice.
• Updates from GitHub (its own updater), debug reports (only if you choose) and diagnostics. → Updates, Privacy and diagnostics
• The quick panel, replacing KOReader's top and bottom menus and ZenOS's touch menu on every device. → Using GZreader
• An English dictionary.

Changed in KOReader's own code:

Where	What
Kindle 2, DX, 3, 4 drawing (frontend/device/kindle/shadowfb.lua, device.lua)	A shadow screen: KOReader draws with its fast C blitter into an 8-bit buffer that's packed into the 4-bit (or inverted 8-bit) framebuffer before each refresh; night mode is done while packing. → Performance
Kindle start script (platform/kindle/koreader.sh)	Restarts, stepping aside for the Kindle's USB drive and coming back after it ("Connect to computer"), the Kindle 2/DX's framework for USB drive mode
Nook devices (frontend/device/nook/)	The Nook 1st Edition's e-ink page (refreshed through the kernel without a flash) and colour touchscreen (controls, reading info, a keyboard), the Simple Touch's e-ink waveforms and touch; the Nook start script and launcher (platform/nook/). → Nook 1st Edition
Loading (frontend/gzbytecode.lua, luasettings.lua)	A bytecode cache for source installs; settings files are only written when they changed
Fonts (frontend/ui/font.lua)	Missing fallback fonts (the removed CJK one) are dropped at start instead of failing on every glyph
Book layout (frontend/document/credocument.lua)	A bigger crengine cache (256 MB instead of 64)
Sleep screen (frontend/ui/screensaver.lua)	GZreader's own sleep screen: the book's cover while reading and a picture elsewhere, whatever sleep screen was saved before (frontend/gzsleepmode.lua); "Custom image or cover" shows the book's cover while reading and the image elsewhere; Scale cover to fill screen (proportions kept, edges cut off; frontend/gzsleepfit.lua); with an Immich album chosen, a picture comes from its pictures first, then the folders (gzsleepmode.pictureDirs)
Menus (frontend/ui/widget/touchmenu.lua, menu orders)	Letter keys in KOReader's menus; GZreader's items in place of removed plugins'
Home folder (frontend/apps/filemanager/)	No Home folder settings (Set, Shorten, Lock) in the file manager's menu and no "Set as HOME folder" buttons: the home folder is always the GZreader folder
Back key (readerback.lua), translations (gettext.lua), plugin loading	Small fixes for the trimmed build

Compared with ZenOS

GZreader keeps ZenOS's Home, tabs, library views, settings and setup guide, and changes:

• Keys: letter keys in every list and dialog (__ZEN_DIALOG_SHORTCUTS, the context menu), tab keys (Z, X, C, V, B) on keyboard Kindles, the 5-way on the Kindle 4. ZenOS was made for touch.
• The quick panel instead of ZenOS's touch menu (its Zen Mode button and tabs), on every device; ZenOS's first-run menu tour is replaced by one of the quick panel, which closes it before the page browser tip.
• Home: a bookshelf view (books on shelves, audiobooks as a cassette walkman, music as a CD player), Grimmory reading stats on a notebook page in place of ZenOS's local reading stats widget (no longer offered), two shelves on the DX's taller screen; font sizes in Home widgets and the end-of-book page aren't scaled twice.
• Tabs: Catalog (Grimmory's books and audiobooks and Plex music, a page each; the Grimmory tab before 1.27.x), Notes (in Favorites' place) and Calendar, Music and Audiobooks on request.
• The book menu: Add to shelf and Remove from shelf (your Grimmory shelves, kept on the Kindle, changes sent over Wi‑Fi or by the sync page) instead of Add to collection, also for several selected books; no Add to collection anywhere.
• The setup guide: shorter (fewer pages, GZreader's reading defaults set on a first setup), starting with Set up from your browser, ending with whether to send debug reports.
• Settings → Interface → Quick panel: which tiles the quick panel shows, in place of ZenOS's Controls and Launcher (they set up the touch menu GZreader replaces).
• Zen mode is always on (ZenOS's own tabs only): there's no Zen mode switch in Settings → Interface, and it's turned back on if it was off.
• The update screen: GZreader's version and what's new in it, after every GZreader update (ZenOS showed its own version and list, only when ZenOS changed).
• Settings: GZreader's sections in ZenOS's settings (Connections: Grimmory, Memos, Calendar, Plex, copying connections, sync through a computer) and its items in ZenOS's own sections (General: Wi‑Fi as On, Off or Auto in place of ZenOS's switch, Updates, Screen with the flash settings, Audio; Interface: Pre-size covers and the quick panel; About: Send debug reports automatically and Advanced, with the diagnostic log at its top). ZenOS's Library section (the Downloads tab's settings: Appearance, Folders, Books, Context menu) is in Settings → Home, after Home's own rows; its Folders has no Home folder menu (the home folder is always the GZreader folder).
• Covers: pre-sized and cached on disk, made in a background process. → Performance
• Not loaded: ZenOS's own updater (GZreader's replaces it; a small stand-in answers ZenOS) and its Rakuyomi manga integration unless that plugin is installed. → Performance
• Immich (Photos): Settings → Connections has Immich, and Settings → Interface → Wallpaper has Picture from Immich (a picture from your Immich album behind Home and the tabs, another one when new pictures come; common/gz_immich_wallpaper.lua). → Home and bookshelves
• The reader's top status bar (Settings → Reader → Appearance → Top status bar: the clock, by default) stays on screen while the layout menu (the quick panel's Layout) is open and after it closes; ZenOS drew it only while nothing else was open over the book, so it went missing until the next page turn.
• Wi‑Fi in the status bars (Home's and a book's top bar): an A after the Wi‑Fi icon while Wi‑Fi is on Auto (common/gz_wifi_icon.lua); the icon itself still shows on or off.
• Settings, rearranged: every row has an icon. General has Time and date (Time zone first), Language and Storage (what's on the Kindle: each part with its size, and an arrow into the biggest of each), which were in About → Device or at the top of Settings. Sleep → Wallpaper shows the sleep screens as tiles with previews, its other settings under Wallpaper options; no custom image, no sleep-screen presets. General comes first in Settings. General → Screen is KOReader's Screen menu (moved there from KOReader's settings), and its E-ink settings hold every setting about when the screen flashes: KOReader's Full refresh rate, then GZreader's Flash on every page turn, Flash when the screen changes and Partial pages refresh (they were in Reader → Appearance and Advanced, then General → Screen refresh). ZenOS's Flash on every CBZ page turn is gone: KOReader's Always flash on pages with images covers comics.
• Fewer settings that don't apply: Settings → About starts with GZreader's version ("Built on ZenOS … and KOReader …" under it) and its Report a bug sends to GZreader's developer, not ZenOS's issue tracker. Advanced is under About (Settings → About → Advanced), with GZreader's diagnostic log items at the top and KOReader settings (KOReader's whole menu) at the end, and no Debug logging, Clear all gestures, Plugin management, Patch management, Extract metadata, Show hidden files or Allow dragging reader modals (a saved tick of the last two is turned off once). Where GZreader shows KOReader's rows outside About → Advanced → KOReader settings (General → Screen, the KOReader menu a bottom swipe can open), it leaves out the File browser menu (Downloads' own Sort and Filter set the same things), no Tools → Reading statistics (the statistics are still kept), and no Plugin management, Patch management, Developer options, file browser Display mode or Start with, Wi‑Fi actions, Restore Wi‑Fi or Disable Wi‑Fi connection when inactive, second Grimmory menu, Disable double tap (GZreader has no double-tap actions; a saved untick is cleared once), Book metadata location and Move book metadata (GZreader looks for a book's metadata next to it), or Help → Report a bug and Disable external plugins (GZreader's own plugins count as external). No Manga, News or Calibre Search tabs.
• Nooks: paths for a Nook's microSD card, Bluetooth stubbed out, Wi‑Fi switching adapted.
• Settings → Reader in six rows: Gestures and controls (Bottom swipe gesture, Reader controls, Page Browser) and Notes and footnotes (Annotation viewer, Footnotes and pinned pages) are submenus; ZenOS has the five side by side. The Settings buttons in the page browser, the annotation viewer and the footnotes drawer open their page inside the group.
• No Extras section in Settings: its Schedules and Sleep are in General and Custom icons in Interface (as in ZenOS); the rest (Stats tab widgets, ZenPM, Rakuyomi, Zen Search, Lockdown mode, Zen Keyboard) isn't offered, and keeps its default or what was set before.
• GZreader's menus look like ZenOS's Settings: the Calendar and Notes tabs' connect lists, Plex's sign-in and the Music list, Downloads, the sync queue, copying from another GZreader, the Notes filters, the font list and Add to shelf have ZenOS's rows: an icon on the left, an arrow on the right of each row that does something, ZenOS's spacing, and short labels (longer explanations behind an About … row). Lists of books, albums and tracks keep their own look.
• No Metadata menu in Settings → Home → Books (ZenOS's online sources for its metadata editor): a download's title, authors and series come from Grimmory. Square cover corners in the Bookshelf view (Rounded cover corners is greyed out there; the other views keep their setting).
• No Double tap on the Kindle 2, 3, DX and 4 (Settings → Home → Books; ZenOS's Double-tap to open a book before 4.3.2): they open books with keys or the 5-way, so there's nothing to tap. The touch Kindles still have it, with Single tap and Double tap under it (what each does to a book: open it, its menu, or nothing).
• Branding: GZreader's name and logo; a "GZreader" item on the touch Kindles' home screen instead of ZenOS's.
• No KOReader section in Settings: KOReader's whole menu, nothing left out, is Settings → About → Advanced → KOReader settings (for whatever is open: Home or the book). What GZreader has elsewhere is there too: Language, Time and date, Sleep screen, Autosuspend timeout, Wi‑Fi connection, HTTP proxy and Network info (Settings → General, the last three in Wi‑Fi), History, Favorites and Collections (tabs), End of document action (Reader → End of book), Night mode, Rotation and Exit (quick panel tiles), Activate menu (Interface → Quick panel), the Screen menu (Settings → General → Screen), Version, About and Quickstart guide (Settings → About).

The full list of changed upstream files is tools/gzreader/tests/keeps.txt in the repository.