Page numbers in Kindle popup

.github/workflows/test.yml

@@ -59,6 +59,10 @@ jobs:
         run: |
           ./scripts/test_watchdog.sh './test/CatchTests/build/tests [kindle] --reporter console --reporter junit::out=catch-results-kindle.xml' 60
 
+      - name: Run kindle short pages tests
+        run: |
+          ./scripts/test_watchdog.sh './test/CatchTests/build/tests [kindle-short-pages] --reporter console --reporter junit::out=catch-results-kindle-short-pages.xml' 60
+
       - name: Test Report
         uses: dorny/test-reporter@v1
         # run this step even if previous step failed

.gitignore

@@ -39,4 +39,7 @@ build-log.txt
 test_kindle_*.ini
 
 # Claude makes docs for sharing with other repos
-docs/* 
+docs/*
+
+# Log files
+logs/* 

AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+
+This guide aligns contributors on how to build, test, and submit changes for the Sol Reader glasses firmware.
+
+## Project Structure & Module Organization
+- `src/`: C/C++ app code (entry: `src/main.cpp`). Key areas: `Communications/`, `Displays/`, `EPub/`, `Inputs/`, `Models/`, `Renderers/`, `Sensors/`, `Storage/`, `UI/`, `Ulp/`.
+- `include/`: generated or shared headers. `components/` and `lib/`: external components and Simulator code.
+- `test/CatchTests/`: Catch2 tests; images under `Images/Accepted/` (baselines) and `Images/TestRun/` (diffs).
+- `scripts/`: helper tools; `docs/`, `data/`: assets and docs. Build output goes to `build*/`.
+
+## Build, Test, and Development Commands
+- Build firmware: `. ~/esp/esp-idf/export.sh && make build`
+- Flash + monitor: `make flash monitor` (set serial ports automatically). Stop reset-only monitor with `make monitor`.
+- Target profiles: `TARGET=glasses-release make build` (see `sdkconfig.defaults.*`).
+- Simulator: `make sim` (or `sim8`, `sim16`, `sim24`); logs in `logs/`.
+- Tests: `make test` (or focused: `make test-kindle`, `make test-content-sync`).
+- Lint/format: `make clang-format` or `make tidy`; clean: `make clean`.
+
+## Coding Style & Naming Conventions
+- C++ style: LLVM base, 4-space indent, 100-col limit (`.clang-format`).
+- Includes: group/regroup system `<...>` before local "...".
+- Naming (`.clang-tidy`): namespaces `lower_case`; classes/structs `CamelCase`; functions `camelBack`; variables `camelBack`; constants `UPPER_CASE`; private/protected members end with `_`.
+- Run `make tidy` before pushing. Python files are auto-formatted in CI via `black` and `isort`.
+
+## Testing Guidelines
+- Framework: Catch2 in `test/CatchTests`. Add files as `Test*.cpp` or `<Feature>Test.cpp`.
+- Tags: use category tags (e.g., `[epub]`, `[content-sync]`, `[telemetry]`, `[kindle]`).
+- Visual baselines: when a baseline is missing or mismatches, tests write new images to `.../TestRun/` and also copy them into the matching `.../Accepted/` location—but the run still fails (by design) so CI flags it.
+- Local acceptance: run `make test`, review diffs, then leave the updated baselines in Accepted/ unstaged to accept them, then rerun.
+
+## Commit & Pull Request Guidelines
+- Messages: imperative, concise; reference issues/PRs with `#1234`. Example: `Fix: prevent green flash (#1143)`.
+- PRs: include a summary, linked issues, test plan (commands run), and screenshots or updated baselines for UI changes.
+- CI must pass: Catch2 tests, clang-tidy/format, and Python formatting workflows run on PRs. Run `make test` and `make tidy` locally first.
+
+## Security & Configuration Tips
+- Do not commit secrets or local prefs (e.g., `simprefs.ini`, logs, `TestRun/` outputs are gitignored).
+- Set up ESP-IDF per README; export the environment before building. For Simulator cloud access, keep tokens in `simprefs.ini` locally.

CLAUDE.md

@@ -1,5 +1,8 @@
 # Sol Reader Embedded App - Development Guide
 
+## Tips
+- **Visual Test Generation**: When tests use `ASSERT_VIEW_UNCHANGED`, they automatically generate accepted images on first run if they don't exist. The test will fail initially and show you the copy command to create the accepted image from the generated TestRun image.
+
 ## Test Screenshots
 - Never copy TestRun images to Accepted folder - the test runner auto-accepts them when tests fail
 - The test framework automatically updates accepted screenshots when they change
@@ -12,10 +15,16 @@
 - Monitor serial logs: `make monitor`
 - Run simulator: `make sim` (or `make sim8`, `make sim16`, `make sim24` for different display modes)
   - No need to run export.sh for simulator
+  - Simulator output is logged to `logs/sim.log` (or `logs/sim8.log`, `logs/sim16.log`, `logs/sim24.log`)
+  - Watch logs in real-time: `tail -f logs/sim.log`
+  - Log file is cleared on each run
 - Run tests: `make test`
