chat-summaries/2026-03-08_20-30-summary.md

# Port PR #1342: Book Info, Metadata, Serialization Safety

**Date:** 2026-03-08
**Task:** Port upstream PR #1342 with mod-specific adaptations (ManageBook menu in file browser, confirmation guards on all destructive actions)

## Changes Made

### Part A: EPUB Metadata Expansion (4 files)
- `lib/Epub/Epub/parsers/ContentOpfParser.h/.cpp`: Added `series`, `seriesIndex`, `description` fields and parser states. Parses `dc:description`, `calibre:series/calibre:series_index` (OPF2), and EPUB3 `belongs-to-collection/group-position`. Added `stripHtml()` and `trim()` helpers.
- `lib/Epub/Epub/BookMetadataCache.h/.cpp`: Added 3 new string fields to `BookMetadata`. Bumped `BOOK_CACHE_VERSION` 5→6. Updated binary serialization.
- `lib/Epub/Epub.h/.cpp`: Added `getSeries()`, `getSeriesIndex()`, `getDescription()` getters. Propagated new fields from parser.

### Part B: Serialization Safety (10 files, 37 call sites)
- `lib/Serialization/Serialization.h`: `readString` returns `bool` with `MAX_STRING_LENGTH=4096` guard.
- Updated all call sites in: `ContentOpfParser.cpp`, `BookMetadataCache.cpp`, `ImageBlock.cpp`, `TextBlock.cpp`, `Section.cpp`, `CrossPointSettings.cpp`, `CrossPointState.cpp`, `RecentBooksStore.cpp`, `WifiCredentialStore.cpp`, `KOReaderCredentialStore.cpp`.

### Part C: RecentBooksStore Series Field (5 files)
- `src/RecentBooksStore.h/.cpp`: Added `series` field to `RecentBook`. Updated `addBook()`/`updateBook()` signatures.
- `src/JsonSettingsIO.cpp`: Added `series` to JSON serialization.
- Updated call sites in `EpubReaderActivity.cpp`, `TxtReaderActivity.cpp`, `XtcReaderActivity.cpp`, `HomeActivity.cpp`.

### Part D: BookInfoActivity (2 new files)
- `src/activities/home/BookInfoActivity.h/.cpp`: ActivityManager-compliant info screen showing title, author, series, language, file size, description. Scrollable content, synchronous metadata loading.

### Part E: FileBrowser Controls (2 files)
- `src/activities/home/FileBrowserActivity.h/.cpp`: Replaced long-press Confirm=delete with Left=ManageBook menu, Right=BookInfo. Added contextual button hints. Added `handleManageResult()` with confirmation guards.

### Part F: ConfirmationActivity Input Gating (2 files)
- `src/activities/util/ConfirmationActivity.h/.cpp`: Added `inputArmed` mechanism preventing accidental confirm from the press that opened the dialog.

### Part G: Confirmation Guards (3 files, 10 sites)
- `src/activities/home/HomeActivity.h/.cpp`: Extracted `executeManageAction()`, wrapped DELETE/ARCHIVE in ConfirmationActivity chain.
- `src/activities/home/RecentBooksActivity.h/.cpp`: Same pattern as HomeActivity.
- `src/activities/reader/EpubReaderActivity.cpp`: Wrapped all 6 DELETE/ARCHIVE sites (EndOfBookMenu, ReaderMenu, ManageBook) in ConfirmationActivity chains.

### Part H: i18n + Theme (2 files)
- `lib/I18n/translations/english.yaml`: Added `STR_BOOK_INFO`, `STR_AUTHOR`, `STR_SERIES`, `STR_FILE_SIZE`, `STR_DESCRIPTION`, `STR_MANAGE`, `STR_INFO`.
- `src/activities/home/RecentBooksActivity.cpp`: Updated list subtitle to show "Author • Series" when available.

### Documentation
- `mod/prs/MERGED.md`: Added PR #1342 entry with full diff analysis.

## Build Verification
- `pio run`: SUCCESS (0 errors, 0 warnings)
- RAM: 30.3% (99,428 / 327,680 bytes)
- Flash: 95.6% (6,266,793 / 6,553,600 bytes)
- `clang-format`: Applied to all source files

