diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..187ca843 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,13 @@ +blank_issues_enabled: false +contact_links: + - name: Scope or Roadmap Question (start here if unsure) + url: https://github.com/crosspoint-reader/crosspoint-reader/discussions + about: | + Not sure if your idea fits CrossPoint's scope? Start a Discussion before filing an issue. + See SCOPE.md and ROADMAP.md for what is in, out, and currently paused. + - name: Read the Scope document + url: https://github.com/crosspoint-reader/crosspoint-reader/blob/master/SCOPE.md + about: The authoritative list of what CrossPoint will and will not accept. + - name: Read the Roadmap + url: https://github.com/crosspoint-reader/crosspoint-reader/blob/master/ROADMAP.md + about: Current phase, what is being closed out, and what comes next. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..4838988c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,80 @@ +name: Feature Request +description: Propose a new feature, enhancement, or change to CrossPoint +title: "Short, descriptive title of the request" +labels: ["enhancement", "needs-scope-review"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to propose a change to CrossPoint! + + **Before you continue, please read [SCOPE.md](../blob/master/SCOPE.md) and [ROADMAP.md](../blob/master/ROADMAP.md).** + + CrossPoint is intentionally narrow. Most rejected proposals are rejected for scope reasons that are already + documented. The checklist below exists to save both of us time. + + If you are not sure whether your idea fits, open a [Discussion](../../discussions) first instead of filing + this issue. + + - type: checkboxes + id: scope-check + attributes: + label: Scope Self-Check (required) + description: Please confirm each of the following. If any are unchecked, your issue will likely be closed. + options: + - label: I have read SCOPE.md and ROADMAP.md. + required: true + - label: This is **not** a new theme or theming change (themes are temporarily closed pending the move to SD-loaded themes). + required: true + - label: This is **not** a new external network connector (sync engine, cloud storage, remote file access, OPDS extensions beyond what exists, or any new "talk to a server" feature). + required: true + - label: This is **not** an interactive app (game, calculator, notepad), writing/authoring tool, RSS/news/browser feature, media playback feature, or PDF rendering. + required: true + - label: The stock firmware does **not** already handle this well. + required: true + - label: No other popular CrossPoint fork already handles this well (or, if one does, I explain below why CrossPoint still needs it). + required: true + + - type: textarea + id: problem + attributes: + label: Problem this solves + description: What user-facing problem or reading-experience gap does this address? Be concrete. + placeholder: e.g., "When reading in landscape, paragraph breaks are inconsistent because..." + validations: + required: true + + - type: textarea + id: stock-gap + attributes: + label: Why the stock firmware (and other forks) do not already solve this + description: Explain which existing solutions you checked and why they fall short. This is the core scope filter. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed change + description: A short description of what you would build or change. Focus on user impact; implementation details can come later. + validations: + required: true + + - type: textarea + id: tradeoffs + attributes: + label: Memory / flash / complexity cost + description: | + CrossPoint runs on 380KB of RAM. Roughly how much DRAM, flash, or code complexity does this add? + "Don't know" is a valid answer, but please attempt an estimate. + placeholder: e.g., "Adds ~2KB flash for the new font tables, no DRAM impact at runtime." + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional context + description: Anything else relevant (links, screenshots, related discussions). + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 21b09aaf..0159b9e4 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -3,16 +3,34 @@ * **What is the goal of this PR?** (e.g., Implements the new feature for file uploading.) * **What changes are included?** +## Scope Check + +CrossPoint is intentionally narrow. See [SCOPE.md](../blob/master/SCOPE.md) and [ROADMAP.md](../blob/master/ROADMAP.md). +Please confirm: + +- [ ] I have read SCOPE.md and ROADMAP.md. +- [ ] This PR is **not** a new built-in theme (themes are temporarily closed pending the move to SD-loaded themes). +- [ ] This PR is **not** a new external network connector (sync engine, cloud storage, remote file access, etc.). +- [ ] This PR is **not** an interactive app, writing tool, RSS/news/browser, media playback, or PDF feature. +- [ ] The stock firmware does not already handle this well, **and** no other popular CrossPoint fork already does + (or, if one does, I explain why CrossPoint still needs it below). +- [ ] If this PR touches `freeink-sdk/`, `lib/hal/`, the bootloader, OTA, or recovery code, I have coordinated with + the relevant maintainer. + +**If this PR was opened against the previous (broader) scope and was already in flight under Phase 0, link the +relevant Discussion or issue so reviewers can see the history.** + ## Additional Context -* Add any other information that might be helpful for the reviewer (e.g., performance implications, potential risks, +* Add any other information that might be helpful for the reviewer (e.g., performance implications, potential risks, specific areas to focus on). +* Memory / flash impact, if known. --- ### AI Usage -While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it +While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it helps set the right context for reviewers. Did you use AI tools to help write this code? _**< YES | PARTIALLY | NO >**_ diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..5b0b21f3 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,88 @@ +# CrossPoint Reader Roadmap + +This roadmap describes how CrossPoint is moving through the tighter scope defined in [SCOPE.md](SCOPE.md). It is +intentionally phased: Phase 0 closed out the commitments already in flight before locking down to the stricter +"fill gaps the stock firmware leaves" delineator. + +Phases are sequential. We do not start the next phase until the prior one is wrapped or explicitly carried over. + +--- + +## Phase 0 - Close Out Legacy Scope Items — **COMPLETE** + +**Goal:** Land the work that was already in motion under the prior, broader scope so contributors are not left +hanging, and so we enter the stricter phases with a clean slate. + +**Landed in Phase 0:** + +* **RTL support PRs.** The in-flight right-to-left work was reviewed, iterated, and merged. +* **Dictionary PR.** The offline dictionary lookup work was reviewed and merged. +* **Bookmarks** feature. First-class navigation markers in EPUBs. +* ~~**Transparent sleep screens.**~~ Shelved; not picked back up under the stricter phases. + +Phase 0 is closed. The tighter scope in [SCOPE.md](SCOPE.md) is now fully enforced. "But it was on the old roadmap" +is not a valid argument for accepting a PR. + +--- + +## Phase 1 - Consolidation, Footprint, and Multi-Device Support — **IN PROGRESS** + +**Goal:** Reduce memory and flash usage, clean up the codebase, and land the SDK / HAL generalization work so +CrossPoint runs cleanly on ESP32-based e-reader hardware beyond Xteink (X3 / X4), including ESP32-S3 class devices. + +**Focus areas:** + +* DRAM and heap fragmentation reduction across the reader core. +* Flash footprint reduction (dead code, redundant strings, oversized tables). +* Refactors that tighten the HAL / SDK boundary. +* Pluggable per-device SDK layers (display, input, storage, battery) and per-device build configuration without + forking the reader core. +* Documentation for adding a new ESP32 e-reader target. +* E-ink driver refinement (ghosting, partial update behavior). + +**Closed during this phase:** new themes built into firmware, new external network connectors (sync engines, cloud +storage, remote file access). + +--- + +## Phase 2 - Languages, Fonts, and Themes + +**Goal:** With the codebase smaller and portable, make reading great in every language: multi-language support, +better font support with custom fonts, UI translations, and themes loaded from the SD card instead of consuming +flash. + +**Focus areas:** + +* Multi-language reading support (underserved languages, complex script support where realistic on ESP32 hardware). +* Better font support and custom fonts. +* UI languages and localization. +* Moving themes off-firmware to SD-loaded assets (see SCOPE.md Section 6). +* **Moving hyphenation files off-firmware.** Hyphenation rules vary per language and the files are large (German + alone is ~200KB). Today these eat flash budget that should be available for the reader core. The plan is to build + a downloader analogous to the existing font downloader and store the dictionaries on SD / SPIFFS, loading on + demand. This unlocks better hyphenation for long-word languages (German, Finnish, Norwegian, etc.) without paying + the flash cost up front. + +This phase depends on Phase 1 cleanup landing first; otherwise we generalize a moving target. + +--- + +## Out of Roadmap + +The following are explicitly *not* on the roadmap. They may live in other CrossPoint forks; they will not be picked +up here: + +* Interactive apps (games, calculators, notepads). +* Writing / authoring tools. +* Active connectivity features (RSS, news, browsers). +* PDF rendering as a first-class format. + +See [SCOPE.md](SCOPE.md) for the full rationale. + +--- + +## How This Roadmap Changes + +* Phase boundaries are decided by maintainers, not by individual PRs. +* If a phase needs to be extended or an item carried over, that is documented here with a short note. +* Proposals for new phases or reordering should go through a Discussion first. diff --git a/SCOPE.md b/SCOPE.md index f115e0b4..e380bfee 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -1,62 +1,174 @@ # Project Vision & Scope: CrossPoint Reader -The goal of CrossPoint Reader is to create an efficient, open-source reading experience for the Xteink X4. We believe a -dedicated e-reader should do one thing exceptionally well: **facilitate focused reading.** +The goal of CrossPoint Reader is to create an efficient, open-source reading experience for ESP32-based e-reader +devices. Xteink hardware (X3, X4) is where the project started and remains a primary target, but CrossPoint is +explicitly broadening to support the wider ecosystem of small ESP32 e-ink readers. We believe a dedicated e-reader +should do one thing exceptionally well: **facilitate focused reading.** ## 1. Core Mission -To provide a lightweight, high-performance firmware that maximizes the potential of the X4, prioritizing legibility and -usability over "swiss-army-knife" functionality. +To provide a lightweight, high-performance firmware that maximizes the potential of ESP32-based e-reader hardware, +prioritizing legibility, performance, and usability over "swiss-army-knife" functionality. -## 2. Scope +CrossPoint is **not** a kitchen-sink firmware, and it is **not** Xteink-only. We want clean, maintainable code that +the community can build on, and that runs across the range of ESP32 e-reader devices (ESP32-C3, ESP32-S3, and +adjacent variants). Every accepted change should make that goal easier, not harder. Device-specific code should live +behind the HAL / SDK boundary so the reader core stays portable. + +## 2. Guiding Principle: Fill Gaps the Stock Firmware Leaves + +CrossPoint exists to do the things the stock firmware does poorly or not at all. New work is evaluated against that +delineator: + +* **Does the stock firmware already do this well?** If yes, we will not duplicate it. +* **Is another popular CrossPoint fork already solving this well?** If yes, we generally defer to that fork rather than + fragmenting the ecosystem. +* **Does this directly improve the reading experience or the firmware's long-term maintainability?** If no, it is out + of scope. + +### Language Priority + +English is the priority language for new features and UI work. Other languages are considered, with preference given +to cases where the stock firmware fails (rendering, input, fonts, layout) or where existing CrossPoint forks have not +addressed the gap. + +## 3. Current Focus (Until Further Notice) + +We are intentionally narrowing scope to consolidate the codebase as we open it up to more ESP32 e-reader devices. +During this period, the priorities are: + +* **Memory footprint:** Reducing DRAM usage and heap fragmentation. The ESP32-C3 is the tightest target and sets the + ceiling, but the gains benefit every ESP32 variant we run on. +* **Flash footprint:** Trimming binary size to leave room for additional device targets and features. +* **Code cleanup:** Refactoring, removing dead code, tightening abstractions, and improving readability. +* **Reading experience:** EPUB parsing and rendering, typography, hyphenation, line spacing, font handling, and + legibility improvements. + +### Temporarily Closed Areas + +PRs in the following areas will be closed until this notice is lifted. Adding these now makes the cleanup and +multi-device work materially harder: + +* **New themes.** The existing theming surface is frozen. +* **New external network connectors.** This includes sync engines, cloud storage clients, OPDS extensions beyond what + exists, remote file access, and any new "talk to a server" feature. + +If you are unsure whether your idea falls into one of these categories, open a Discussion first. + +## 4. Scope ### In-Scope -*These are features that directly improve the primary purpose of the device.* +*Features that directly improve the core reading experience or the firmware's maintainability.* -* **User Experience:** E.g. User-friendly interfaces, and interactions, both inside the reader and navigating the - firmware. This includes things like button mapping, book loading, and book navigation like bookmarks. -* **Document Rendering:** E.g. Support for rendering documents (primarily EPUB) and improvements to the rendering - engine. -* **Format Optimization:** E.g. Efficiently parsing EPUB (CSS/Images) and other documents within the device's - capabilities. -* **Typography & Legibility:** E.g. Custom font support, hyphenation engines, and adjustable line spacing. -* **E-Ink Driver Refinement:** E.g. Reducing full-screen flashes (ghosting management) and improving general rendering. -* **Library Management:** E.g. Simple, intuitive ways to organize and navigate a collection of books. -* **Local Transfer:** E.g. Simple, "pull" based book loading via a basic web-server or public and widely-used standards. -* **Language Support:** E.g. Support for multiple languages both in the reader and in the interfaces. -* **Reference Tools:** E.g. Local dictionary lookup. Providing quick, offline definitions to enhance comprehension - without breaking focus. -* **Clock Display (device dependent):** - -| Device | Scope | -| -- | -- | -| X3 | The X3 uses a dedicated DS3231 RTC, which maintains accurate time across sleep cycles and can be treated as a reliable wall clock. | -| X4 | The X4 relies on the ESP32-C3's internal RTC, which drifts significantly during deep sleep. NTP sync could correct this, with an appropriate user experience around connecting to the internet on wake or on demand. This causes some tension with the **Active Connectivity** section below, so please open a discussion about this UX if it's a feature you would find useful. | +* **EPUB Rendering & Optimization:** Improvements to the rendering engine, CSS/image handling, and parsing + performance. +* **Typography & Legibility:** Custom font support, hyphenation, line and paragraph spacing, margins. +* **E-Ink Driver Refinement:** Reducing full-screen flashes (ghosting management) and improving general rendering. +* **Reading UX:** Bookmarks, progress tracking, button mapping, page navigation, and other in-reader interactions. +* **Library Management:** Simple, intuitive ways to organize and navigate a local book collection. +* **Local Transfer:** Simple, pull-based loading via the existing web server or widely used standards. New connectors + are currently paused (see Section 3). +* **Reference Tools:** Local, offline dictionary lookup. +* **Memory, Flash, and Code Quality:** Refactors and cleanups that reduce resource use or improve maintainability, + even without a user-visible feature. ### Out-of-Scope -*These items are rejected because they compromise the device's stability or mission.* +*Rejected because they compromise the device's stability, maintainability, or core mission.* -* **Interactive Apps:** No Notepads, Calculators, or Games. This is a reader, not a PDA. -* **Active Connectivity:** No RSS readers, News aggregators, or Web browsers. Background Wi-Fi tasks drain the battery - and complicate the single-core CPU's execution. -* **Media Playback:** No Audio players or Audio-books. -* **Complex Annotation:** No typed out notes. These features are better suited for devices with better input - capabilities and more powerful chips. +* **Interactive Apps:** No notepads, calculators, or games. These belong in other forks and are not part of + CrossPoint's focus. +* **Writing / Authoring Tools:** No typed notes, journals, or editors. Input hardware and RAM are wrong for this, and + other forks already explore this space. +* **Active Connectivity:** No RSS readers, news aggregators, or web browsers. Background Wi-Fi drains the battery and + complicates the single-core CPU. +* **Media Playback:** No audio players or audiobooks. +* **Complex Annotation:** No typed-out notes. +* **Duplication of stock firmware behavior** that already works well. +* **PDF Rendering:** PDFs are fixed-layout documents, so rendering them requires displaying pages as images rather + than reflowable text, resulting in constant panning and zooming that makes for a poor reading experience on e-ink. + Out of scope on the current hardware class. -### In-scope — Technically Unsupported +## 5. Idea Evaluation -*These features align with CrossPoint's goals but are impractical on the current hardware or produce poor UX.* +Before proposing a feature, ask: -* **PDF Rendering:** PDFs are fixed-layout documents, so rendering them requires displaying pages as images rather than reflowable text — resulting in constant panning and zooming that makes for a poor reading experience on e-ink. +1. Does the stock firmware already handle this well? We should hit that bar or surpass it. +2. Does another popular CrossPoint fork already handle this well? If yes, we usually defer. +3. Does it improve the core reading experience, or reduce memory / flash / code complexity? +4. Is it in one of the temporarily closed areas (new themes, new network connectors)? If yes, wait. +5. Would adding it make the codebase harder to clean up or harder to port to other devices? If yes, rework or defer. -## 3. Idea Evaluation +If the idea passes those filters, it is a candidate. If you are not sure, open a **Discussion** before writing any +code. -While I appreciate the desire to add new and exciting features to CrossPoint Reader, CrossPoint Reader is designed to be -a lightweight, reliable, and performant e-reader. Things which distract or compromise the device's core mission will not -be accepted. As a guiding question, consider if your idea improve the "core reading experience" for the average user, -and, critically, not distract from that reading experience. +> **Note to Contributors:** CrossPoint is intentionally narrow. "It would be cool if..." features are not enough; the +> bar is "this fixes something the stock firmware does poorly, or it makes the firmware leaner and easier to maintain." -> **Note to Contributors:** If you are unsure if your idea fits the scope, please open a **Discussion** before you start -> coding! +## 6. Calls to Action + +These are the areas where contributor help is most valuable right now. If you want to take one of these on, open a +Discussion or issue first so we can coordinate. + +### Theme System: Move Themes Off-Firmware + +We want to abstract themes out of the firmware entirely so they no longer consume flash, and instead load from the SD +card. This directly supports the current focus on flash footprint and code cleanup. + +* **Status:** [@itsthisjustin](https://github.com/itsthisjustin) plans to take this on eventually but is very open to + someone else claiming it sooner. +* **Why it matters:** Every built-in theme costs flash that we would rather spend on rendering, fonts, or future + device support. SD-loaded themes also let users customize without rebuilding firmware. +* **How to claim:** Comment on the relevant Discussion (or open one) before starting. + +### SDK Abstraction: Generalize the Lower Layers for All ESP32 E-Readers + +To support the broader range of ESP32-based e-reader hardware, the SDK layers (display, input, storage, battery, +etc.) need to be abstracted away from Xteink-specific assumptions and made pluggable per device. + +* **Status:** [@itsthisjustin](https://github.com/itsthisjustin) is actively working on this. +* **How to help:** Coordinate with itsthisjustin before opening PRs that touch `freeink-sdk/` or `lib/hal/` so the + work does not collide. Smaller adjacent cleanups (removing hardcoded assumptions, tightening HAL boundaries) are + welcome if scoped against the in-flight direction. + +### Identifying Other Stock-Firmware Gaps + +We want help cataloguing things the stock firmware (and other popular CrossPoint forks) handle poorly or not at all, +so future work has a clear target list. Particularly interested in: + +* **RTL (right-to-left) text support:** Arabic, Hebrew, Persian, and similar scripts. +* **Languages with poor stock and fork coverage:** Especially those that need shaping, complex layout, or + non-Latin font work that nobody is handling well today. +* **Other gaps:** Rendering edge cases, accessibility issues, input quirks, anything stock does badly and existing + forks have not fixed. + +* **Status:** [@uxjulia](https://github.com/uxjulia) is coordinating this effort. + +If you can read or use the device in one of these languages, your feedback (even without code) is genuinely useful. +Open a Discussion with concrete examples (screenshots, sample EPUBs, expected vs actual behavior) and we will +prioritize from there. + +## 7. Funding and Contributor Sustainability + +CrossPoint uses [Royalty.dev](https://royalty.dev) (yes, a product built by [@itsthisjustin](https://github.com/itsthisjustin)) +to fund contributors. There has been some tension in the community around this, so the intent is being clarified +here directly. + +**Why we do this:** + +* To maintain long-term interest from contributors and maintainers, in direct response to substantial community + requests for a way to give back. +* To motivate contributors to invest in the *core* project rather than spinning up competing forks. +* To help pay for new ESP32 devices so we can port CrossPoint to additional hardware. +* To give the project a credible long-term path to sustainability. + +**How it works:** + +* Funds are distributed automatically to contributors based on impact to the codebase and tenure on the project. +* Over **$600** was raised in the first few days after opening up funding, which is a signal the demand is real. +* The exact scoring methodology is published at . + +**This is not fixed in stone.** The weighting, eligibility, and distribution rules can be tweaked as we learn what +works for this project. If you have concerns or suggestions about how funds are allocated, open a Discussion. The +goal is a system that fairly recognizes the people doing the work, not a perfect one on day one.