feat: release YACP 1.5.0

Author: Sichroteph

CHANGELOG.md

@@ -1,3 +1,213 @@
+## [v1.5.0-yacp] - 2026-08-03
+
+### Added
+
+- Added a dedicated Sleep Images web page for managing global sleep images and the gallery attached to one selected
+  book without exposing the hidden SD-card folders.
+- Added per-book image galleries. Compatible gallery BMPs can be opened from the reader menu and used as sleep images
+  when sleep starts from that book.
+- Added browser-side image preparation to File Transfer, with visual crop selection, X3/X4 target sizing, four-level
+  grayscale preview, threshold tuning, and reader-ready BMP generation before upload.
+- Added `Previous Page` as an optional side-button long-press action in EPUB, TXT, and XTC readers.
+
+### Changed
+
+- Sleep-image rendering now analyzes each image's tonal range before dithering, preserving substantially more useful
+  highlight and midtone detail on the four-level e-ink output.
+- Rendered grayscale sleep-image planes are cached on the SD card and reused while the source image remains unchanged.
+- Per-book sleep images take priority in Cover, Custom, and Cover/Custom modes, rotate randomly, and avoid immediately
+  repeating the previous image when several prepared BMPs are available.
+- Waking after an image-based sleep screen restores the pre-sleep framebuffer instead of showing the normal boot
+  splash. This implementation was inspired by CrossPoint PR #2731 by Marek Vesely (`notmarek`).
+- Finished Books now groups completed titles by finish month and shows each month's book count, reading time, titles,
+  and authors.
+
+### Removed
+
+- Removed the temporary on-device grayscale comparator and browser sorting tools used while validating the new image
+  pipeline.
+
+### Fixed
+
+- Reaching the real EPUB or XTC ending now completes the book automatically, while leaving from the final page or a
+  rounded 100 percent asks for confirmation.
+- First completion dates remain stable across rereads, pending Reading Achievement screens survive activity replacement
+  or restart, and legacy Finished Books entries reconcile their dates and authors from persistent statistics.
+- Sleep-image management loads gallery data and previews only when requested, reducing SD-card contention during file
+  uploads.
+- File Transfer keeps the selected book-gallery destination explicit throughout image preparation, reducing accidental
+  uploads to the current folder.
+- Quick Resume back into the reader restores the loading-dot indicator before live battery status replaces it.
+
+## [v1.4.0-yacp.226] - 2026-08-02
+
+### Changed
+
+- Simplified the Sleep Images page around default images and one selected book, with contextual add actions instead
+  of technical folder shortcuts.
+- Adding an image from the Sleep Images page now opens the existing image preparation workflow with the correct
+  destination and selected book already set, then returns to Sleep Images after a successful upload.
+
+## [v1.4.0-yacp.225] - 2026-08-02
+
+### Added
+
+- Added a dedicated Sleep Images web page for global sleep images and per-book galleries. File Manager no longer loads
+  sleep-image lists when managing regular files.
+- File Transfer can still upload directly into the hidden `/.sleep` folder when that folder is opened explicitly.
+
+### Removed
+
+- Removed the temporary sleep-image test UI and browser sorting page used during grayscale tuning.
+
+### Fixed
+
+- Sleep-image management now loads gallery contents and image previews only on demand, reducing SD-card contention
+  during uploads.
+- Quick Resume back into the reader now shows the small loading-dot indicator in the bottom-left corner again before
+  the live battery status replaces it.
+- Per-book gallery sleep-image rotation now avoids immediately repeating the previously used BMP when several
+  prepared images are available for the book.
+
+## [v1.4.0-yacp.214] - 2026-08-02
+
+### Fixed
+
+- File Transfer now keeps the chosen book-gallery destination clearer and less fragile, so prepared BMP uploads are
+  less likely to be sent to the current folder by mistake.
+
+## [v1.4.0-yacp.211] - 2026-08-02
+
+### Fixed
+
+- Per-book gallery sleep-image rotation now uses the ESP32 hardware RNG, avoiding the same first image after each
+  deep-sleep boot.
+
+## [v1.4.0-yacp.210] - 2026-08-02
+
+### Fixed
+
+- Per-book gallery sleep images now choose randomly among the book's prepared BMPs instead of always using the first
+  uploaded image.
+
+## [v1.4.0-yacp.209] - 2026-08-02
+
+### Changed
+
+- Book gallery BMPs now take priority as the sleep image when sleep starts from that book in Cover, Custom, or
+  Cover/Custom sleep modes.
+
+## [v1.4.0-yacp.208] - 2026-08-02
+
+### Added
+
+- File Transfer's e-reader image preparation now exposes three grayscale threshold sliders, so uploads can be tuned
+  before generating the 2-bit BMP used on the reader.
+
+## [v1.4.0-yacp.206] - 2026-08-02
+
+### Added
+
+- File Transfer can now attach images to a per-book gallery. The reader menu shows `Book Gallery` only for books with
+  compatible gallery images, and opens the existing image viewer for that book's gallery.
+- File Transfer can now prepare uploaded images for the e-reader in the browser, with crop selection, X3/X4 target
+  sizing, four-level grayscale dithering, and 2-bit BMP output before upload.
+
+### Changed
+
+- Dropping or selecting images in File Transfer now uploads the originals by default; e-reader crop/resize preparation
+  is an explicit opt-in choice.
+- Quick resume now shows a wake-up label over the restored sleep frame only when waking to Home, keeping direct
+  reader resumes visually quiet.
+
+## [v1.4.0-yacp.200] - 2026-08-02
+
+### Changed
+
+- Custom BMP sleep images now use adaptive tonal analysis before dithering, preserving more useful detail while
+  keeping the corrected four-level grayscale mapping.
+- Rendered custom sleep-image grayscale planes are cached on the SD card and reused when the source image has not
+  changed.
+- Added a temporary main-menu diagnostic screen for comparing legacy and adaptive sleep-image grayscale rendering
+  directly on device, with a taller label badge and Confirm mapped to the next image.
+- Fixed the temporary sleep-image diagnostic so it uses the same white BW base and crop ratios as the real sleep-image
+  renderer, and keeps the label out of the grayscale planes.
+- The temporary sleep-image diagnostic now uses English overlay labels, `Before` and `After`, regardless of UI
+  language.
+- The temporary sleep-image diagnostic now uses Left/Right for the linear Before/After sequence, while Confirm jumps
+  to the next image's `Before` frame.
+- Added a lightweight web Sleep Images page for previewing sleep-screen images and sorting them into `keep` or
+  `reject` folders from the browser.
+
+## [v1.4.0-yacp.185] - 2026-08-01
+
+### Changed
+
+- Removed the temporary real-device sleep-image comparison mode from the firmware build.
+
+## [v1.4.0-yacp.184] - 2026-08-01
+
+### Changed
+
+- The temporary sleep-image grayscale comparison build now opens the real-device comparator automatically at boot,
+  without requiring a button combo.
+
+## [v1.4.0-yacp.183] - 2026-08-01
+
+### Added
+
+- Added a hidden real-device diagnostic mode to compare the legacy and corrected sleep-image grayscale mappings on
+  every BMP in `/.sleep`.
+
+## [v1.4.0-yacp.181] - 2026-08-01
+
+### Fixed
+
+- Waking from image-based sleep screens to Home now reuses the wake cleanup refresh and avoids a second strong Home
+  refresh.
+
+## [v1.4.0-yacp.180] - 2026-08-01
+
+### Fixed
+
+- Waking from image-based sleep screens now uses the wake half-refresh as the cleanup pass and avoids a second half
+  refresh when the reader page opens.
+
+## [v1.4.0-yacp.179] - 2026-08-01
+
+### Changed
+
+- Rebuilt the Tiny firmware with the remote File Transfer firmware-install endpoint and the current sleep-cover
+  grayscale correction.
+
+## [v1.4.0-yacp.178] - 2026-08-01
+
+### Fixed
+
+- Sleep cover grayscale generation now keeps more midtone detail instead of pushing many light-mid tones to white.
+
+## [v1.4.0-yacp.176] - 2026-08-01
+
+### Added
+
+- File Transfer now exposes a remote firmware install endpoint so a developer can upload a `.bin` over HTTP, trigger
+  validation and OTA flashing from the computer, and let the reader restart without navigating the firmware menu.
+
+## [v1.4.0-yacp.174] - 2026-08-01
+
+### Changed
+
+- Sleep wake now skips the boot splash after every sleep screen mode by restoring the pre-sleep frame first; X3 keeps
+  the no-flash wake indicator only after true Quick Resume sleep screens and uses a half refresh after image-based
+  sleep screens.
+
+## [v1.4.0-yacp.168] - 2026-08-01
+
+### Changed
+
+- Finished Books now groups completed titles by finish month, showing each month's book count, total reading time,
+  titles, and authors instead of exact per-book date timelines.
+
 ## [v1.4.0-yacp.167] - 2026-08-01
 
 ### Added

