Preserve eraser state and finish plugin modularization

.github/workflows/tests.yml

@@ -1,14 +1,22 @@
-name: Source checks
+name: Verification and NickelTC build
 
 on:
   push:
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+env:
+  NICKELTC_IMAGE: ghcr.io/pgaskin/nickeltc:1
+  ABI_FIXTURES_URL: https://github.com/MRoiban/KoboNotebookPlus/releases/download/v0.0.1-alpha/KoboNotebookPlus-fw4.38.23697-abi-fixtures.tar.gz
+  ABI_FIXTURES_SHA256: 2e5fe02b15a947d490c2be29d2bda9598a2413eb2369c281b2e1dd9846abb9db
+  BASELINE_URL: https://github.com/MRoiban/KoboNotebookPlus/releases/download/v0.0.1-alpha/KoboNotebookPlus-v0.0.1-alpha-condor-fw4.38.23697-plugin.zip
+  BASELINE_SHA256: 8707bf7c3c3d8c3a06af351f694701f196b1151ffb6974368aec8210aaa54f2b
+
 jobs:
-  python:
+  source-checks:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -19,5 +27,75 @@ jobs:
           python-version: "3.12"
       - name: Compile verification scripts
         run: python -m py_compile scripts/*.py
-      - name: Run artifact-verifier tests
-        run: python scripts/test-verify-layer-artifacts.py
+      - name: Run host verification suite
+        run: make -C mods/custom-notebook-templates check
+
+  firmware-build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ARM inspection tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes binutils-arm-linux-gnueabihf
+          mkdir -p "$RUNNER_TEMP/cross-bin"
+          ln -s "$(command -v arm-linux-gnueabihf-nm)" "$RUNNER_TEMP/cross-bin/nm"
+          ln -s "$(command -v arm-linux-gnueabihf-objdump)" "$RUNNER_TEMP/cross-bin/objdump"
+          echo "$RUNNER_TEMP/cross-bin" >> "$GITHUB_PATH"
+      - name: Fetch checksum-pinned firmware ABI fixtures and baseline
+        run: |
+          mkdir -p extracted/rootfs/usr/local/Kobo ci/baseline
+          curl --fail --location --retry 3 "$ABI_FIXTURES_URL" -o "$RUNNER_TEMP/abi-fixtures.tar.gz"
+          echo "$ABI_FIXTURES_SHA256  $RUNNER_TEMP/abi-fixtures.tar.gz" | sha256sum --check --strict
+          tar -xzf "$RUNNER_TEMP/abi-fixtures.tar.gz" -C extracted/rootfs/usr/local/Kobo
+          curl --fail --location --retry 3 "$BASELINE_URL" -o "$RUNNER_TEMP/baseline.zip"
+          echo "$BASELINE_SHA256  $RUNNER_TEMP/baseline.zip" | sha256sum --check --strict
+          unzip -q "$RUNNER_TEMP/baseline.zip" -d ci/baseline
+          mkdir -p mods/custom-notebook-templates/package
+          cp extracted/rootfs/usr/local/Kobo/libiinknote.so mods/custom-notebook-templates/package/libiinknote.so
+          echo "f80a7de7a1c482173a89b18f2bb8164fcfb53b8fab9b2a75bd23998813a528ea  mods/custom-notebook-templates/package/libiinknote.so" | sha256sum --check --strict
+      - name: Verify firmware ABI pins
+        run: python scripts/verify-layer-abi.py
+      - name: Clean NickelTC build
+        run: docker run --rm -v "$PWD:/work" -w /work "$NICKELTC_IMAGE" make -C mods/custom-notebook-templates clean
+      - name: Compile with NickelTC
+        run: docker run --rm -v "$PWD:/work" -w /work "$NICKELTC_IMAGE" make -C mods/custom-notebook-templates -j2 VERSION="ci-${GITHUB_SHA::12}"
+      - name: Package with NickelTC
+        run: docker run --rm -v "$PWD:/work" -w /work "$NICKELTC_IMAGE" make -C mods/custom-notebook-templates koboroot VERSION="ci-${GITHUB_SHA::12}"
+      - name: Verify compiled preview ABI
+        run: >-
+          python scripts/verify-layer-preview-abi.py
+          mods/custom-notebook-templates/libcustomnotebooktemplates.so
+          --objdump arm-linux-gnueabihf-objdump
+      - name: Verify loader-visible binary parity
+        run: >-
+          python scripts/verify-binary-parity.py
+          ci/baseline/libcustomnotebooktemplates.so
+          mods/custom-notebook-templates/libcustomnotebooktemplates.so
+          --tool-prefix arm-linux-gnueabihf-
+      - name: Validate installer contents and binary identity
+        run: >-
+          python scripts/verify-release-package.py
+          mods/custom-notebook-templates/KoboRoot.tgz
+          mods/custom-notebook-templates/libcustomnotebooktemplates.so
+      - name: Record build checksums
+        run: |
+          sha256sum \
+            mods/custom-notebook-templates/KoboRoot.tgz \
+            mods/custom-notebook-templates/libcustomnotebooktemplates.so \
+            mods/custom-notebook-templates/package/libiinknote.so \
+            | tee SHA256SUMS
+      - uses: actions/upload-artifact@v4
+        with:
+          name: KoboNotebookPlus-${{ github.sha }}
+          path: |
+            mods/custom-notebook-templates/KoboRoot.tgz
+            mods/custom-notebook-templates/libcustomnotebooktemplates.so
+            SHA256SUMS
+          if-no-files-found: error
+          retention-days: 14

CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to KoboNotebookPlus will be documented in this file.
 
+## [0.0.2-alpha] - 2026-07-17
+
+### Fixed
+
+- Preserve the configured eraser width whenever Nickel switches between pen,
+  object eraser, brush eraser, or the stylus hardware eraser.
+- Reapply the eraser policy after firmware tool activation, so the highlighted
+  object/brush mode and the engine's actual erasing behavior stay synchronized.
+- Coalesce a guarded zero-delay replay after tool activation to cover cached
+  erasers which Nickel restyles or replaces later in the same event cycle.
+- Verify that eraser state replay leaves the selected notebook layer unchanged.
+
+### Changed
+
+- Replace the 8,000-line umbrella translation unit and all `.cc.inc` fragments
+  with explicit firmware-resolution, runtime, hook, entry-point, visibility,
+  menu, page, eraser, and layer translation units.
+- Centralize firmware addresses in an immutable pin inventory and keep only two
+  audited process globals (`gPluginState` and NickelHook's `info`).
+- Add `make check` for artifact, binary-parity, globals-budget, and release-
+  package verifier tests.
+- Add GitHub CI which verifies firmware ABI pins, performs a clean NickelTC
+  build, checks preview ABI and loader-visible parity, validates the exact
+  two-file installer, and records SHA-256 checksums.
+
+### Verification
+
+- Tested on Kobo Elipsa 2E (`condor`) firmware `4.38.23697`, including pen and
+  hardware eraser switching, both eraser policies and widths, layer selection,
+  isolated erasing, previews, covers, templates, page tools, and library asset
+  filtering.
+- The release installer remains firmware-specific and contains only the ARM
+  plugin plus the checksum-pinned stock `libiinknote.so`.
+
 ## [0.0.1-alpha] - 2026-07-16
 
 ### Added

README.md

@@ -9,9 +9,48 @@ Elipsa 2E. Instead of overlaying a separate app, it hooks the native notebook
 UI and the MyScript ink engine directly, so layers, previews, and erasing all
 behave like built-in features.
 
-<!-- TODO: add 1–2 photos here — the Layers popup on-device and a custom
-     template/cover. A single picture will sell this better than the list
-     below. -->
+## On-device previews
+
+Click any preview to view it at full size.
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="docs/images/previews/layers.jpg">
+        <img src="docs/images/previews/layers.jpg" width="420" alt="Native Layers popup on a Kobo Elipsa 2E">
+      </a><br>
+      <strong>Native layers</strong>
+    </td>
+    <td align="center">
+      <a href="docs/images/previews/eraser-controls.jpg">
+        <img src="docs/images/previews/eraser-controls.jpg" width="420" alt="Brush and object eraser controls with five eraser sizes">
+      </a><br>
+      <strong>Eraser controls</strong>
+    </td>
+  </tr>
+  <tr>
+    <td align="center">
+      <a href="docs/images/previews/cover-picker.jpg">
+        <img src="docs/images/previews/cover-picker.jpg" width="420" alt="Custom notebook cover picker on a Kobo Elipsa 2E">
+      </a><br>
+      <strong>Custom covers</strong>
+    </td>
+    <td align="center">
+      <a href="docs/images/previews/notebook-menu.jpg">
+        <img src="docs/images/previews/notebook-menu.jpg" width="420" alt="Notebook menu with layers and page operations">
+      </a><br>
+      <strong>Page and notebook tools</strong>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" colspan="2">
+      <a href="docs/images/previews/notebook-library.jpg">
+        <img src="docs/images/previews/notebook-library.jpg" width="420" alt="Kobo notebook library showing a custom checkerboard cover">
+      </a><br>
+      <strong>Custom covers in the notebook library</strong>
+    </td>
+  </tr>
+</table>
 
 > [!CAUTION]
 > This plugin calls private Kobo and MyScript C++ APIs **by firmware
@@ -37,9 +76,10 @@ behave like built-in features.
 
 ## Status
 
-Experimental, source-only — **no stable binary release yet**. The current
-build has passed its host-side ABI, relocation, packaging, and ARM
-disassembly checks; final on-device runtime verification is still pending.
+Experimental alpha. The current release has passed host-side ABI, relocation,
+packaging, ARM disassembly, and on-device feature verification. It is still
+firmware-specific software built on private APIs, not a stable or portable
+Kobo extension.
 
 ## Compatibility
 
@@ -55,13 +95,14 @@ used by the current build is pinned by the verification scripts in
 `scripts/`. Supporting a different firmware requires a fresh binary audit —
 changing only the version check is unsafe.
 
-## Why source-only
+## Release package and source
 
-This repository intentionally contains no Kobo firmware, MyScript libraries,
-Binary Ninja databases, device backups, notebooks, generated plugins, or
-`KoboRoot.tgz`. The install archive embeds a stock `libiinknote.so`, which
-you must extract from firmware you obtained yourself; it must not be
-redistributed here.
+The source repository contains no firmware images, Binary Ninja databases,
+device backups, notebooks, or generated build products. Firmware-pinned alpha
+releases provide a checksum file and a complete `KoboRoot.tgz` containing only
+the ARM plugin and the exact stock `libiinknote.so` required by the supported
+firmware. Source builders can instead supply their own matching firmware
+libraries using the process below.
 
 ## Building
 
@@ -115,9 +156,11 @@ docker run --rm -v "$PWD:/work" -w /work \
 
 ## Installing
 
-Before installing, inspect the built `KoboRoot.tgz` and confirm it contains
-only the compiled ARM plugin and the exact stock library — nothing else.
-Never install a package built for a different firmware.
+Download `KoboRoot.tgz` and its adjacent `.sha256` file from the matching
+[GitHub release](https://github.com/MRoiban/KoboNotebookPlus/releases). Verify
+the checksum before installing. Never install a package built for a different
+device or firmware. Source builders should also inspect the archive and confirm
+it contains only the compiled ARM plugin and the exact stock library.
 
 1. Back up `/mnt/onboard/.kobo/KoboReader.sqlite`, `Kobo eReader.conf`, and
    your notebooks.

mods/custom-notebook-templates/Makefile

@@ -1,9 +1,16 @@
 NICKELHOOK ?= ../../third_party/NickelHook/
 
+ifneq ($(filter check,$(MAKECMDGOALS)),check)
 include $(NICKELHOOK)/NickelHook.mk
+endif
 
 override LIBRARY  := libcustomnotebooktemplates.so
-override SOURCES  += src/customnotebooktemplates.cc
+override SOURCES  += src/firmware_resolver.cc src/fs_util.cc src/settings.cc \
+	src/templates.cc src/covers.cc src/cover_cache.cc src/cover_editor.cc src/page_io.cc \
+	src/notebook_widget.cc src/notebook_hook_services.cc src/notebook_menu.cc src/pages.cc \
+	src/page_actions.cc src/visibility.cc src/eraser_menu.cc src/layers_state.cc \
+	src/layers_service.cc src/layers_preview.cc src/layers_eraser.cc src/layers_menu.cc \
+	src/plugin_runtime.cc src/plugin_entry.cc src/hooks.cc src/visibility_hooks.cc
 override MOCS     += src/covermenureceiver.h
 override PKGCONF  += Qt5Widgets
 override CXXFLAGS += -Wall -Wextra -Werror -Wno-missing-field-initializers \
@@ -14,4 +21,14 @@ override CXXFLAGS += -Wall -Wextra -Werror -Wno-missing-field-initializers \
 # and manifest file untouched.
 override KOBOROOT += package/libiinknote.so:/usr/local/Kobo/libiinknote.so
 
+.PHONY: check
+check:
+	python3 ../../scripts/test-verify-layer-artifacts.py
+	python3 ../../scripts/test-verify-binary-parity.py
+	python3 ../../scripts/test-verify-globals-budget.py
+	python3 ../../scripts/test-verify-release-package.py
+	python3 ../../scripts/verify-globals-budget.py
+
+ifneq ($(filter check,$(MAKECMDGOALS)),check)
 include $(NICKELHOOK)/NickelHook.mk
+endif