# 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)