uxjulia · uxjulia · Aug 8, 2026 · Jul 25, 2026 · Jul 25, 2026 · Jul 25, 2026
diff --git a/.claude/CONTEXT.md b/.claude/CONTEXT.md
@@ -2,11 +2,15 @@
 
 Keep this file focused on repo-specific gotchas that are worth reusing in future sessions.
 
+## FreeInk SDK
+
+Refer to https://freeink.org/llms.txt for guidance.
+
 ## Simulator
 
-- Simulator patches belong in the adjacent `crosspoint-simulator` repo.
+- Simulator patches belong in the adjacent `crossink-simulator` repo.
 - The valid local simulator env in this repo is `simulator`, and `pio run -e simulator` currently builds cleanly.
-- The simulator `PNGdec` stub in `crosspoint-simulator/src/PNGdec.h` needs to mirror the real API shape used by app code, including `hasAlpha()` and `getTransparentColor()`, even though decode still fails intentionally.
+- The simulator `PNGdec` stub in `crossink-simulator/src/PNGdec.h` needs to mirror the real API shape used by app code, including `hasAlpha()` and `getTransparentColor()`, even though decode still fails intentionally.
 - Known simulator limits:
   - No image rendering: `platformio.ini` ignores `hal`, `PNGdec`, and `JPEGDEC`, so image decoders are intentionally absent.
   - JPEGDEC stub always fails; `JPEGDEC fallback: open failed (err=-1)` is expected in simulator.
@@ -23,6 +27,19 @@ Keep this file focused on repo-specific gotchas that are worth reusing in future
 - Kindle EPUBs may contain paired high-res and old-Kindle fallback images. `ChapterHtmlSlimParser` should skip `<img>` nodes with `data-AmznRemoved-M8` to avoid duplicate stacked images.
 - After image/layout pipeline changes that affect cached EPUB output, clear the affected `.crosspoint/epub_<hash>/` cache if behavior looks stale.
 
+## UI Consistency
+
+- Use FreeInkUI SDK components and input routing for list-style screens where possible. Row rendering, touch targets,
+  hit testing, and pagination should share the same FreeInkUI list configuration instead of custom touch scaling.
+
+## Heap Baselines (X4 hardware, SD card font)
+
+- A normal resume-into-partial reading session runs at ~85-90KB free / ~49KB maxAlloc by
+  the first watermark crossing (Epub metadata + x-locations + resident glyph caches).
+  Do not read mid-range heap numbers as session degradation without checking the scenario.
+- SD-font section builds cost ~38-50KB at cold start; the 4-style advance-table prewarm
+  (~30KB incl. 16KB contiguous scratch) dominates and is skipped below 80KB free.
+
 ## Misc Repo Gotchas
 
 - POSIX TZ signs are inverted from ISO 8601 in `TimeStore::applyTimezone()`: `"UTC-1"` means UTC+1.

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -14,9 +14,10 @@ body:
       label: Device
       description: Which device is this affecting?
       options:
+        - "--- Select ---"
         - X4
         - X3
-        - Both
+        - Seeed Sticky
     validations:
       required: true
 
@@ -35,6 +36,7 @@ body:
       label: EPUB Optimization
       description: Is your EPUB optimized?
       options:
+        - "--- Select ---"
         - No / Not Applicable
         - Yes, using the built-in web transfer EPUB optimizer
         - Yes, using a different EPUB optimizer
@@ -48,6 +50,7 @@ body:
       label: Cache State
       description: Have you attempted to clear any cached data?
       options:
+        - "--- Select ---"
         - No / Not Applicable
         - Yes, book cache (Reader menu > Delete Book Cache)
         - Yes, reading cache (Settings > System > Clear Reading Cache)
@@ -61,7 +64,7 @@ body:
     attributes:
       label: Describe the Bug
       description: A clear and concise description of what the bug is.
-      placeholder:
+      placeholder: |
     validations:
       required: true
 
@@ -85,6 +88,19 @@ body:
     validations:
       required: true
 
+  - type: dropdown
+    id: epub-attachment
+    attributes:
+      label: File Provided
+      description: If your issue is related to a specific file (EPUB, XTC, etc.), please make sure to attach the exact file in this ticket or email it to julia@uxj.io and reference your issue number. **_EPUBs and XTC files need to be zipped to be attached._**
+      options:
+        - "--- Select ---"
+        - Not Applicable
+        - I've attached it
+        - I've emailed it
+    validations:
+      required: true
+
   - type: textarea
     id: logs
     attributes:

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -65,36 +65,58 @@ jobs:
         run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
 
   build:
-    # Never run untrusted fork PR code on the self-hosted runner.
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
-    runs-on: [self-hosted, linux, crossink-build]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        environment: [default, sticky]
     steps:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
 
