crosspoint-reader-mod/mod/docs/session-summary.md

Session Context Dump (2026-02-09)

Everything below is a snapshot of the conversation context at the time of writing. It captures what was explored, what was read, what was produced, and what the current state of work is. Use this to resume without re-exploring.

Branch State

• Current branch: mod/sleep-screen-tweaks
• Git status: .gitignore modified (unstaged). No other tracked changes. All mod/docs/ files are new/untracked (the mod/ directory is gitignored).

What Was Done This Session

1. Explored the entire project structure using parallel agents. Mapped every directory, identified all source files, read key headers and configs.

2. Created 3 documentation files in mod/docs/:

   • hardware.md -- Full hardware capabilities (CPU, flash partitions, display specs with GPIO pins, buttons with indices, SD card, battery, WiFi, USB, power management, SDK libraries)
   • file-structure.md -- Complete directory tree with descriptions of every file group (src/ activities, components, network; lib/ HAL, EPUB engine, fonts, supporting libs; scripts, tests, docs, .github CI)
   • ci-build-and-code-style.md -- Build system (3 PlatformIO environments), all 4 CI workflows with triggers and steps, release process, clang-format rules table, cppcheck config, PR requirements, contribution guidelines

3. Created project-summary.md -- condensed reference consolidating all three docs plus architecture patterns, caching behavior, and constraints.

Files Read During Exploration

The following files were read in full and their contents informed the documentation:

Config/root:

• platformio.ini -- all build environments, flags, dependencies, SDK symlinks
• partitions.csv -- flash partition table (6 rows)
• .clang-format -- 332 lines of formatting rules
• .clangd -- C++2a standard setting
• .gitmodules -- open-x4-sdk submodule reference
• README.md -- project overview, features checklist, install instructions, internals (caching), contributing
• SCOPE.md -- in-scope/out-of-scope feature boundaries
• GOVERNANCE.md -- community principles, moderation

HAL layer:

• lib/hal/HalDisplay.h -- display constants (480x800, buffer size 48000), refresh modes enum, grayscale buffer methods
• lib/hal/HalGPIO.h -- GPIO pin defines (EPD_SCLK=8, EPD_MOSI=10, EPD_CS=21, EPD_DC=4, EPD_RST=5, EPD_BUSY=6, SPI_MISO=7, BAT_GPIO0=0, UART0_RXD=20), button indices (0-6), WakeupReason enum
• lib/hal/HalStorage.h -- Storage singleton, file ops API, SDCardManager wrapper

Application:

• src/main.cpp -- 413 lines: setup/loop, activity routing (onGoHome, onGoToReader, etc.), font initialization (Bookerly 12/14/16/18, NotoSans 12/14/16/18, OpenDyslexic 8/10/12/14, Ubuntu 10/12), power button verification, deep sleep entry, auto-sleep timeout, memory logging
• src/MappedInputManager.h -- Button enum (Back, Confirm, Left, Right, Up, Down, Power, PageBack, PageForward), Labels struct, mapLabels()
• src/Battery.h -- global BatteryMonitor battery(BAT_GPIO0) instance

CI/GitHub:

• .github/workflows/ci.yml -- 4 jobs (clang-format, cppcheck, build, test-status), triggers, steps
• .github/workflows/release.yml -- tag trigger, gh_release env, 5 artifact files
• .github/workflows/release_candidate.yml -- workflow_dispatch, release/* branch gate, SHORT_SHA extraction
• .github/workflows/pr-formatting-check.yml -- semantic PR title check
• .github/PULL_REQUEST_TEMPLATE.md -- summary, context, AI usage disclosure

Scripts:

• bin/clang-format-fix -- bash script, git ls-files, grep for C/C++ extensions, excludes builtinFonts/, -g flag for modified-only

Directory listings obtained:

• Root, src/, src/Activities/ (full recursive), lib/ (all subdirectories), lib/Epub/ (full recursive), docs/, scripts/, test/

Current Mod Work Context

From mod/docs/todo.md, two tasks are planned for the sleep screen on branch mod/sleep-screen-tweaks:

Task 1 -- Gradient fill for letterboxed images: When a sleep screen image doesn't match the 480x800 display aspect ratio, void/letterbox areas should be filled with a gradient sampled from the nearest ~20 pixels of the image edge. Relevant files:

• src/activities/boot_sleep/SleepActivity.cpp/.h -- sleep screen rendering logic
• lib/GfxRenderer/BitmapHelpers.cpp/.h -- bitmap manipulation utilities
• lib/GfxRenderer/Bitmap.cpp/.h -- bitmap data structure
• lib/hal/HalDisplay.h -- display dimensions (480x800), buffer operations

Task 2 -- Fix "Fit" mode for small images: In "Fit" mode, images smaller than the display should be scaled UP to fit (maintaining aspect ratio). The current implementation only scales down larger images. Same relevant files as Task 1.

Neither task has been started yet -- only documentation/exploration was done this session.

Key Architectural Details Observed in Source

Activity lifecycle (from main.cpp):

• exitActivity() calls onExit() then delete on the current activity
• enterNewActivity() sets currentActivity and calls onEnter()
• Activities receive GfxRenderer& and MappedInputManager& in constructors
• ReaderActivity also receives the epub path and callback functions for navigation

Boot sequence (from main.cpp setup()):

1. gpio.begin() -- init GPIO/SPI
2. Serial init only if USB connected
3. Storage.begin() -- SD card init (shows error screen on failure)
4. Load settings, KOReader store, UI theme
5. Check wakeup reason: PowerButton verifies hold duration, AfterUSBPower goes back to sleep, AfterFlash/Other proceed
6. Display + font setup
7. Show BootActivity (splash)
8. Load app state + recent books
9. Route to HomeActivity or ReaderActivity based on saved state

Main loop (from main.cpp loop()):

1. Poll GPIO
2. Apply fadingFix setting to renderer
3. Log memory every 10s (when serial active)
4. Track activity timer, auto-sleep on configurable timeout
5. Check power button hold for manual sleep
6. Run currentActivity->loop()
7. Delay 10ms normally, or yield() if activity requests fast response (e.g. web server)

Settings system:

• CrossPointSettings loaded from SD at boot via SETTINGS macro
• Includes: shortPwrBtn behavior, getPowerButtonDuration(), getSleepTimeoutMs(), fadingFix
• CrossPointState (APP_STATE) tracks: openEpubPath, lastSleepFromReader, readerActivityLoadCount

Display details (from HalDisplay.h):

• DISPLAY_WIDTH and DISPLAY_HEIGHT are constexpr sourced from EInkDisplay
• DISPLAY_WIDTH_BYTES = DISPLAY_WIDTH / 8 (480/8 = 60)
• BUFFER_SIZE = DISPLAY_WIDTH_BYTES * DISPLAY_HEIGHT (60 * 800 = 48000)
• Grayscale uses separate LSB/MSB buffers
• displayBuffer() and refreshDisplay() take RefreshMode and optional turnOffScreen
• drawImage() supports PROGMEM source flag

Companion Documentation Files

All in mod/docs/:

• todo.md -- active mod task list (sleep screen tweaks)
• hardware.md -- full hardware reference (175 lines)
• file-structure.md -- complete file tree with descriptions (307 lines)
• ci-build-and-code-style.md -- build/CI/style reference (281 lines)
• project-summary.md -- condensed project reference (217 lines)
• session-summary.md -- this file