## Follow-up Items
- Hardware testing needed: all 4 orientations, Book Info screen, ManageBook menu from file browser, confirmation dialogs
- Series rendering in Home screen "Continue Reading" card (deferred — data flows through but no visual change yet)
- Delete `.crosspoint/` on device to force cache regeneration (version bump 5→6)
port: upstream PR #1342 - Book Info screen, richer metadata, safer controls Ports upstream PR #1342 (feat: Add Book Info screen, richer metadata, and safer file-browser controls) with mod-specific adaptations: - Parse and cache series, seriesIndex, description from EPUB OPF - Bump book.bin cache version to 6 for new metadata fields - Add BookInfoActivity (new screen) accessible via Right button in FileBrowser - Add ManageBook menu via Left button in FileBrowser (replaces upstream hidden delete) - Guard all delete/archive actions with ConfirmationActivity (10 call sites) - Add inputArmed gating to ConfirmationActivity to prevent accidental confirmation - Safe deserialization: readString now returns bool with MAX_STRING_LENGTH guard - Add series field to RecentBooksStore with JSON and binary serialization - Add i18n keys: STR_BOOK_INFO, STR_AUTHOR, STR_SERIES, STR_FILE_SIZE, etc. Made-with: Cursor 2026-03-09 00:39:32 -04:00			`# Port PR #1342: Book Info, Metadata, Serialization Safety`

			`Date: 2026-03-08`
			`Task: Port upstream PR #1342 with mod-specific adaptations (ManageBook menu in file browser, confirmation guards on all destructive actions)`

			`## Changes Made`

			`### Part A: EPUB Metadata Expansion (4 files)`
			- `lib/Epub/Epub/parsers/ContentOpfParser.h/.cpp`: Added `series`, `seriesIndex`, `description` fields and parser states. Parses `dc:description`, `calibre:series/calibre:series_index` (OPF2), and EPUB3 `belongs-to-collection/group-position`. Added `stripHtml()` and `trim()` helpers.
			- `lib/Epub/Epub/BookMetadataCache.h/.cpp`: Added 3 new string fields to `BookMetadata`. Bumped `BOOK_CACHE_VERSION` 5→6. Updated binary serialization.
			- `lib/Epub/Epub.h/.cpp`: Added `getSeries()`, `getSeriesIndex()`, `getDescription()` getters. Propagated new fields from parser.

			`### Part B: Serialization Safety (10 files, 37 call sites)`
			- `lib/Serialization/Serialization.h`: `readString` returns `bool` with `MAX_STRING_LENGTH=4096` guard.
			- Updated all call sites in: `ContentOpfParser.cpp`, `BookMetadataCache.cpp`, `ImageBlock.cpp`, `TextBlock.cpp`, `Section.cpp`, `CrossPointSettings.cpp`, `CrossPointState.cpp`, `RecentBooksStore.cpp`, `WifiCredentialStore.cpp`, `KOReaderCredentialStore.cpp`.

			`### Part C: RecentBooksStore Series Field (5 files)`
			- `src/RecentBooksStore.h/.cpp`: Added `series` field to `RecentBook`. Updated `addBook()`/`updateBook()` signatures.
			- `src/JsonSettingsIO.cpp`: Added `series` to JSON serialization.
			- Updated call sites in `EpubReaderActivity.cpp`, `TxtReaderActivity.cpp`, `XtcReaderActivity.cpp`, `HomeActivity.cpp`.

			`### Part D: BookInfoActivity (2 new files)`
			- `src/activities/home/BookInfoActivity.h/.cpp`: ActivityManager-compliant info screen showing title, author, series, language, file size, description. Scrollable content, synchronous metadata loading.

			`### Part E: FileBrowser Controls (2 files)`
			- `src/activities/home/FileBrowserActivity.h/.cpp`: Replaced long-press Confirm=delete with Left=ManageBook menu, Right=BookInfo. Added contextual button hints. Added `handleManageResult()` with confirmation guards.

			`### Part F: ConfirmationActivity Input Gating (2 files)`
			- `src/activities/util/ConfirmationActivity.h/.cpp`: Added `inputArmed` mechanism preventing accidental confirm from the press that opened the dialog.

			`### Part G: Confirmation Guards (3 files, 10 sites)`
			- `src/activities/home/HomeActivity.h/.cpp`: Extracted `executeManageAction()`, wrapped DELETE/ARCHIVE in ConfirmationActivity chain.
			- `src/activities/home/RecentBooksActivity.h/.cpp`: Same pattern as HomeActivity.
			- `src/activities/reader/EpubReaderActivity.cpp`: Wrapped all 6 DELETE/ARCHIVE sites (EndOfBookMenu, ReaderMenu, ManageBook) in ConfirmationActivity chains.

			`### Part H: i18n + Theme (2 files)`
			- `lib/I18n/translations/english.yaml`: Added `STR_BOOK_INFO`, `STR_AUTHOR`, `STR_SERIES`, `STR_FILE_SIZE`, `STR_DESCRIPTION`, `STR_MANAGE`, `STR_INFO`.
			- `src/activities/home/RecentBooksActivity.cpp`: Updated list subtitle to show "Author • Series" when available.

			`### Documentation`
			- `mod/prs/MERGED.md`: Added PR #1342 entry with full diff analysis.

			`## Build Verification`
			- `pio run`: SUCCESS (0 errors, 0 warnings)
			`- RAM: 30.3% (99,428 / 327,680 bytes)`
			`- Flash: 95.6% (6,266,793 / 6,553,600 bytes)`
			- `clang-format`: Applied to all source files

			`## Follow-up Items`
			`- Hardware testing needed: all 4 orientations, Book Info screen, ManageBook menu from file browser, confirmation dialogs`
			`- Series rendering in Home screen "Continue Reading" card (deferred — data flows through but no visual change yet)`
			- Delete `.crosspoint/` on device to force cache regeneration (version bump 5→6)