xteink-plugins/README.md

<table>
  <tr>
    <td><img src="screenshot1.jpg?1" height="400"/></td>
    <td><img src="screenshot2.jpg?1" height="400"/></td>
    <td><img src="screenshot3.jpg?1" height="400"/></td>
  </tr>
</table>

# xteink-plugins

A plugin system for customizing and extending https://github.com/crosspoint-reader/crosspoint-reader firmware on your xteink device. Plugins are applied as source-level patches before the firmware is compiled and flashed.

> **Note on this revision:** the plugin installer was rewritten from independent per-plugin `patch.py` scripts (which broke when installed as anything other than "all of them, in this exact order") to a shared declarative framework - see [Why plugin.py instead of patch.py](#why-pluginpy-instead-of-patchpy). Every plugin now installs correctly alone or in any combination. A few honest notes on functional gaps found and decisions made along the way:
> - **Smaller Fonts** actually only implements two states (Disabled/Enabled - one size step down) even though the UI text below describes three; the underlying code never distinguished a "Smallest" tier or handled OpenDyslexic. This rewrite matches what the code actually does rather than inventing the missing tier.
> - **Bookerly** generates 12/14/16/18pt only; the 8pt/10pt claim below wasn't actually wired up in the original code either. Bookerly also won't appear in the font picker on devices that also have SD-card custom fonts installed (a narrow pre-existing edge case).
> - **GitHub Sync**'s original boot hook only ran inside one rare boot path (quick-resume with no cached frame), so it silently never synced on most ordinary boots - it's now a proper once-per-boot hook. Its install-time NVS credential pre-seeding was dropped for simplicity; configure it via Settings → Plugins → GitHub Sync after flashing instead.

## Plugins

### Dark Mode

Adds a Dark Mode option to the Plugins settings tab and the web interface Settings page. When enabled, the screen is inverted after each page render, producing white-on-black text across all reader formats (EPUB, TXT, and XTC).

State | Effect
------|--------
Disabled | Normal display (default)
Enabled | Screen inverted — white text on black background

---

### Smaller Fonts

Adds a Smaller Fonts option to the Plugins settings tab and the web interface Settings page. When enabled, your chosen reader font is transparently substituted with a smaller variant — no need to change your font preference.

Mode | Effect
-----|--------
Disabled | No change (default)
Enabled | Drops the current font size down by one step (e.g. Bookerly 16 → 14)

Supports Noto Serif, Noto Sans, and Bookerly.

---

### Lockscreen

Adds a customizable Lockscreen experience to your xteink device.

This plugin introduces a dedicated lockscreen activity that is shown when the device wakes or powers on.

Features:
- Custom lockscreen activity integrated into firmware
- Four-digit PIN configurable on plugin enable
- Displays on device wake or power-on
- Replaces default wake screen behavior
- Clean UI consistent with CrossPoint Reader

---

### Bookerly Font

Adds the Bookerly font to your xteink device, available as a reader font option alongside the built-in Noto Serif, Noto Sans, and OpenDyslexic fonts.

- Generates Bookerly at 12pt, 14pt, 16pt, and 18pt during install
- Selectable via Settings → Reader → Font
- Works with the Smaller Fonts plugin to drop one size step down (e.g. 16 → 14)

---

### Hardcover Sync

Automatically syncs your reading progress between your xteink device and https://hardcover.app.

- Extracts ISBN metadata from EPUB files to identify books
- Tracks reading progress (page numbers) while you read
- Automatically syncs progress for books with > 0% completion
- Marks books as "Read" when you reach 100%+ completion
- Requires a Hardcover API token configured in Settings

Books without ISBN metadata or at 0% completion are skipped. 100%+ completed books are automatically moved to your "Read" shelf on Hardcover.

Requirements:
- Active internet connection via WiFi
- Hardcover account and API token
- Books with embedded ISBN metadata

---

### GitHub Sync

Syncs `.epub` files from a private GitHub repository to your device on boot.

- Downloads new or updated books from your configured repo automatically on startup
- Skips files already on the device that haven't changed
- Configurable via Settings → Plugins → GitHub Sync (username, personal access token, repo, branch), after flashing

Requirements:
- Active internet connection via WiFi
- GitHub account with a repository containing your `.epub` files
- Personal access token with read-only Contents access to the repo

---

## Requirements

- Python 3.10+
- PlatformIO (pio on your PATH)
- git
- Your xteink device connected via USB

Install Python dependencies with:

pip3 install -r requirements.txt

## Usage

From the root of this repository, run:

python3 install.py

To auto-accept all plugin prompts, pass --yes (or -y):

python3 install.py --yes

By default this uses the default build environment. To use a different environment pass --environment (or -e):

python3 install.py --environment slim
python3 install.py --environment gh_release

Flags can be combined:

python3 install.py -y -e gh_release

Environment | Description
------------|-------------
default | Debug logging enabled, version from current git branch (recommended)
gh_release | Info logging only, version hardcoded to release tag
slim | No serial logging, smallest binary size

The installer will:

1. Clone the CrossPoint Reader source repository
2. Prompt you to select which plugins to install and apply them as patches
3. Build the firmware with PlatformIO
4. Auto-detect your device's serial port and flash the firmware

Note: This script modifies and flashes custom firmware to your device. The author accepts no responsibility for any damage that may occur to your device as a result of using this installer.

## Repository Structure

```
xteink-plugins/
├── install.py              # Interactive installer: clone → select → apply → build → flash
├── framework/               # Shared plugin engine (see "Adding a Plugin" below)
│   ├── manifest.py          # Declarative contribution types plugins are built from
│   ├── engine.py             # Applies every selected plugin's contributions in one pass
│   └── discovery.py          # Finds plugin.py files under plugins/
├── test_harness.py          # Applies every plugin, alone and in combination, against a
│                             # fresh clone and reports pass/fail - run this after adding
│                             # or editing a plugin
└── plugins/
    ├── darkmode/
    │   ├── plugin.py
    │   └── DarkModePlugin.h/.cpp
    ├── smallerfonts/
    │   ├── plugin.py
    │   └── SmallerFontsPlugin.h/.cpp
    ├── lockscreen/
    │   ├── plugin.py
    │   ├── LockscreenPlugin.h/.cpp
    │   └── LockscreenActivity.h/.cpp
    ├── bookerly/
    │   ├── plugin.py
    │   └── BookerlyPlugin.h/.cpp
    ├── hardcover/
    │   ├── plugin.py
    │   ├── HardcoverPlugin.h/.cpp
    │   └── HardcoverSyncActivity.h/.cpp
    ├── githubsync/
    │   ├── plugin.py
    │   ├── GitHubSync.h/.cpp
    │   └── GitHubSyncSettingsActivity.h/.cpp
    └── pong/
        ├── plugin.py
        └── PongActivity.h/.cpp
```

### Why plugin.py instead of patch.py

Previously every plugin's `patch.py` directly rewrote CrossPoint's shared source files with hand-written string edits, and each one had to hardcode knowledge of every *other* plugin's edits to land in the right place (e.g. darkmode's patch literally contained smallerfonts' settings entry). That's fine as long as you always install every plugin together in the same order, but install any subset, or add a new plugin later, and those hardcoded assumptions stop holding - settings referenced fields that were never declared, and the build failed.

`plugin.py` instead returns a declarative `PluginManifest` (see `framework/manifest.py`) describing *what* the plugin needs - a settings field, a row in the on-device "Plugins" tab, a new `SettingAction`, a boot-time hook, and so on. A single engine (`framework/engine.py`) collects the manifests of only the plugins you actually selected and writes each shared file exactly once, built fresh from that selection. Installing 1 plugin or all 7, in any combination, produces internally consistent output every time.

## Troubleshooting

### Linux: Permission denied when flashing

If you see an error like:
Could not open /dev/ttyACM0, the port is busy or doesn't exist
or Permission denied

Run:

sudo usermod -aG dialout $USER

Log out and log back in for the change to take effect, then re-run install.py.

### Windows: 'pio' is not recognized

If you see:
'pio' is not recognized as an internal or external command

Run in PowerShell:

$env:PATH += ";$env:USERPROFILE\.platformio\penv\Scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

If Python was installed from the Microsoft Store:

$scripts = (Get-ChildItem "$env:USERPROFILE\AppData\Local\Packages" -Filter "Scripts" -Recurse -ErrorAction SilentlyContinue | Where-Object { $_.FullName -like "*Python*" } | Select-Object -First 1).FullName
$env:PATH += ";$scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

Restart your terminal and re-run install.py.

## Adding a Plugin

1. Create a new directory under `plugins/` with your plugin's name.
2. Add a `plugin.py` with a `get_manifest(ctx) -> PluginManifest` function. Use an existing plugin (e.g. `plugins/pong/plugin.py` for a simple action-row example, or `plugins/darkmode/plugin.py` for a settings-backed one) as a template. `framework/manifest.py` documents every contribution type: `SettingsField`, `PluginsTabEntry`, `SettingActionEnumValue`, `MainHook`, `ToggleHook`, `TranslationEntry`, and so on.
3. List any plugin-owned `.h`/`.cpp` files under `source_files` so the installer copies them into the firmware tree - you don't touch any shared CrossPoint file directly.
4. Run `python3 test_harness.py <path-to-a-crosspoint-reader-clone> /tmp/scratch <your-plugin-name>` (or `all` to check every plugin and combination) to confirm it applies cleanly alone and alongside everything else, before shipping it.

The installer automatically discovers and offers to install any directory under `plugins/` that contains a `plugin.py` exposing `get_manifest`.