-- Run single test: `./test/CatchTests/build/tests '[test-tag]'` (e.g. `'[epub]'`, `'[content-sync]'`)
-- Format code: `make clang-format`
-- Static analysis: `make clang-tidy`
+- Build tests: `make test-build`
+- Run single test: `make test-build && ./test/CatchTests/build/tests '[test-tag]'` (e.g. `'[epub]'`, `'[content-sync]'`)
+  - Always rebuild before running tests to ensure changes are included
+- Format code: `make clang-tidy`
+  - **IMPORTANT**: Always run `. $IDF_PATH/export.sh && make clang-tidy` after making code changes
+- Full linting (format + static analysis): `make clang-format` (can be slow)
 
 ## Code Style Guidelines
 - Format: Use clang-format with LLVM-based style (ColumnLimit: 100, IndentWidth: 4)
@@ -24,8 +33,17 @@
 - Logging: Use log_d/log_i/log_w/log_e with descriptive messages
 - Memory: Manage heap allocations carefully, use HEAP_PROFILE macros to track
 - Naming: camelCase for variables/methods, PascalCase for classes, ALL_CAPS for constants/macros
-- Comments: Use `//` for line comments, `/* */` for block comments
+- Comments: Use `//` for line comments and for block comments
 - Stack usage: Monitor stack usage with watermarks (SHOW_WATERMARK macro)
 - Threading: Use DispatchQueue for most async operations
 - Comments: Only include comments if they add context that's not readily apparent in the next line of code or if the code block has some complexity
 - Comments: Don't add comments that are simply addressing the prompt, only add them if the comments clear up confusion
+
+## Architecture Conventions
+- **Network/API requests**: All network requests must go through SindarinAPI (never direct HTTP calls from UI screens)
+- **Kindle navigation**: Kindle-specific logic and state management should be delegated to KindlePageFlipper, not handled in UI screens
+- **Async operations**: Use DispatchQueue for background operations; UI screens coordinate but don't implement async logic directly
+- **State management**: Business logic classes (like KindlePageFlipper) encapsulate state changes; UI screens handle callbacks and visual updates
+- **Error handling**: Use assertions (`assert()`) for programming errors; return structured error types for recoverable operations
+- **Data persistence**: UI screens use LocalStore and PreferencesStore for data access; avoid direct file system operations in UI
+- **Telemetry**: Use centralized Telemetry class with structured fields; log meaningful events at appropriate levels (log_d/log_i/log_w/log_e)

Makefile

@@ -1,7 +1,7 @@
 all: build
 
 # Use all but 1 core for building
-NUM_CORES := $(shell nproc)
+NUM_CORES := $(shell nproc 2>/dev/null || sysctl -n hw.ncpu)
 NUM_CORES := $(shell echo $$(( $(NUM_CORES) - 1 )))
 NUM_CORES := $(shell [ $(NUM_CORES) -lt 1 ] && echo 1 || echo $(NUM_CORES))
 
@@ -51,7 +51,11 @@ sim-build:
 
 .PHONY: sim-run
 sim: sim-build
-	./lib/Simulator/build/simulator
+	@mkdir -p logs
+	@echo "Starting simulator with logging to logs/sim.log"
+	@echo "You can watch the log with: tail -f logs/sim.log"
+	@> logs/sim.log
+	@./lib/Simulator/build/simulator 2>&1 | tee logs/sim.log
 
 .PHONY: sim8-build
 sim8-build:
@@ -60,7 +64,11 @@ sim8-build:
 
 .PHONY: sim-run8
 sim8: sim8-build
-	./lib/Simulator/build8/simulator
+	@mkdir -p logs
+	@echo "Starting simulator with logging to logs/sim8.log"
+	@echo "You can watch the log with: tail -f logs/sim8.log"
+	@> logs/sim8.log
+	@./lib/Simulator/build8/simulator 2>&1 | tee logs/sim8.log
 
 .PHONY: sim16-build
 sim16-build:
@@ -69,7 +77,11 @@ sim16-build:
 
 .PHONY: sim-run16
 sim16: sim16-build
-	./lib/Simulator/build16/simulator
+	@mkdir -p logs
+	@echo "Starting simulator with logging to logs/sim16.log"
+	@echo "You can watch the log with: tail -f logs/sim16.log"
+	@> logs/sim16.log
+	@./lib/Simulator/build16/simulator 2>&1 | tee logs/sim16.log
 
 .PHONY: sim24-build
 sim24-build:
@@ -78,7 +90,11 @@ sim24-build:
 
 .PHONY: sim-run24
 sim24: sim24-build
-	./lib/Simulator/build24/simulator
+	@mkdir -p logs
+	@echo "Starting simulator with logging to logs/sim24.log"
+	@echo "You can watch the log with: tail -f logs/sim24.log"
+	@> logs/sim24.log
+	@./lib/Simulator/build24/simulator 2>&1 | tee logs/sim24.log
 
 .PHONY: lldb
 lldb: sim-build
@@ -100,6 +116,7 @@ test: test-build
 	./test/CatchTests/build/tests '[content-sync]'
 	./test/CatchTests/build/tests '[telemetry]'
 	./test/CatchTests/build/tests '[kindle]'
+	./test/CatchTests/build/tests '[kindle-short-pages]'
 
 .PHONY: test-content-sync
 test-content-sync: test-build
@@ -115,6 +132,10 @@ test-epub-lldb: test-build
 
 test-kindle: test-build
 	./test/CatchTests/build/tests '[kindle]'
+	./test/CatchTests/build/tests '[kindle-short-pages]'
+
+test-kindle-short: test-build
+	./test/CatchTests/build/tests '[kindle-short-pages]'
 
 test-kindle-lldb: test-build
 	lldb ./test/CatchTests/build/tests '[kindle]'