README.md

@@ -26,19 +26,39 @@ YACP is expected to use less energy and perform less incidental work than its ba
 measured battery-life claim yet. Long-running current analysis continues so future choices can be based on repeatable
 hardware measurements rather than optimistic estimates.
 
-## What is new in 1.4.0-yacp.167
+## What is new in 1.5.0-yacp
 
-- **Reliable book completion:** reaching the real EPUB or XTC ending completes the book automatically, while leaving
-  from its final page or a rounded 100% asks for confirmation. The first completion date remains stable across rereads.
-- **Dated Finished Books timelines:** every known reading span now shows its start date, finish date, both years, and
-  active reading time. Opening Reading Stats repairs older retained entries from the book's persistent dates.
-- **Safer reading start dates:** a short preview no longer starts a book's timeline; YACP waits for meaningful active
-  reading and forward progress.
-- **Previous Page on a side-button hold:** the optional long-press action turns back exactly one page in EPUB, TXT,
-  and XTC while preserving the side button's normal short-press direction.
+This release is centered on one visible e-ink improvement: a new adaptive grayscale path for sleep images. The previous
+mapping could wash out highlights or collapse useful midtones. YACP now analyzes the image's tonal range before
+dithering it to the four levels available on the panel.
 
-This is a focused reliability release built on the no-flash screen maintenance, Reading Achievement, Finished Books,
-and Home improvements introduced in `.155`. See the [changelog](CHANGELOG.md) for the complete inventory.
+<p align="center">
+  <img src="https://github.com/Sichroteph/YACP/releases/download/v1.5.0-yacp/YACP-sleep-image-before-after.jpg"
+       alt="Four real-device before and after comparisons of YACP adaptive grayscale sleep-image rendering"
+       width="760">
+  <br>
+  <sub>The same source images rendered with the previous and adaptive mappings on a real X3.</sub>
+</p>
+
+- **Adaptive grayscale rendering:** custom and per-book sleep images preserve more highlight and midtone detail, while
+  rendered grayscale planes are cached on the SD card and reused when the source is unchanged.
+- **Per-book sleep-image galleries:** prepared images can be attached to a book, selected when sleep starts from that
+  book, rotated randomly, and kept from repeating immediately.
+- **Image preparation in the browser:** File Transfer can crop, resize for X3 or X4, preview four-level grayscale,
+  adjust the thresholds, and upload the resulting BMP without a separate conversion tool.
+- **A focused Sleep Images page:** global images and one selected book gallery can be viewed and updated without
+  navigating the hidden storage layout.
+- **Cleaner sleep and wake:** image-based sleep screens wake without the normal boot splash; direct Quick Resume into
+  the reader remains visually quiet.
+- **Reading reliability and ergonomics:** finished books are grouped by month, completion data survives rereads more
+  reliably, and a side-button hold can optionally turn back one page.
+
+[Watch the complete sleep-image workflow](https://github.com/Sichroteph/YACP/releases/download/v1.5.0-yacp/YACP-sleep-images-overview.mp4)
+from the phone interface to the resulting Alice in Wonderland and Jurassic Park sleep screens on the reader.
+
+This builds on earlier YACP work such as X3 no-flash screen maintenance and seamless Quick Resume. When a technical
+finding appears broadly useful, I try to submit it to CrossPoint as a focused PR so its maintainers can review and,
+if they wish, adopt it upstream. See the [changelog](CHANGELOG.md) for the complete inventory.
 
 ## Direction
 
@@ -161,10 +181,10 @@ book. The first completion date stays unchanged when the book is reopened or rer
 
 Finishing a new book opens a Reading Achievement screen with its reading time, sessions, average session, favorite
 reading period, reading span, completed-book count, and total reading time on the device. The following Finished Books
-view keeps the 32 most recently completed books in a bounded SD index and presents each known reading span as a compact
-start-to-finish timeline with the year on both dates and the reading time. Existing installations recover completed
-entries from their recent-books list without scanning the entire SD card. Opening Reading Stats also reconciles a
-completed book's persistent dates with its retained entry, so legacy timelines repair themselves without a fake edit.
+view keeps the 32 most recently completed books in a bounded SD index and groups them by finish month, showing each
+month's book count, reading time, titles, and authors. Existing installations recover completed entries from their
+recent-books list without scanning the entire SD card. Opening Reading Stats also reconciles a completed book's
+persistent dates and author with its retained entry, so legacy entries repair themselves without a fake edit.
 
 <table>
   <tr>
@@ -252,9 +272,9 @@ checksums, and applies the [build checklist](BUILD_CHECKLIST.md).
 
 ## Project status
 
-This is not a community project. Issues, Discussions, pull requests, feature requests, support requests, and project
-contact are not accepted. External pull requests are closed automatically. The source is public for inspection and
-forking; maintain a fork if a different direction is needed.
+This remains a personal firmware project rather than a community roadmap. GitHub Issues are open for reproducible bug
+reports, hardware feedback, and focused technical discussion. General support requests, feature voting, and external
+pull requests are not accepted; maintain a fork if a different direction is needed.
 
 Optional financial support does not buy features or influence project decisions:
 [PayPal](https://www.paypal.com/paypalme/ChrJeannette).

docs/data-cache.md

@@ -34,6 +34,7 @@ The main data directory is `.crosspoint` on the SD card. It stores render caches
 ├── clippings/              # EPUB clipping/highlight files, one per book
 ├── home_carousel_cache.bin # Lyra Carousel home-screen snapshot cache
 ├── sleep_frame.bin         # Temporary sleep overlay framebuffer, when used
+├── sleep_images/           # Rendered custom sleep-image grayscale planes
 ├── epub_12471232/          # Each EPUB is cached to epub_<hash>
 │   ├── progress.bin        # Reading position (chapter, page, etc.)
 │   ├── stats.bin           # Legacy per-book reading stats

docs/file-formats.md

@@ -5,6 +5,37 @@ All POD fields are written in the ESP32 little-endian representation used by
 `Serialization.h`; strings are length-prefixed UTF-8 unless a format notes a
 fixed-size char buffer.
 
+## `/.crosspoint/sleep_images/<pathHash>_<sourceHash>_<sourceSize>_<WxH>_v1.bin`
+
+### Version 1
+
+Custom BMP sleep images are rendered once into the three native display planes
+used by the grayscale sleep refresh, then cached in `/.crosspoint/sleep_images/`.
+The cache key includes:
+
+- `pathHash`: FNV-1a 32-bit hash of the SD-card source path
+- `sourceHash`: FNV-1a 32-bit hash of the source file bytes
+- `sourceSize`: source file size in bytes
+- `WxH`: renderer screen dimensions
+- `v1`: cache format version
+
+Binary layout:
+
+- header:
+  - `magic` (`uint32_t`, ASCII `YSIC` in little-endian)
+  - `version` (`uint16_t`, `1`)
+  - `screenWidth` (`uint16_t`)
+  - `screenHeight` (`uint16_t`)
+  - `bufferSize` (`uint32_t`)
+  - `sourceHash` (`uint32_t`)
+  - `sourceSize` (`uint32_t`)
+- `bufferSize` bytes: black-and-white base plane
+- `bufferSize` bytes: grayscale LSB plane
+- `bufferSize` bytes: grayscale MSB plane
+
+The firmware compares the full header before using the cache. If a read fails,
+the image is rendered from the original BMP and the cache can be rebuilt.
+
 ## `book.bin`
 
 ### Version 8
@@ -230,32 +261,33 @@ Binary layout:
 
 ## `/.crosspoint/finished_books.bin`
 
-### Version 2
+### Version 3
 
 `finished_books.bin` is a bounded chronological index used by the persistent
 Finished Books statistics page. It holds at most 32 entries, all navigable in
-five-entry pages, and is refreshed
+four-entry pages, and is refreshed
 when completion changes and when a completed EPUB or XTC reader exits. The
 normal reader page-turn path never reads or writes it.
 
 The eight-byte header contains:
 
 - `[0-3]` magic ASCII `CPFB`
-- `[4]` version (`2`)
+- `[4]` version (`3`)
 - `[5]` entry count (`uint8_t`, maximum `32`)
 - `[6-7]` reserved (`uint16_t`)
 
 Each variable-length entry contains a `uint64_t` path key, total reading seconds
 (`uint32_t`), start date and finish date (each `year uint16_t`, `month uint8_t`,
-`day uint8_t`), a title length (`uint16_t`, maximum 160), then the UTF-8 title
-bytes. Entries are stored newest finish date first. Saves use `.tmp` and `.bak`
-rotation. When an EPUB is moved to `/Read/`, its path key is migrated explicitly
-so two different books with the same title remain separate entries.
-
-Version 1 entries, which contain no start date, remain readable. Their timeline
-falls back to the finish date with its year and the reading time until Reading
+`day uint8_t`), a title length (`uint16_t`, maximum 160), UTF-8 title bytes, an
+author length (`uint16_t`, maximum 120), then UTF-8 author bytes. Entries are
+stored newest finish date first. Saves use `.tmp` and `.bak` rotation. When an
+EPUB is moved to `/Read/`, its path key is migrated explicitly so two different
+books with the same title remain separate entries.
+
+Version 1 entries, which contain no start date, and version 2 entries, which
+contain no author, remain readable. Missing fields stay blank until Reading
 Stats reconciles the entry with the completed book's persistent statistics. The
-next index write uses version 2 and the real book-path key; accidental cache-path
+next index write uses version 3 and the real book-path key; accidental cache-path
 entries are merged during the same reconciliation.
 
 When the file is first introduced, YACP checks only the bounded recent-books

docs/reader-features.md

@@ -168,10 +168,10 @@ If **Move finished books to Read folder** is enabled, books marked as finished a
 
 Marking books as finished also contributes to the total **Books Read** reading stat.
 
-The **Finished Books** statistics page shows the reading start and finish dates with their years, followed by the
-active reading time. It does not display a separate elapsed-day count.
-Opening Reading Stats for a completed EPUB or XTC reconciles those persistent dates with the bounded Finished Books
-index, including legacy entries that do not yet contain their known start date.
+The **Finished Books** statistics page groups completed books by finish month. Each month shows the completed-book
+count and total reading time for that month, followed by the finished titles and their authors when known.
+Opening Reading Stats for a completed EPUB or XTC reconciles its persistent dates and author with the bounded Finished
+Books index, including legacy entries that do not yet contain their known start date or author.
 
 The file browser can also mark books as finished without opening them first.