-      - name: Verify PlatformIO Core
-        run: pio --version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Cache PlatformIO packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.platformio
+          key: ${{ runner.os }}-platformio-${{ matrix.environment }}-${{ hashFiles('platformio.ini', 'platformio.local.example.ini') }}
+          restore-keys: |
+            ${{ runner.os }}-platformio-${{ matrix.environment }}-
+            ${{ runner.os }}-platformio-
+
+      - name: Install PlatformIO Core
+        run: uv pip install --system -U https://github.com/pioarduino/platformio-core/archive/refs/tags/v6.1.19.zip
 
-      - name: Build CrossInk tiny
+      - name: Build ${{ matrix.environment }} firmware
         run: |
           set -euo pipefail
-          pio run -e tiny | tee pio.log
+          pio run -e ${{ matrix.environment }} | tee pio-${{ matrix.environment }}.log
 
       - name: Extract firmware stats
         run: |
           set -euo pipefail
           {
-            echo "## Firmware build stats"
-            grep -E "RAM:\s|Flash:\s" pio.log | while read -r line; do echo "- ${line}"; done
+            echo "## ${{ matrix.environment }} firmware build stats"
+            grep -E "RAM:\s|Flash:\s" pio-${{ matrix.environment }}.log | while read -r line; do echo "- ${line}"; done
           } >> "$GITHUB_STEP_SUMMARY"
 
       - name: Upload firmware artifacts
+        if: matrix.environment == 'default'
         uses: actions/upload-artifact@v7
         with:
-          name: firmware-tiny
+          name: firmware-x3-x4
           path: |
-            .pio/build/tiny/firmware-tiny.bin
+            .pio/build/default/firmware-x3-x4.bin
           if-no-files-found: error
 
   # This job is used as the PR required actions check, allows for changes to other steps in the future without breaking

diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - "docs/**"
+      - "site/**"
       - ".github/workflows/pages.yml"
   workflow_dispatch:
 
@@ -28,14 +29,21 @@ jobs:
 
       - uses: actions/configure-pages@v6
 
-      - uses: actions/jekyll-build-pages@v1
+      - uses: actions/setup-node@v5
         with:
-          source: ./docs
-          destination: ./_site
+          node-version: 22
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+
+      - run: npm ci
+        working-directory: site
+
+      - run: npm run build
+        working-directory: site
 
       - uses: actions/upload-pages-artifact@v4
         with:
-          path: ./_site
+          path: ./site/dist
 
       - name: Deploy to GitHub Pages
         id: deployment

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -61,16 +61,16 @@ jobs:
 
       - name: Build CrossInk
         env:
-          CROSSPOINT_RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
-        run: pio run -e tiny -e xlarge
+          CROSSINK_RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
+        run: pio run -j1 -e default -e sticky
 
       - name: Generate release catalog
         run: |
           python3 scripts/generate_release_catalog.py \
             --version "${{ env.RELEASE_VERSION }}" \
             --repo "${{ github.repository }}" \
-            --firmware ".pio/build/tiny/firmware-tiny-v${{ env.RELEASE_VERSION }}.bin" \
-            --firmware ".pio/build/xlarge/firmware-xlarge-v${{ env.RELEASE_VERSION }}.bin" \
+            --firmware ".pio/build/default/firmware-x3-x4-v${{ env.RELEASE_VERSION }}.bin" \
+            --firmware ".pio/build/sticky/firmware-sticky-v${{ env.RELEASE_VERSION }}.bin" \
             --output ".pio/build/catalog"
 
       - name: Publish catalog to GitHub Pages source
@@ -113,5 +113,5 @@ jobs:
           target_commitish: ${{ github.sha }}
           draft: true
           files: |
-            .pio/build/tiny/firmware-tiny-v${{ env.RELEASE_VERSION }}.bin
-            .pio/build/xlarge/firmware-xlarge-v${{ env.RELEASE_VERSION }}.bin
+            .pio/build/default/firmware-x3-x4-v${{ env.RELEASE_VERSION }}.bin
+            .pio/build/sticky/firmware-sticky-v${{ env.RELEASE_VERSION }}.bin
diff --git a/.github/workflows/release_candidate.yml b/.github/workflows/release_candidate.yml
@@ -77,18 +77,18 @@ jobs:
           escaped_version=$(printf '%s\n' "$VERSION" | sed 's/[&|]/\\&/g')
           sed -i "s|^crossink_version = .*|crossink_version = ${escaped_version}|" platformio.ini
 
-      - name: Build CrossPoint
+      - name: Build CrossInk
         shell: bash
         env:
-          CROSSPOINT_RC_ARTIFACTS: "1"
-          CROSSPOINT_RC_BRANCH: ${{ env.RC_BRANCH_RAW }}
-          CROSSPOINT_RC_HASH: ${{ env.RC_HASH_SHORT }}
+          CROSSINK_RELEASE_VERSION: "1"
+          CROSSINK_RC_BRANCH: ${{ env.RC_BRANCH_RAW }}
+          CROSSINK_RC_HASH: ${{ env.RC_HASH_SHORT }}
         run: |
           build_args=()
           for env_name in $RC_ENVS; do
             build_args+=(-e "$env_name")
           done
-          pio run "${build_args[@]}"
+          pio run -j1 "${build_args[@]}"
 
       - name: Create GitHub RC Prerelease
         uses: softprops/action-gh-release@v3
@@ -102,5 +102,5 @@ jobs:
           draft: true
           prerelease: true
           files: |
-            .pio/build/tiny/firmware-tiny-${{ env.RC_BRANCH_SAFE }}-${{ env.RC_HASH_SHORT }}-RC.bin
-            .pio/build/xlarge/firmware-xlarge-${{ env.RC_BRANCH_SAFE }}-${{ env.RC_HASH_SHORT }}-RC.bin
+            .pio/build/default/firmware-x3-x4-${{ env.RC_BRANCH_SAFE }}-${{ env.RC_HASH_SHORT }}-RC.bin
+            .pio/build/sticky/firmware-sticky-${{ env.RC_BRANCH_SAFE }}-${{ env.RC_HASH_SHORT }}-RC.bin
diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,12 @@ build
 /.venv
 *.local*
 fs_/
+/site/node_modules/
+/site/dist/
+/site/.astro/
+/site/public/images/
+/site/public/catalog
+/site/public/CNAME
 
 # scratchpad used as release notes for next crossink version
 release.md
@@ -35,4 +41,11 @@ lib/EpdFont/scripts/output/
 /site/public/catalog
 /site/public/CNAME
 
-dist-publish/
+dist-publish/
+
+# Generated by pioarduino when custom_sdkconfig rebuilds the framework.
+/managed_components/
+/.dummy/
+/CMakeLists.txt
+/dependencies.lock
+/sdkconfig.*
diff --git a/AGENTS.md b/AGENTS.md
@@ -3,14 +3,14 @@
 This is the canonical repo instruction file.
 `CLAUDE.md` should point here so Codex and Claude read the same guidance.
 
-Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
+Project: Open-source e-reader firmware for ESP32-C3 and ESP32-S3 devices.
 
 ## Core Rules
 
 - Role: Senior Embedded Systems Engineer for ESP-IDF / Arduino-ESP32 work.
-- The ESP32-C3 has no PSRAM and about 380 KB usable RAM. Stability beats features.
+- Support both constrained ESP32-C3 devices and PSRAM-equipped ESP32-S3 devices. Keep shared code safe for the C3 unless it is explicitly capability-gated; stability beats features.
 - Cite file paths and line numbers before proposing non-trivial changes.
-- Do not assume ESP-IDF or SDK API availability. Verify in `open-x4-sdk/` or the live code.
+- Do not assume ESP-IDF or SDK API availability. Verify in `freeink-sdk/` or the live code.
 - Do not claim performance or memory wins without explaining the mechanism, such as reduced heap churn, flash vs DRAM placement, or smaller stack use.
 - Justify new heap allocations or explain why stack/static storage is not suitable.
 - Explain fixes in plain language where possible, ideally in terms a Node / React developer would follow.
@@ -20,7 +20,6 @@ Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
 
 - Read `.claude/CONTEXT.md` at session start for durable repo-specific gotchas.
 - Keep `.claude/CONTEXT.md` short. Add only reusable findings, not turn-by-turn history.
-- If asked to summarize a session, create `.claude/CONTEXT-YYYY-MM-DD.md` with the relevant findings for that session.
 
 ## Repo Skills
 
@@ -37,10 +36,11 @@ Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
 
 ## Hardware Constraints
 
-- MCU: ESP32-C3, single-core RISC-V at 160 MHz.
-- Display: 800x480 e-ink.
-- Single framebuffer only: `800 * 480 / 8 = 48000` bytes.
-- Storage is SD via SdFat. On real hardware, only one reader can hold a file open at a time.
+- ESP32-C3 targets (Xteink X3/X4): single-core RISC-V at 160 MHz, no PSRAM, and about 380 KB usable internal RAM.
+- ESP32-S3R8 targets (Seeed reTerminal Sticky/Xteink X4 Pro): dual-core Xtensa at up to 240 MHz with 8 MB PSRAM. PSRAM is slower than internal DRAM and is not suitable for every DMA, ISR, or latency-sensitive buffer.
+- Current displays use an 800x480 1-bit e-ink framebuffer: `800 * 480 / 8 = 48000` bytes. Use runtime renderer dimensions because orientation and future device profiles may differ.
+- Use one framebuffer only. C3 targets keep it in internal RAM; current S3 targets place it in PSRAM via `FREEINK_FB_PSRAM`.
+- Storage is exposed through SdFat, but the transport is device-specific (SPI SD on X3/X4/Sticky and SDMMC on X4 Pro). On real hardware, only one reader can hold a file open at a time.
 
 ## Resource Rules
 
