🚀 CPR-vCodex Steroids — Update & Improvement Report

📋 Summary

This update brings CPR-vCodex Steroids fully in line with upstream 1.5.0.23, while keeping all Steroids-specific enhancements intact. The firmware is more stable, faster, and easier to maintain — without changing the reading experience you already know.

🎯 Upstream Alignment — CPR-vCodex 1.5.0.23

What changed upstream

The original CPR-vCodex project introduced several fixes and improvements in version 1.5.0.23. We reviewed every change and safely integrated the ones that make sense for Steroids, while preserving our custom features like reading statistics, CrossInk EPUB engine, and X3/X4 device support.

What we brought over

• ✅ Better hardware detection — More reliable startup on both X3 and X4 devices
• ✅ Safer file handling — JSON settings and reading stats are now saved atomically, reducing corruption risk
• ✅ Faster storage access — SD card operations are leaner and less fragmented
• ✅ Cleaner reader startup — Removed redundant file existence checks for smoother book opening
• ✅ Upstream test coverage — Added image-safety tests to catch regressions early

What we kept separate

• 🔒 EPUB engine stays on the Steroids/CrossInk version (v60) for best compatibility
• 🔒 Reading stats keep all Steroids fields (pace, summary JSON, etc.)
• 🔒 Memory budget and JPEG handling remain tuned for the ESP32-C3 constraints

✨ Improvements & Refactoring (in plain English)

All of this is behind-the-scenes work. The UI and reading experience stay the same, but the code is cleaner, faster, and safer to change in the future.

🧹 Code cleanup & organization

• Removed duplicate logic — Consolidated repeated boot and restart guards so the firmware does one thing, not six
• Unified helper functions — WiFi, popups, toasts, and string copies now use shared utilities instead of being rewritten in each screen
• Deleted dead code — Removed unused restart paths and old variables that were cluttering the main loop

⚡ Performance & memory

• Smaller memory footprint — Better heap usage during boot, especially when loading fonts and settings
• Leaner SD card access — Fewer directory scans mean faster library loading and less wear on the card
• Safer JSON saves — Reading stats and settings are written to a temp file first, then renamed, so a power loss mid-save won’t corrupt data

📱 User-facing polish

• More consistent menus — List screens (settings, favorites, reading stats) now use a unified input system, so scrolling and confirmation behave the same everywhere
• Cleaner empty states — When a list is empty (no favorites, no flashcards, etc.), the message is rendered consistently across all activities
• Better long-press handling — Long press now has a single, clear implementation used by the library, home, and keyboard screens

🛠️ Developer-quality improvements

• Shared utilities — Common operations like text overlay, battery shutdown screen, and WiFi power management are now in one place
• Easier maintenance — Centralized hint rendering and list helpers mean bug fixes apply everywhere at once
• Better documentation — Added internal guides for boot, loop, and silent-restart patterns so future changes are safer

🗑️ What we intentionally removed

• CoverGenerator utility — Removed the experimental non-blocking cover generation introduced in earlier refactor commits. The old cover handling is restored for maximum stability.

📊 Impact at a Glance

🙏 Why this matters

• Stability first — Every change was evaluated against the ESP32-C3’s tight memory limits
• No surprises — Your books, settings, reading stats, and WiFi credentials are preserved
• Future-proof — Cleaner code means faster fixes and easier upstream syncs going forward

Built with care for the Xteink X4 and X3 community. If you spot anything unusual, open an issue on GitHub.