reorganize

.github/workflows/ci.yml

@@ -7,6 +7,9 @@ on:
 jobs:
   converter:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: book-processing
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -18,6 +21,9 @@ jobs:
 
   firmware:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: firmware
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

.gitignore

@@ -6,6 +6,7 @@
 *.map
 
 # Python bytecode, test output, and coverage reports.
+.venv/
 __pycache__/
 *.py[cod]
 .pytest_cache/
@@ -16,7 +17,7 @@ htmlcov/
 # Generated reader content and local source books.
 chapters/
 *.epub
-!examples/rsvp-timing-sample.epub
+!book-processing/examples/rsvp-timing-sample.epub
 
 # Filesystem metadata that may appear when preparing an SD card.
 .DS_Store

Makefile

@@ -0,0 +1,31 @@
+PYTHON ?= python3
+PIO ?= pio
+UPLOAD_PORT ?=
+VENV := .venv
+DEPS_STAMP := $(VENV)/.requirements-installed
+
+.DEFAULT_GOAL := all
+.PHONY: all deps test convert build flash
+
+all: test convert build
+
+deps: $(DEPS_STAMP)
+
+$(DEPS_STAMP): book-processing/requirements.txt
+	$(PYTHON) -m venv $(VENV)
+	$(VENV)/bin/python -m pip install -r $<
+	touch $@
+
+test: deps
+	. $(VENV)/bin/activate && cd book-processing && python -m unittest discover -v
+
+convert: deps
+	@output_dir=$$(mktemp -d /tmp/tds3p-timing-sample.XXXXXX); \
+		echo "Converting sample EPUB into $$output_dir"; \
+		. $(VENV)/bin/activate && cd book-processing && python epub_to_chapters.py examples/rsvp-timing-sample.epub "$$output_dir"
+
+build:
+	cd firmware && $(PIO) run
+
+flash:
+	cd firmware && $(PIO) run -t upload $(if $(UPLOAD_PORT),--upload-port $(UPLOAD_PORT))

README.md

@@ -101,15 +101,15 @@ Chapter 2
 Generate this layout from an EPUB with the included converter:
 
 ```bash
-./.venv/bin/python -m pip install -r requirements.txt
+./.venv/bin/python -m pip install -r book-processing/requirements.txt
-./.venv/bin/python epub_to_chapters.py book.epub "Example Book"
+./.venv/bin/python book-processing/epub_to_chapters.py book.epub "Example Book"
 ```
 
 For a quick end-to-end check, the repository includes a two-chapter sample
 with EPUB styles, punctuation, and repeated invented names:
 
 ```bash
-./.venv/bin/python epub_to_chapters.py examples/rsvp-timing-sample.epub "Timing Sample"
+./.venv/bin/python book-processing/epub_to_chapters.py book-processing/examples/rsvp-timing-sample.epub "Timing Sample"
 ```
 
 The output directory must be empty unless `--overwrite` is supplied. Copy the
@@ -141,7 +141,7 @@ bold records select matching reader-font variants; the device never performs
 dictionary or SD-card lookups while advancing words.
 
 The converter requires the desktop-only `english-words` and `wordfreq`
-packages listed in `requirements.txt`; the reader does not need either
+packages listed in `book-processing/requirements.txt`; the reader does not need either
 dependency. Reconvert a book to create v2 sidecars with unfamiliar-word
 timing. Existing v1 style-only sidecars remain readable but do not contain
 timing metadata.
@@ -150,10 +150,10 @@ Eject the card safely and insert it in the board before powering the board.
 
 ## 3. Build the firmware
 
-Open a terminal in this project directory:
+Open a terminal in the `firmware` directory:
 
 ```bash
-cd /path/to/tds3p-rsvp-reader
+cd /path/to/tds3p-rsvp-reader/firmware
 pio run
 ```
 
@@ -163,7 +163,7 @@ ends with `SUCCESS` and creates the firmware under `.pio/build/rsvp_reader/`.
 
 The project targets the T-Display S3 Pro's 16 MB flash and 8 MB OPI PSRAM. It
 defaults to the v1.1 16-step backlight driver. If your board is the original
-v1.0 hardware, add this line under `build_flags` in `platformio.ini` before
+v1.0 hardware, add this line under `build_flags` in `firmware/platformio.ini` before
 building:
 
 ```ini

T-Display-S3-Pro

@@ -1 +0,0 @@
-Subproject commit bef8db74e847f1e89a10cb3877f3b3a8544857d6

TODO.md

@@ -1,11 +1,5 @@
 # TODO
 
-## Bookmarks and per-book progress
-
-Paragraph-level resume restores the last reading position. Add named bookmarks
-and a compact recent-books/progress list so readers can return to several
-places in a book without overwriting their normal resume point.
-
 ## Reading profiles
 
 Add selectable reading profiles for punctuation and paragraph pause lengths,
@@ -34,38 +28,6 @@ record only when it already exists for style/timing metadata or when an entity
 assignment requires one. Add a persisted reader setting to toggle coloring
 without requiring reconversion.
 
-## Converter preflight and safe section splitting
-
-Add a `--check` mode that reports section word counts, section and sidecar
-sizes, filename issues, and unsupported characters without writing output.
-Offer optional splitting at paragraph boundaries for sections that exceed the
-device's 150,000-word or 1 MiB file limits.
-
-## Memory-limit hardware validation
-
-Stress-test the 150,000-word and 1 MiB section/sidecar limits on real hardware,
-record PSRAM headroom, and lower the supported limit if token indexing or
-sidecar metadata leaves insufficient memory for reliable reading. Include
-adversarial short-word and dense-sidecar inputs, not just ordinary prose.
-
-## Reading continuity preference
-
-Keep the current default of pausing on every chapter title, but add an optional
-auto-continue mode for readers who want uninterrupted reading across sections.
-
-## RSVP orientation point
-
-Offer an optional focal-letter/orientation-point treatment that subtly marks a
-consistent letter within each displayed word. Keep the current centered plain
-word rendering as the default and make the feature work with italic and bold
-fonts.
-
-## Library diagnostics and import validation
-
-Add a device diagnostics screen for SD-card, TOC, missing-section, sidecar,
-and memory-limit errors. Extend converter preflight to report the same issues,
-including oversized tokens, before a book is copied to the card.
-
 ## Add anti-aliased reader fonts
 
 The current reader uses TFT_eSPI's bitmap FreeSans, FreeSerif, and FreeMono