rsvpreader 1.1.0__tar.gz

rsvpreader-1.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+
+# Personal content: books and the legacy single-script settings file
+book/
+rsvp_settings.json
+
+# Local task tracking (tasks-axi)
+backlog.md
+
+# macOS
+.DS_Store

rsvpreader-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreejit Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rsvpreader-1.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: rsvpreader
+Version: 1.1.0
+Summary: Spritz-style rapid serial visual presentation reader for plain-text books, with a fixed pivot letter and per-book resume.
+Project-URL: Homepage, https://github.com/shreejitverma/rsvpreader
+Project-URL: Repository, https://github.com/shreejitverma/rsvpreader
+Project-URL: Issues, https://github.com/shreejitverma/rsvpreader/issues
+Project-URL: Releases, https://github.com/shreejitverma/rsvpreader/releases
+Author: Shreejit Verma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: reader,rsvp,speed-reading,spritz,tkinter
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# rsvpreader
+
+A Spritz-style rapid serial visual presentation reader for plain-text books.
+It shows one chunk of one to three words at a time with a fixed pivot letter pinned to the center of the screen, or one full sentence at a time, and remembers where you stopped in every book.
+
+[![CI](https://github.com/shreejitverma/rsvpreader/actions/workflows/ci.yml/badge.svg)](https://github.com/shreejitverma/rsvpreader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/rsvpreader)](https://pypi.org/project/rsvpreader/)
+
+## Install and run
+
+Requires Python 3.10 or newer with Tk.
+On macOS, Homebrew's Python ships without Tk; `uv` installs a Python that has it.
+
+From PyPI:
+
+```sh
+uv tool install rsvpreader   # or: pipx install rsvpreader, pip install rsvpreader
+rsvpreader                   # fullscreen, reads ./book
+rsvpreader --windowed        # normal window
+rsvpreader ~/Books           # a different book folder
+```
+
+From a checkout:
+
+```sh
+uv sync
+uv run rsvpreader --windowed
+```
+
+`python rsvpreader.py` works as a launcher from a checkout without installing.
+
+Put `.txt` files, in any folder structure, under `book/` next to where you run the command, or point `RSVPREADER_BOOK_ROOT` or the positional argument at another folder.
+
+## Controls
+
+| Where | Input | Action |
+|---|---|---|
+| Browser | Click, Enter, Space, Right | Open folder or book |
+| Browser | Up, Down | Move selection |
+| Browser | Backspace, Left | Back one folder |
+| Reader | Click, Right, Space | Next chunk or sentence |
+| Reader | Secondary click, Left | Previous chunk or sentence |
+| Reader | Hold click 2 s | Autoplay while held, ramping up to the max WPM over 5 s |
+| Reader | p | Toggle autoplay (same ramp) |
+| Reader | Up, Down | Max WPM plus or minus 10 |
+| Reader | Home, End | First or last unit |
+| Reader | Hold secondary click 3 s | Open settings |
+| Anywhere | s or the gear icon | Toggle settings |
+| Anywhere | Esc | Close settings, else back one level, else leave fullscreen |
+| Anywhere | q | Quit |
+
+Autoplay speed is true words per minute: a three-word chunk is shown three times as long as a single word, and a sentence for as long as its word count implies.
+
+## Settings
+
+Chunk size (1, 2 or 3 words), max autoplay WPM, font family and size, brightness, text color (native color picker) and sentence mode.
+Changes apply live, rebuild the current book without losing your place, and persist to `settings.json` in the user config directory:
+
+| Platform | Location |
+|---|---|
+| macOS | `~/Library/Application Support/rsvpreader/` |
+| Linux | `$XDG_CONFIG_HOME/rsvpreader/` or `~/.config/rsvpreader/` |
+| Windows | `%APPDATA%\rsvpreader\` |
+
+Override with `--config-dir` or `RSVPREADER_CONFIG_DIR`.
+On first run, settings and reading positions are imported from the directory the 1.0.x releases used (`RSVP_READER_CONFIG_DIR` if set, otherwise `rsvp-reader` in the same locations), then from a legacy `rsvp_settings.json` in the working directory.
+Reading positions live in `progress.json` in the same directory, keyed by the book's absolute path.
+
+## How text is chunked
+
+1. Regular punctuation (comma, semicolon, colon, apostrophe, dashes) attaches to its word and never forces a break.
+2. A sentence terminator (`.` `!` `?`) closes the chunk on the word carrying it.
+3. An opening double quote (straight or curly) closes the previous chunk, so the quoted word starts a new one.
+4. A closing double quote closes the chunk on the word carrying it.
+
+Text pasted without spaces is repaired first: `forth,The` becomes `forth, The` and `it."Believe` becomes `it. "Believe`, while `0.99365`, `1,000`, `e.g.` and `7.25p.m.` stay intact.
+Straight double quotes alternate open and close by parity.
+A token with no letters or digits, such as a spaced en dash, glues to the previous word so it never occupies a chunk of its own.
+
+The pivot word is the middle word of a three-word chunk, the word with more letters in a two-word chunk (tie goes to the first), or the only word.
+The pivot letter is the middle letter counting letters only, rounding left for an even count (`Bull` highlights `u`); a word with no letters falls back to its digits.
+
+To inspect the units for any file without opening the GUI:
+
+```sh
+uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --chunk-size 3
+uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --sentences
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest            # unit tests plus Tk smoke tests (skipped without a display)
+uv run ruff check src tests
+uv run ruff format src tests
+uv build                 # sdist and wheel under dist/
+```
+
+CI runs lint and tests on Linux, macOS and Windows for every push and pull request, and builds the wheel on Linux.
+
+### Releasing
+
+The package version lives only in `__version__` in `src/rsvpreader/__init__.py`.
+To release: bump it, merge, then publish a GitHub release whose tag is `v<version>` (for example `v1.0.1`).
+The publish workflow builds the distributions, checks that the tag matches the version, and uploads to PyPI through trusted publishing; no API token is stored anywhere.
+
+Layout under `src/rsvpreader/`:
+
+| Module | Role |
+|---|---|
+| `text.py` | Normalization, tokenization, chunk and sentence building, file decoding |
+| `pivot.py` | Pivot word and letter selection |
+| `session.py` | Reading cursor over units; position survives mode and chunk-size changes |
+| `autoplay.py` | WPM ramp and due-time logic driven by an external clock |
+| `layout.py` | Pivot box and flow-text geometry |
+| `settings.py`, `progress.py`, `storage.py`, `paths.py`, `colors.py` | Validated settings, per-book resume, atomic JSON, config locations, hex color helpers |
+| `library.py` | Folder listing |
+| `app.py`, `browser_view.py`, `reader_view.py`, `settings_panel.py`, `theme.py` | Tk shell and views |
+| `cli.py` | Argument parsing and entry point |
+
+Everything outside the Tk modules is pure and unit tested; the Tk smoke tests drive a real window and assert the rendered pivot geometry from Tk's own bounding boxes.

rsvpreader-1.1.0/README.md

@@ -0,0 +1,122 @@
+# rsvpreader
+
+A Spritz-style rapid serial visual presentation reader for plain-text books.
+It shows one chunk of one to three words at a time with a fixed pivot letter pinned to the center of the screen, or one full sentence at a time, and remembers where you stopped in every book.
+
+[![CI](https://github.com/shreejitverma/rsvpreader/actions/workflows/ci.yml/badge.svg)](https://github.com/shreejitverma/rsvpreader/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/rsvpreader)](https://pypi.org/project/rsvpreader/)
+
+## Install and run
+
+Requires Python 3.10 or newer with Tk.
+On macOS, Homebrew's Python ships without Tk; `uv` installs a Python that has it.
+
+From PyPI:
+
+```sh
+uv tool install rsvpreader   # or: pipx install rsvpreader, pip install rsvpreader
+rsvpreader                   # fullscreen, reads ./book
+rsvpreader --windowed        # normal window
+rsvpreader ~/Books           # a different book folder
+```
+
+From a checkout:
+
+```sh
+uv sync
+uv run rsvpreader --windowed
+```
+
+`python rsvpreader.py` works as a launcher from a checkout without installing.
+
+Put `.txt` files, in any folder structure, under `book/` next to where you run the command, or point `RSVPREADER_BOOK_ROOT` or the positional argument at another folder.
+
+## Controls
+
+| Where | Input | Action |
+|---|---|---|
+| Browser | Click, Enter, Space, Right | Open folder or book |
+| Browser | Up, Down | Move selection |
+| Browser | Backspace, Left | Back one folder |
+| Reader | Click, Right, Space | Next chunk or sentence |
+| Reader | Secondary click, Left | Previous chunk or sentence |
+| Reader | Hold click 2 s | Autoplay while held, ramping up to the max WPM over 5 s |
+| Reader | p | Toggle autoplay (same ramp) |
+| Reader | Up, Down | Max WPM plus or minus 10 |
+| Reader | Home, End | First or last unit |
+| Reader | Hold secondary click 3 s | Open settings |
+| Anywhere | s or the gear icon | Toggle settings |
+| Anywhere | Esc | Close settings, else back one level, else leave fullscreen |
+| Anywhere | q | Quit |
+
+Autoplay speed is true words per minute: a three-word chunk is shown three times as long as a single word, and a sentence for as long as its word count implies.
+
+## Settings
+
+Chunk size (1, 2 or 3 words), max autoplay WPM, font family and size, brightness, text color (native color picker) and sentence mode.
+Changes apply live, rebuild the current book without losing your place, and persist to `settings.json` in the user config directory:
+
+| Platform | Location |
+|---|---|
+| macOS | `~/Library/Application Support/rsvpreader/` |
+| Linux | `$XDG_CONFIG_HOME/rsvpreader/` or `~/.config/rsvpreader/` |
+| Windows | `%APPDATA%\rsvpreader\` |
+
+Override with `--config-dir` or `RSVPREADER_CONFIG_DIR`.
+On first run, settings and reading positions are imported from the directory the 1.0.x releases used (`RSVP_READER_CONFIG_DIR` if set, otherwise `rsvp-reader` in the same locations), then from a legacy `rsvp_settings.json` in the working directory.
+Reading positions live in `progress.json` in the same directory, keyed by the book's absolute path.
+
+## How text is chunked
+
+1. Regular punctuation (comma, semicolon, colon, apostrophe, dashes) attaches to its word and never forces a break.
+2. A sentence terminator (`.` `!` `?`) closes the chunk on the word carrying it.
+3. An opening double quote (straight or curly) closes the previous chunk, so the quoted word starts a new one.
+4. A closing double quote closes the chunk on the word carrying it.
+
+Text pasted without spaces is repaired first: `forth,The` becomes `forth, The` and `it."Believe` becomes `it. "Believe`, while `0.99365`, `1,000`, `e.g.` and `7.25p.m.` stay intact.
+Straight double quotes alternate open and close by parity.
+A token with no letters or digits, such as a spaced en dash, glues to the previous word so it never occupies a chunk of its own.
+
+The pivot word is the middle word of a three-word chunk, the word with more letters in a two-word chunk (tie goes to the first), or the only word.
+The pivot letter is the middle letter counting letters only, rounding left for an even count (`Bull` highlights `u`); a word with no letters falls back to its digits.
+
+To inspect the units for any file without opening the GUI:
+
+```sh
+uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --chunk-size 3
+uv run rsvpreader --dump-chunks "book/selfhelp/some book.txt" --sentences
+```
+
+## Development
+
+```sh
+uv sync
+uv run pytest            # unit tests plus Tk smoke tests (skipped without a display)
+uv run ruff check src tests
+uv run ruff format src tests
+uv build                 # sdist and wheel under dist/
+```
+
+CI runs lint and tests on Linux, macOS and Windows for every push and pull request, and builds the wheel on Linux.
+
+### Releasing
+
+The package version lives only in `__version__` in `src/rsvpreader/__init__.py`.
+To release: bump it, merge, then publish a GitHub release whose tag is `v<version>` (for example `v1.0.1`).
+The publish workflow builds the distributions, checks that the tag matches the version, and uploads to PyPI through trusted publishing; no API token is stored anywhere.
+
+Layout under `src/rsvpreader/`:
+
+| Module | Role |
+|---|---|
+| `text.py` | Normalization, tokenization, chunk and sentence building, file decoding |
+| `pivot.py` | Pivot word and letter selection |
+| `session.py` | Reading cursor over units; position survives mode and chunk-size changes |
+| `autoplay.py` | WPM ramp and due-time logic driven by an external clock |
+| `layout.py` | Pivot box and flow-text geometry |
+| `settings.py`, `progress.py`, `storage.py`, `paths.py`, `colors.py` | Validated settings, per-book resume, atomic JSON, config locations, hex color helpers |
+| `library.py` | Folder listing |
+| `app.py`, `browser_view.py`, `reader_view.py`, `settings_panel.py`, `theme.py` | Tk shell and views |
+| `cli.py` | Argument parsing and entry point |
+
+Everything outside the Tk modules is pure and unit tested; the Tk smoke tests drive a real window and assert the rendered pivot geometry from Tk's own bounding boxes.

rsvpreader-1.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "rsvpreader"
+dynamic = ["version"]
+description = "Spritz-style rapid serial visual presentation reader for plain-text books, with a fixed pivot letter and per-book resume."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Shreejit Verma" }]
+keywords = ["rsvp", "speed-reading", "spritz", "tkinter", "reader"]
+classifiers = [
+  "Environment :: X11 Applications",
+  "Environment :: MacOS X",
+  "Environment :: Win32 (MS Windows)",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.scripts]
+rsvpreader = "rsvpreader.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/shreejitverma/rsvpreader"
+Repository = "https://github.com/shreejitverma/rsvpreader"
+Issues = "https://github.com/shreejitverma/rsvpreader/issues"
+Releases = "https://github.com/shreejitverma/rsvpreader/releases"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/rsvpreader/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rsvpreader"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/rsvpreader", "tests"]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF", "N", "PL"]
+ignore = [
+  "PLR0913", # many keyword args are fine for layout/geometry helpers
+  "PLR2004", # magic numbers in tests and geometry are self-explanatory
+  "RUF001", "RUF002", "RUF003", # typographic quotes and dashes are this project's domain
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["PLR0915"]

rsvpreader-1.1.0/src/rsvpreader/__init__.py

@@ -0,0 +1,8 @@
+"""rsvpreader: a Spritz-style rapid serial visual presentation reader for plain-text books.
+
+The package is split into pure, Tk-free modules (text, pivot, session, autoplay, layout,
+settings, progress, library) and thin Tk views (app, browser_view, reader_view,
+settings_panel). Everything under the pure modules is unit tested without a display.
+"""
+
+__version__ = "1.1.0"

rsvpreader-1.1.0/src/rsvpreader/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m rsvpreader`."""
+
+from rsvpreader.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rsvpreader-1.1.0/src/rsvpreader/app.py

@@ -0,0 +1,234 @@
+"""Application shell: window, navigation stack, settings ownership, key dispatch."""
+
+from __future__ import annotations
+
+import sys
+import tkinter as tk
+import tkinter.font as tkfont
+from pathlib import Path
+
+from rsvpreader.browser_view import FolderView
+from rsvpreader.colors import apply_brightness
+from rsvpreader.progress import ProgressStore
+from rsvpreader.reader_view import ReaderView
+from rsvpreader.settings import Settings, SettingsStore, platform_default_font_family
+from rsvpreader.settings_panel import SettingsPanel
+from rsvpreader.theme import (
+    BG,
+    STATUS_BRIGHTNESS_FACTOR,
+    UI_FONT_CANDIDATES,
+    Theme,
+    resolve_font_family,
+)
+
+WINDOWED_GEOMETRY = "1100x700"
+SETTINGS_SAVE_DEBOUNCE_MS = 300
+GEAR_GLYPH = "⚙"
+REBUILD_KEYS = frozenset({"chunk_size", "sentence_mode"})
+
+
+class App:
+    def __init__(
+        self,
+        root: tk.Tk,
+        *,
+        book_root: Path,
+        settings_store: SettingsStore,
+        progress_store: ProgressStore,
+        fullscreen: bool = True,
+    ) -> None:
+        self.root = root
+        self.book_root = Path(book_root)
+        self.settings_store = settings_store
+        self.progress = progress_store
+        self.installed_fonts = frozenset(tkfont.families(root))
+        self.theme = Theme(resolve_font_family("", self.installed_fonts, UI_FONT_CANDIDATES))
+        self._fonts: dict[tuple[str, int, str], tkfont.Font] = {}
+        self._settings_save_job: str | None = None
+
+        loaded = settings_store.load()
+        self.settings: Settings = loaded.with_changes(
+            font_family=resolve_font_family(
+                loaded.font_family,
+                self.installed_fonts,
+                (platform_default_font_family(), *UI_FONT_CANDIDATES),
+            )
+        )
+
+        root.title("rsvpreader")
+        root.configure(bg=BG)
+        self.is_fullscreen = fullscreen
+        if fullscreen:
+            root.attributes("-fullscreen", True)
+        else:
+            root.geometry(WINDOWED_GEOMETRY)
+
+        self.container = tk.Frame(root, bg=BG)
+        self.container.pack(fill="both", expand=True)
+
+        self.nav_stack: list[tuple[str, Path]] = []
+        self.view: FolderView | ReaderView | None = None
+        self.settings_panel: SettingsPanel | None = None
+        self._gear: tk.Label | None = None
+
+        root.bind("<Escape>", lambda e: self.on_escape())
+        root.bind("<Key>", self._on_key)
+        root.protocol("WM_DELETE_WINDOW", self.quit)
+
+        self.push_folder(self.book_root)
+
+    # -- appearance -----------------------------------------------------------------
+    def accent(self) -> str:
+        return apply_brightness(self.settings.font_color, self.settings.brightness)
+
+    def dim_accent(self) -> str:
+        return apply_brightness(
+            self.settings.font_color, self.settings.brightness * STATUS_BRIGHTNESS_FACTOR
+        )
+
+    def font(self, family: str, size: int, weight: str = "normal") -> tkfont.Font:
+        """Cached named fonts; creating one per redraw would leak Tk font objects."""
+        key = (family, size, weight)
+        if key not in self._fonts:
+            self._fonts[key] = tkfont.Font(root=self.root, family=family, size=size, weight=weight)
+        return self._fonts[key]
+
+    def reader_font(self) -> tkfont.Font:
+        return self.font(self.settings.font_family, self.settings.font_size, "bold")
+
+    # -- navigation --------------------------------------------------------------------
+    def push_folder(self, folder: Path) -> None:
+        self.nav_stack.append(("folder", Path(folder)))
+        self._show_top()
+
+    def open_book(self, book_path: Path) -> None:
+        self.nav_stack.append(("reader", Path(book_path)))
+        self._show_top()
+
+    def _show_top(self, focus: Path | None = None) -> None:
+        """Render the top of the stack; `focus` preselects that entry in a folder view."""
+        self.close_settings_panel()
+        if self.view is not None:
+            self.view.destroy()
+            self.view = None
+        kind, path = self.nav_stack[-1]
+        if kind == "folder":
+            self.view = FolderView(self, self.container, path, focus=focus)
+        else:
+            self.view = ReaderView(self, self.container, path)
+        self._add_gear()
+
+    def on_escape(self) -> None:
+        if self.settings_panel is not None:
+            self.close_settings_panel()
+            return
+        if len(self.nav_stack) > 1:
+            _, left = self.nav_stack.pop()
+            self._show_top(focus=left)
+            return
+        if self.is_fullscreen:
+            self.root.attributes("-fullscreen", False)
+            self.root.geometry(WINDOWED_GEOMETRY)
+            self.is_fullscreen = False
+
+    def quit(self) -> None:
+        if self.view is not None:
+            self.view.destroy()  # the reader view saves its position on destroy
+            self.view = None
+        self._flush_settings_save()
+        self.progress.save()
+        self.root.destroy()
+
+    def _on_key(self, event: tk.Event) -> None:
+        keysym = event.keysym
+        if keysym == "Escape":
+            return  # handled by the dedicated <Escape> binding
+        if event.char == "q":
+            self.quit()
+            return
+        if event.char == "s":
+            self.toggle_settings_panel()
+            return
+        if self.settings_panel is not None:
+            return  # keys belong to the panel's widgets while it is open
+        if self.view is not None:
+            self.view.on_key(event)
+
+    # -- gear icon + settings panel -------------------------------------------------
+    def _add_gear(self) -> None:
+        self._gear = tk.Label(
+            self.container,
+            text=GEAR_GLYPH,
+            font=self.theme.gear,
+            fg=self.accent(),
+            bg=BG,
+            cursor="hand2",
+        )
+        self._gear.place(relx=1.0, rely=0.0, x=-16, y=10, anchor="ne")
+        self._gear.bind("<Button-1>", lambda e: self.toggle_settings_panel())
+
+    def toggle_settings_panel(self) -> None:
+        if self.settings_panel is None:
+            self.open_settings_panel()
+        else:
+            self.close_settings_panel()
+
+    def open_settings_panel(self) -> None:
+        if self.settings_panel is None:
+            self.settings_panel = SettingsPanel(self, self.container)
+
+    def close_settings_panel(self) -> None:
+        if self.settings_panel is not None:
+            self.settings_panel.destroy()
+            self.settings_panel = None
+
+    # -- settings ---------------------------------------------------------------------
+    def update_settings(self, **changes: object) -> None:
+        new = self.settings.with_changes(**changes)
+        if new == self.settings:
+            return
+        rebuild = any(getattr(new, k) != getattr(self.settings, k) for k in REBUILD_KEYS)
+        self.settings = new
+        self._schedule_settings_save()
+        if self.view is not None:
+            self.view.on_settings_changed(rebuild=rebuild)
+        if self._gear is not None:
+            self._gear.configure(fg=self.accent())
+        if self.settings_panel is not None:
+            self.settings_panel.refresh()
+
+    def _schedule_settings_save(self) -> None:
+        if self._settings_save_job is not None:
+            self.root.after_cancel(self._settings_save_job)
+        self._settings_save_job = self.root.after(
+            SETTINGS_SAVE_DEBOUNCE_MS, self._flush_settings_save
+        )
+
+    def _flush_settings_save(self) -> None:
+        if self._settings_save_job is not None:
+            self.root.after_cancel(self._settings_save_job)
+            self._settings_save_job = None
+        self.settings_store.save(self.settings)
+
+
+def run_app(
+    *,
+    book_root: Path,
+    settings_store: SettingsStore,
+    progress_store: ProgressStore,
+    fullscreen: bool,
+) -> int:
+    try:
+        root = tk.Tk()
+    except tk.TclError as exc:
+        print(f"rsvpreader: cannot open a display: {exc}", file=sys.stderr)
+        return 1
+    App(
+        root,
+        book_root=book_root,
+        settings_store=settings_store,
+        progress_store=progress_store,
+        fullscreen=fullscreen,
+    )
+    root.mainloop()
+    return 0