@@ -55,6 +55,7 @@ Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
 9. `new` is not nothrow on ESP32. With exceptions disabled, bare `new` calls `abort()` on allocation failure instead of returning `nullptr`. Use `new (std::nothrow)` or `makeUniqueNoThrow<T>()` from `lib/Memory/Memory.h` for fallible allocations.
 10. Prefer `makeUniqueNoThrow<T>()` / `makeUniqueNoThrow<T[]>()` for owned heap allocations so cleanup is automatic on early returns.
 11. Use raw `malloc` or `new (std::nothrow)` only when a C or SDK API takes ownership; add a short comment explaining that ownership transfer.
+12. Treat PSRAM as a device capability, not a universal assumption. Keep shared paths within C3 limits or gate S3-only allocations behind the relevant board/capability macro, and handle PSRAM allocation failure.
 
 ## HAL And Platform Rules
 
@@ -106,13 +107,15 @@ Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
 - Host environment may be macOS, Linux, WSL, or Windows Git Bash. Check `uname -s` before recommending platform-specific shell commands.
 - Logging uses `LOG_INF`, `LOG_DBG`, and `LOG_ERR`.
 - The simulator env in this repo is `simulator`.
-- For simulator work, build from this firmware repo unless the change belongs in `crosspoint-simulator` itself.
+- For simulator work, build from this firmware repo unless the change belongs in `crossink-simulator` itself.
 - Common validation commands:
   - `pio run -e simulator` for simulator-facing UI/reader work.
-  - `pio run -e default` for firmware compile validation.
+  - `pio run -e default` for the ESP32-C3 X3/X4 firmware.
+  - `pio run -e sticky` for the ESP32-S3 Sticky firmware.
+  - `pio run -e x4-pro` for the ESP32-S3 X4 Pro firmware.
   - `pio check -e default --fail-on-defect low --fail-on-defect medium --fail-on-defect high` for static analysis.
   - `find src lib include test -name "*.cpp" -o -name "*.h" | xargs clang-format -i` for formatting touched C++ files.
-- For crash debugging, check serial logs, heap with `ESP.getFreeHeap()`, task stack high-water marks, and whether cache files need clearing.
+- For crash debugging, check serial logs, internal heap with `ESP.getFreeHeap()` and `ESP.getMaxAllocHeap()`, task stack high-water marks, and whether cache files need clearing. On S3 targets, also inspect PSRAM free space and largest allocatable block; abundant PSRAM does not prove that internal-RAM or DMA-capable allocations can succeed.
 - Hardware verification should mention the concrete device path to test, expected UI/log behavior, and any cache reset needed.
 
 ## Generated Files
@@ -131,7 +134,10 @@ Project: Open-source e-reader firmware for Xteink X4 (ESP32-C3).
 ## Git Workflow
 
 - Check `git status --short` before edits and before reporting results. Preserve unrelated user changes.
-- Do not commit unless the user explicitly asks.
+- When resolving merge, rebase, or cherry-pick conflicts, inspect the relevant commit messages for upstream PR references such as `#2608`. Open the PR in its source repository and read its description and changed files before resolving the conflict so the intended behavior is understood.
+- Do not resolve conflicts by automatically keeping CrossInk's current implementation or by discarding the upstream change wholesale. Preserve or adapt the upstream intent unless it is already fully implemented, would introduce a regression, or would substantially and unjustifiably change CrossInk's UX or behavior. When rejecting an upstream change, state the concrete reason.
+- If a referenced PR cannot be accessed, inspect the source commit diff and nearby history, then report that the PR intent could not be verified instead of guessing.
+- Do not commit unless the user explicitly asks or committing is part of the skill utilized.
 - Before staging, ensure ignored/generated/local files such as `.pio/`, `*.generated.h`, `compile_commands.json`, and `platformio.local.ini` are not included.
 - Branch names should use repo-style prefixes such as `feat/`, `fix/`, `docs/`, `refactor/`, `test/`, or `chore/`.
 - Suggested commit messages should follow `<type>: <short summary>`, using types like `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf`.
@@ -150,6 +156,7 @@ When new features are added or issues are fixed, make sure to add an entry to `C
 - The release date of each version is displayed.
 
 ### Types of Changelog Changes
+
 - Added - for new features.
 - Changed - for changes in existing functionality.
 - Deprecated - for soon-to-be removed features.