From dbd2f391bddd5b7ca1dfa7d24d8ba5167740ffbf Mon Sep 17 00:00:00 2001 From: Nico Verbruggen Date: Tue, 17 Mar 2026 18:38:54 +0100 Subject: [PATCH] Add more integration tests --- .github/workflows/build.yml | 13 +- README.md | 88 ++-- run-locally.sh => serve-locally.sh | 0 tests/e2e/integration.spec.js | 773 +++++++++++++++++++++++------ tests/e2e/run-e2e-local.sh | 38 -- tests/e2e/run-e2e.sh | 43 +- web/public/css/style.css | 45 +- web/public/index.html | 103 ++-- web/public/js/app.js | 15 +- 9 files changed, 850 insertions(+), 268 deletions(-) rename run-locally.sh => serve-locally.sh (100%) delete mode 100755 tests/e2e/run-e2e-local.sh diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index a55199e..997ef59 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -52,24 +52,29 @@ jobs: GOOS=js GOARCH=wasm go test -exec="$EXEC" ./... - name: Check if integration test is needed - id: check-wasm + id: check-e2e run: | if [[ "${{ github.ref }}" == refs/tags/* ]]; then echo "run=true" >> "$GITHUB_OUTPUT" - elif git diff --name-only HEAD~1 HEAD | grep -q '^kobopatch-wasm/'; then + elif git diff --name-only HEAD~1 HEAD | grep -qE '^(kobopatch-wasm/|web/|tests/|nickelmenu/)'; then echo "run=true" >> "$GITHUB_OUTPUT" else echo "run=false" >> "$GITHUB_OUTPUT" fi - name: Full integration test (WASM) - if: steps.check-wasm.outputs.run == 'true' && env.GITEA_ACTIONS != 'true' + if: steps.check-e2e.outputs.run == 'true' && env.GITEA_ACTIONS != 'true' run: | cd kobopatch-wasm ./test-integration.sh + - name: Set up NickelMenu assets + if: steps.check-e2e.outputs.run == 'true' && env.GITEA_ACTIONS != 'true' + run: | + nickelmenu/setup.sh + - name: Full integration test (Playwright) - if: steps.check-wasm.outputs.run == 'true' && env.GITEA_ACTIONS != 'true' + if: steps.check-e2e.outputs.run == 'true' && env.GITEA_ACTIONS != 'true' run: | cd tests/e2e ./run-e2e.sh diff --git a/README.md b/README.md index 3d25dfb..a1cb95f 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,12 @@ > [!IMPORTANT] > **This is an experiment**, mostly created with the help of Claude and some very precise instructions. It currently only supports the latest version of Kobo's software, and only for the Kobo Libra Color, Kobo Clara Color and Kobo Clara BW models. Further support may be added at a later date. -A web application that provides a GUI for applying custom [kobopatch](https://github.com/pgaskin/kobopatch) patches to Kobo e-readers. It uses the File System Access API (Chromium) to interface with connected Kobo devices, or falls back to manual model/software version selection on other browsers. +A web application for customising Kobo e-readers. It supports two modes: -The app makes it easy to configure which patches to apply, downloads the correct software update from Kobo's servers, runs the patcher (compiled to WebAssembly), and places the resulting `KoboRoot.tgz` on the device. The user then safely ejects and reboots to apply. It can also restore the original unpatched software. +- **NickelMenu** — installs [NickelMenu](https://pgaskin.net/NickelMenu/) with an optional curated configuration (custom menus, fonts, screensavers, UI tweaks). Works with most Kobo devices regardless of software version. Can also remove NickelMenu from a connected device. +- **Custom patches** — applies community [kobopatch](https://github.com/pgaskin/kobopatch) patches to your Kobo's system software. Requires a supported software version and device model. + +The app uses the File System Access API (Chromium) to interface with connected Kobo devices, or falls back to manual model/software version selection with a downloadable ZIP on other browsers. Fully client-side — no backend needed, can be hosted as a static site. Patches are community-contributed via the [MobileRead forums](https://www.mobileread.com/forums/forumdisplay.php?f=247) and need to be manually updated when new Kobo software versions come out. @@ -14,51 +17,57 @@ Fully client-side — no backend needed, can be hosted as a static site. Patches ## User flow -1. **Select device** — auto-detect via File System Access API on Chromium, or manual dropdowns on any browser -2. **Configure patches** — enable/disable patches (PatchGroup mutual exclusion via radio buttons), or select none to restore original unpatched software -3. **Build** — software update is auto-downloaded from Kobo's CDN (`ereaderfiles.kobo.com`, CORS open) and either patched via WASM in a Web Worker, or the original `KoboRoot.tgz` is extracted as-is for restoring -4. **Install** — write `KoboRoot.tgz` directly to the device (Chromium auto mode) or download for manual installation +1. **Connect or download** — auto-detect your Kobo via File System Access API on Chromium, or choose manual download mode (any browser) +2. **Choose mode** — NickelMenu (install/configure/remove) or custom patches +3. **Configure** — for NickelMenu: select install options (fonts, screensaver, tab/homescreen tweaks) or removal; for patches: enable/disable patches (or select none to restore original software) +4. **Review** — confirm your selections before proceeding +5. **Install** — write directly to the device (Chromium auto mode) or download a ZIP/tgz for manual installation ## File structure ``` web/public/ # Webroot — serve this directory - index.html # Single-page app, 4-step wizard (Device → Patches → Build → Install) + index.html # Single-page app, multi-step wizard css/ style.css js/ app.js # Step navigation, flow orchestration, firmware download with progress kobo-device.js # KOBO_MODELS (serial prefix → name), FIRMWARE_DOWNLOADS (version+prefix → URL), # getDevicesForVersion(), getFirmwareURL(), KoboDevice class (File System Access API) + nickelmenu.js # NickelMenuInstaller: downloads NickelMenu.zip + kobo-config.zip, installs to + # device or builds download ZIP, handles config file filtering and modification patch-ui.js # PatchUI class: loads patch zips (JSZip), parses YAML, renders toggle UI, # generates kobopatch.yaml config with overrides kobopatch.js # KobopatchRunner: spawns Web Worker per build, handles progress/done/error messages patch-worker.js # Web Worker: loads wasm_exec.js + kobopatch.wasm, runs patchFirmware(), # posts progress back, transfers result buffer zero-copy wasm_exec.js # Go WASM support runtime (copied from Go SDK by setup.sh, gitignored) + jszip.min.js # Bundled JSZip library wasm/ kobopatch.wasm # Compiled WASM binary (built by build.sh, gitignored) patches/ index.json # Contains a list of available patches patches_*.zip # Each contains kobopatch.yaml + src/*.yaml patch files + nickelmenu/ # NickelMenu assets (built by nickelmenu/setup.sh, gitignored) + NickelMenu.zip # NickelMenu release + kobo-config.zip # Curated configuration files (fonts, screensaver, menu items) + +nickelmenu/ + setup.sh # Downloads NickelMenu.zip and bundles kobo-config.zip from kobo-config repo kobopatch-wasm/ # WASM build main.go # Go entry point: jsPatchFirmware() → patchFirmware() pipeline - # Accepts configYAML, firmwareZip, patchFiles, optional progressFn - # Returns { tgz: Uint8Array, log: string } go.mod setup.sh # Clones kobopatch source, copies wasm_exec.js - build.sh # GOOS=js GOARCH=wasm go build, copies .wasm to web/public/wasm/, - # sets ?ts= cache-bust timestamp in js/patch-worker.js + build.sh # GOOS=js GOARCH=wasm go build, copies .wasm to web/public/wasm/ integration_test.go # Go integration test: validates SHA1 checksums of patched binaries test-integration.sh # Downloads firmware and runs integration_test.go tests/ e2e/ # Playwright E2E tests - integration.spec.js # Full browser pipeline test (patch + restore) + integration.spec.js # Full browser tests: NickelMenu flows, custom patches, mock device playwright.config.js - run-e2e.sh # Headless E2E runner (downloads firmware, installs browser) - run-e2e-local.sh # Headed E2E runner (visible browser window) + run-e2e.sh # E2E runner (downloads firmware, sets up NickelMenu assets, installs browser) ``` ## Adding a new software version @@ -77,41 +86,60 @@ cd kobopatch-wasm ./build.sh # compiles WASM, copies to web/public/wasm/ ``` +## Setting up NickelMenu assets + +```bash +nickelmenu/setup.sh +``` + +This downloads `NickelMenu.zip` and clones/updates the [kobo-config](https://github.com/nicoverbruggen/kobo-config) repo to bundle `kobo-config.zip` into `web/public/nickelmenu/`. + ## Running locally ```bash ./run-locally.sh ``` -This serves the app at `http://localhost:8888`. If the WASM binary hasn't been built yet, the script automatically runs `setup.sh` and `build.sh` first. +This serves the app at `http://localhost:8888`. If the WASM binary or NickelMenu assets haven't been set up yet, the script handles that automatically. ## Testing -To further validate the patched `KoboRoot.tgz` packages are identical to what a local version of `kobopatch` would generate, two integration tests have been added. +### E2E tests (Playwright) -Both integration tests run the full patching pipeline with software version 4.45.23646 (Kobo Libra Color), enable a single patch, and verify SHA1 checksums of all 4 patched binaries. The software update zip (~150MB) is downloaded once and cached in `kobopatch-wasm/testdata/`. +The E2E tests cover all major user flows: -The reason this particular combination is used is simple: the author has actually used that specific version on an actual device before and it's a known, working, patched version of the software. So comparing hashes against it seems like a good idea. +- **NickelMenu** — install with config (manual download), install NickelMenu only, remove option disabled without device +- **Custom patches** — full patching pipeline, restore original firmware +- **With simulated Kobo Libra Color** — install NickelMenu with config, remove NickelMenu, install custom patches, restore firmware -**WASM integration test** — calls `patchFirmware()` directly in Go/WASM via Node.js: +The simulated device tests mock the File System Access API with an in-memory filesystem that mimics a Kobo Libra Color (serial prefix N428, firmware 4.45.23646). -```bash -cd kobopatch-wasm -./test-integration.sh -``` - -**Playwright E2E test** — drives the full browser UI (manual mode, headless): +Custom patches tests download firmware 4.45.23646 (~150MB, cached in `kobopatch-wasm/testdata/`), enable a single patch, and verify SHA1 checksums of all 4 patched binaries. This specific combination is used because the author has tested it on an actual device. ```bash cd tests/e2e ./run-e2e.sh ``` -To run the Playwright test with a visible browser window: +To run with a visible browser window: ```bash -cd tests/e2e -./run-e2e-local.sh +./run-e2e.sh --headed +``` + +Extra Playwright arguments can be passed after `--`: + +```bash +./run-e2e.sh --headed -- --grep "NickelMenu" +``` + +### WASM integration test + +Calls `patchFirmware()` directly in Go/WASM via Node.js: + +```bash +cd kobopatch-wasm +./test-integration.sh ``` ## Output validation @@ -124,8 +152,8 @@ The WASM patcher performs several checks on each patched binary before including ## Credits -Built on [kobopatch](https://github.com/pgaskin/kobopatch) by pgaskin. Patches and discussion on the [MobileRead forums](https://www.mobileread.com/forums/forumdisplay.php?f=247). +Built on [kobopatch](https://github.com/pgaskin/kobopatch) and [NickelMenu](https://pgaskin.net/NickelMenu/) by pgaskin. Uses [JSZip](https://stuk.github.io/jszip/) for client-side ZIP handling. Software patches and discussion on the [MobileRead forums](https://www.mobileread.com/forums/forumdisplay.php?f=247). ## License -[MIT](LICENSE) +[MIT](LICENSE). diff --git a/run-locally.sh b/serve-locally.sh similarity index 100% rename from run-locally.sh rename to serve-locally.sh diff --git a/tests/e2e/integration.spec.js b/tests/e2e/integration.spec.js index b8664a7..2e6a5e3 100644 --- a/tests/e2e/integration.spec.js +++ b/tests/e2e/integration.spec.js @@ -17,7 +17,11 @@ const EXPECTED_SHA1 = { const FIRMWARE_PATH = process.env.FIRMWARE_ZIP || path.resolve(__dirname, '..', '..', 'kobopatch-wasm', 'testdata', 'kobo-update-4.45.23646.zip'); -const WEBROOT_FIRMWARE = path.resolve(__dirname, '..', '..', 'web', 'public', '_test_firmware.zip'); +const WEBROOT = path.resolve(__dirname, '..', '..', 'web', 'public'); +const WEBROOT_FIRMWARE = path.join(WEBROOT, '_test_firmware.zip'); + +// SHA1 of the original unmodified KoboRoot.tgz inside firmware 4.45.23646. +const ORIGINAL_TGZ_SHA1 = 'b5c3307e8e7ec036f4601135f0b741c37b899db4'; /** * Parse a tar archive (uncompressed) and return a map of entry name -> Buffer. @@ -51,27 +55,33 @@ function parseTar(buffer) { return entries; } -// SHA1 of the original unmodified KoboRoot.tgz inside firmware 4.45.23646. -const ORIGINAL_TGZ_SHA1 = 'b5c3307e8e7ec036f4601135f0b741c37b899db4'; - -// Clean up the symlink after the test. +// Clean up the symlink after each test. test.afterEach(() => { try { fs.unlinkSync(WEBROOT_FIRMWARE); } catch {} }); -test('full manual mode patching pipeline', async ({ page }) => { - if (!fs.existsSync(FIRMWARE_PATH)) { - test.skip(true, `Firmware not found at ${FIRMWARE_PATH}`); - } - - // Symlink the cached firmware into the webroot so the app can fetch it locally. - try { fs.unlinkSync(WEBROOT_FIRMWARE); } catch {} - fs.symlinkSync(path.resolve(FIRMWARE_PATH), WEBROOT_FIRMWARE); +/** + * Check that NickelMenu assets exist in webroot. + */ +function hasNickelMenuAssets() { + return fs.existsSync(path.join(WEBROOT, 'nickelmenu', 'NickelMenu.zip')) + && fs.existsSync(path.join(WEBROOT, 'nickelmenu', 'kobo-config.zip')); +} +/** + * Navigate to manual mode: click "Download files manually" on the connect step. + */ +async function goToManualMode(page) { await page.goto('/'); await expect(page.locator('h1')).toContainText('KoboPatch'); + await page.click('#btn-manual'); + await expect(page.locator('#step-mode')).not.toBeHidden(); +} - // Override the firmware download URLs to point at the local server. +/** + * Override firmware download URLs to point at the local test server. + */ +async function overrideFirmwareURLs(page) { await page.evaluate(() => { for (const version of Object.keys(FIRMWARE_DOWNLOADS)) { for (const prefix of Object.keys(FIRMWARE_DOWNLOADS[version])) { @@ -79,149 +89,630 @@ test('full manual mode patching pipeline', async ({ page }) => { } } }); +} - // Step 1: Switch to manual mode. - await page.click('#btn-manual-from-auto'); - await expect(page.locator('#step-manual')).not.toBeHidden(); - - // Step 2: Select firmware version. - await page.selectOption('#manual-version', '4.45.23646'); - await expect(page.locator('#manual-model')).not.toBeHidden(); - - // Step 3: Select Kobo Libra Colour (N428). - await page.selectOption('#manual-model', 'N428'); - await expect(page.locator('#btn-manual-confirm')).toBeEnabled(); - await page.click('#btn-manual-confirm'); - - // Step 4: Wait for patches to load. - await expect(page.locator('#step-patches')).not.toBeHidden(); - await expect(page.locator('#patch-container .patch-file-section')).not.toHaveCount(0); - - // Step 5: Enable "Remove footer (row3) on new home screen". - const patchName = page.locator('.patch-name', { hasText: 'Remove footer (row3) on new home screen' }).first(); - const patchSection = patchName.locator('xpath=ancestor::details'); - await patchSection.locator('summary').click(); - await expect(patchName).toBeVisible(); - await patchName.locator('xpath=ancestor::label').locator('input').check(); - - // Verify patch count updated. - await expect(page.locator('#patch-count-hint')).toContainText('1 patch selected'); - await expect(page.locator('#btn-patches-next')).toBeEnabled(); - - // Step 6: Continue to build step. - await page.click('#btn-patches-next'); - await expect(page.locator('#step-firmware')).not.toBeHidden(); - await expect(page.locator('#firmware-version-label')).toHaveText('4.45.23646'); - await expect(page.locator('#firmware-device-label')).toHaveText('Kobo Libra Colour'); - - // Step 7: Build and wait for completion. - await page.click('#btn-build'); - - const doneOrError = await Promise.race([ - page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), - page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), - ]); - - if (doneOrError === 'error') { - const errorMsg = await page.locator('#error-message').textContent(); - throw new Error(`Build failed: ${errorMsg}`); - } - - await expect(page.locator('#build-status')).toContainText('Patching complete'); - await expect(page.locator('#build-status')).toContainText('Kobo Libra Colour'); - - // Step 8: Download KoboRoot.tgz and verify checksums. - const [download] = await Promise.all([ - page.waitForEvent('download'), - page.click('#btn-download'), - ]); - - expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); - await expect(page.locator('#download-device-name')).toHaveText('Kobo Libra Colour'); - - const downloadPath = await download.path(); - const tgzData = fs.readFileSync(downloadPath); - - const tarData = zlib.gunzipSync(tgzData); - const entries = parseTar(tarData); - - for (const [name, expectedHash] of Object.entries(EXPECTED_SHA1)) { - const data = entries[name]; - expect(data, `missing binary in output: ${name}`).toBeDefined(); - const actualHash = crypto.createHash('sha1').update(data).digest('hex'); - expect(actualHash, `SHA1 mismatch for ${name}`).toBe(expectedHash); - } -}); - -test('restore original firmware pipeline', async ({ page }) => { - if (!fs.existsSync(FIRMWARE_PATH)) { - test.skip(true, `Firmware not found at ${FIRMWARE_PATH}`); - } - - // Symlink the cached firmware into the webroot so the app can fetch it locally. +/** + * Set up firmware symlink for tests that need it. + */ +function setupFirmwareSymlink() { try { fs.unlinkSync(WEBROOT_FIRMWARE); } catch {} fs.symlinkSync(path.resolve(FIRMWARE_PATH), WEBROOT_FIRMWARE); +} - await page.goto('/'); - await expect(page.locator('h1')).toContainText('KoboPatch'); +// ============================================================ +// NickelMenu tests +// ============================================================ - // Override the firmware download URLs to point at the local server. - await page.evaluate(() => { - for (const version of Object.keys(FIRMWARE_DOWNLOADS)) { - for (const prefix of Object.keys(FIRMWARE_DOWNLOADS[version])) { - FIRMWARE_DOWNLOADS[version][prefix] = '/_test_firmware.zip'; - } +test.describe('NickelMenu', () => { + test('no device — install NickelMenu with config via manual download', async ({ page }) => { + test.skip(!hasNickelMenuAssets(), 'NickelMenu assets not found in webroot'); + + await goToManualMode(page); + + // Mode selection: NickelMenu should be pre-selected (checked in HTML) + await expect(page.locator('input[name="mode"][value="nickelmenu"]')).toBeChecked(); + await page.click('#btn-mode-next'); + + // NickelMenu configure step + await expect(page.locator('#step-nickelmenu')).not.toBeHidden(); + + // No option pre-selected — Continue should be disabled + await expect(page.locator('#btn-nm-next')).toBeDisabled(); + + // Select "Install NickelMenu and configure" + await page.click('input[name="nm-option"][value="sample"]'); + await expect(page.locator('#nm-config-options')).not.toBeHidden(); + + // Verify default checkbox states + await expect(page.locator('input[name="nm-cfg-fonts"]')).toBeChecked(); + await expect(page.locator('input[name="nm-cfg-screensaver"]')).not.toBeChecked(); + await expect(page.locator('input[name="nm-cfg-simplify-tabs"]')).not.toBeChecked(); + await expect(page.locator('input[name="nm-cfg-simplify-home"]')).not.toBeChecked(); + + await expect(page.locator('#btn-nm-next')).toBeEnabled(); + await page.click('#btn-nm-next'); + + // Review step + await expect(page.locator('#step-nm-review')).not.toBeHidden(); + await expect(page.locator('#nm-review-list')).toContainText('NickelMenu'); + await expect(page.locator('#nm-review-list')).toContainText('Readerly fonts'); + + // Write button should be hidden in manual mode + await expect(page.locator('#btn-nm-write')).toBeHidden(); + // Download button visible + await expect(page.locator('#btn-nm-download')).toBeVisible(); + + // Click download and wait for done step + await page.click('#btn-nm-download'); + await expect(page.locator('#step-nm-done')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('#nm-done-status')).toContainText('ready to download'); + + // Download instructions should be visible, and include eReader.conf step for sample config + await expect(page.locator('#nm-download-instructions')).not.toBeHidden(); + await expect(page.locator('#nm-download-conf-step')).not.toBeHidden(); + }); + + test('no device — install NickelMenu only via manual download', async ({ page }) => { + test.skip(!hasNickelMenuAssets(), 'NickelMenu assets not found in webroot'); + + await goToManualMode(page); + await page.click('#btn-mode-next'); + await expect(page.locator('#step-nickelmenu')).not.toBeHidden(); + + // Select "Install NickelMenu only" + await page.click('input[name="nm-option"][value="nickelmenu-only"]'); + await expect(page.locator('#nm-config-options')).toBeHidden(); + + await page.click('#btn-nm-next'); + + // Review step + await expect(page.locator('#step-nm-review')).not.toBeHidden(); + await expect(page.locator('#nm-review-list')).toContainText('NickelMenu (KoboRoot.tgz)'); + + // Download + await page.click('#btn-nm-download'); + await expect(page.locator('#step-nm-done')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('#nm-done-status')).toContainText('ready to download'); + + // eReader.conf step should be hidden for nickelmenu-only + await expect(page.locator('#nm-download-conf-step')).toBeHidden(); + }); + + test('no device — remove NickelMenu option is disabled in manual mode', async ({ page }) => { + test.skip(!hasNickelMenuAssets(), 'NickelMenu assets not found in webroot'); + + await goToManualMode(page); + await page.click('#btn-mode-next'); + await expect(page.locator('#step-nickelmenu')).not.toBeHidden(); + + // Remove option should be disabled (no device connected) + await expect(page.locator('#nm-option-remove')).toHaveClass(/nm-option-disabled/); + await expect(page.locator('input[name="nm-option"][value="remove"]')).toBeDisabled(); + }); +}); + +// ============================================================ +// Custom patches tests +// ============================================================ + +test.describe('Custom patches', () => { + test('no device — full manual mode patching pipeline', async ({ page }) => { + test.skip(!fs.existsSync(FIRMWARE_PATH), `Firmware not found at ${FIRMWARE_PATH}`); + + setupFirmwareSymlink(); + await goToManualMode(page); + + // Select "Custom Patches" mode + await page.click('input[name="mode"][value="patches"]'); + await page.click('#btn-mode-next'); + + // Manual version/model selection + await expect(page.locator('#step-manual-version')).not.toBeHidden(); + + await overrideFirmwareURLs(page); + + // Select firmware version + await page.selectOption('#manual-version', '4.45.23646'); + await expect(page.locator('#manual-model')).not.toBeHidden(); + + // Select Kobo Libra Colour (N428) + await page.selectOption('#manual-model', 'N428'); + await expect(page.locator('#btn-manual-confirm')).toBeEnabled(); + await page.click('#btn-manual-confirm'); + + // Wait for patches to load + await expect(page.locator('#step-patches')).not.toBeHidden(); + await expect(page.locator('#patch-container .patch-file-section')).not.toHaveCount(0); + + // Enable "Remove footer (row3) on new home screen" + const patchName = page.locator('.patch-name', { hasText: 'Remove footer (row3) on new home screen' }).first(); + const patchSection = patchName.locator('xpath=ancestor::details'); + await patchSection.locator('summary').click(); + await expect(patchName).toBeVisible(); + await patchName.locator('xpath=ancestor::label').locator('input').check(); + + // Verify patch count + await expect(page.locator('#patch-count-hint')).toContainText('1 patch selected'); + await expect(page.locator('#btn-patches-next')).toBeEnabled(); + + // Continue to build step + await page.click('#btn-patches-next'); + await expect(page.locator('#step-firmware')).not.toBeHidden(); + await expect(page.locator('#firmware-version-label')).toHaveText('4.45.23646'); + await expect(page.locator('#firmware-device-label')).toHaveText('Kobo Libra Colour'); + + // Build and wait for completion + await page.click('#btn-build'); + + const doneOrError = await Promise.race([ + page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), + page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), + ]); + + if (doneOrError === 'error') { + const errorMsg = await page.locator('#error-message').textContent(); + throw new Error(`Build failed: ${errorMsg}`); + } + + await expect(page.locator('#build-status')).toContainText('Patching complete'); + await expect(page.locator('#build-status')).toContainText('Kobo Libra Colour'); + + // Download KoboRoot.tgz and verify checksums + const [download] = await Promise.all([ + page.waitForEvent('download'), + page.click('#btn-download'), + ]); + + expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); + await expect(page.locator('#download-device-name')).toHaveText('Kobo Libra Colour'); + + const downloadPath = await download.path(); + const tgzData = fs.readFileSync(downloadPath); + + const tarData = zlib.gunzipSync(tgzData); + const entries = parseTar(tarData); + + for (const [name, expectedHash] of Object.entries(EXPECTED_SHA1)) { + const data = entries[name]; + expect(data, `missing binary in output: ${name}`).toBeDefined(); + const actualHash = crypto.createHash('sha1').update(data).digest('hex'); + expect(actualHash, `SHA1 mismatch for ${name}`).toBe(expectedHash); } }); - // Step 1: Switch to manual mode. - await page.click('#btn-manual-from-auto'); - await expect(page.locator('#step-manual')).not.toBeHidden(); + test('no device — restore original firmware pipeline', async ({ page }) => { + test.skip(!fs.existsSync(FIRMWARE_PATH), `Firmware not found at ${FIRMWARE_PATH}`); - // Step 2: Select firmware version. - await page.selectOption('#manual-version', '4.45.23646'); - await expect(page.locator('#manual-model')).not.toBeHidden(); + setupFirmwareSymlink(); + await goToManualMode(page); - // Step 3: Select Kobo Libra Colour (N428). - await page.selectOption('#manual-model', 'N428'); - await expect(page.locator('#btn-manual-confirm')).toBeEnabled(); - await page.click('#btn-manual-confirm'); + // Select "Custom Patches" mode + await page.click('input[name="mode"][value="patches"]'); + await page.click('#btn-mode-next'); - // Step 4: Wait for patches to load, then continue with zero patches selected. - await expect(page.locator('#step-patches')).not.toBeHidden(); - await expect(page.locator('#patch-container .patch-file-section')).not.toHaveCount(0); - await expect(page.locator('#patch-count-hint')).toContainText('restore the original'); - await page.click('#btn-patches-next'); + // Manual version/model selection + await expect(page.locator('#step-manual-version')).not.toBeHidden(); - // Step 5: Verify build step shows restore text. - await expect(page.locator('#step-firmware')).not.toBeHidden(); - await expect(page.locator('#firmware-description')).toContainText('without modifications'); - await expect(page.locator('#btn-build')).toContainText('Restore Original Software'); + await overrideFirmwareURLs(page); - // Step 6: Build and wait for completion. - await page.click('#btn-build'); + await page.selectOption('#manual-version', '4.45.23646'); + await page.selectOption('#manual-model', 'N428'); + await page.click('#btn-manual-confirm'); - const doneOrError = await Promise.race([ - page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), - page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), - ]); + // Wait for patches to load, then continue with zero patches + await expect(page.locator('#step-patches')).not.toBeHidden(); + await expect(page.locator('#patch-container .patch-file-section')).not.toHaveCount(0); + await expect(page.locator('#patch-count-hint')).toContainText('restore the original'); + await page.click('#btn-patches-next'); - if (doneOrError === 'error') { - const errorMsg = await page.locator('#error-message').textContent(); - throw new Error(`Restore failed: ${errorMsg}`); - } + // Verify build step shows restore text + await expect(page.locator('#step-firmware')).not.toBeHidden(); + await expect(page.locator('#firmware-description')).toContainText('without modifications'); + await expect(page.locator('#btn-build')).toContainText('Restore Original Software'); - await expect(page.locator('#build-status')).toContainText('Software extracted'); + // Build and wait for completion + await page.click('#btn-build'); - // Step 7: Download KoboRoot.tgz and verify it matches the original. - const [download] = await Promise.all([ - page.waitForEvent('download'), - page.click('#btn-download'), - ]); + const doneOrError = await Promise.race([ + page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), + page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), + ]); - expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); - const downloadPath = await download.path(); - const tgzData = fs.readFileSync(downloadPath); - const actualHash = crypto.createHash('sha1').update(tgzData).digest('hex'); - expect(actualHash, 'restored KoboRoot.tgz SHA1 mismatch').toBe(ORIGINAL_TGZ_SHA1); + if (doneOrError === 'error') { + const errorMsg = await page.locator('#error-message').textContent(); + throw new Error(`Restore failed: ${errorMsg}`); + } + + await expect(page.locator('#build-status')).toContainText('Software extracted'); + + // Download KoboRoot.tgz and verify it matches the original + const [download] = await Promise.all([ + page.waitForEvent('download'), + page.click('#btn-download'), + ]); + + expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); + const downloadPath = await download.path(); + const tgzData = fs.readFileSync(downloadPath); + const actualHash = crypto.createHash('sha1').update(tgzData).digest('hex'); + expect(actualHash, 'restored KoboRoot.tgz SHA1 mismatch').toBe(ORIGINAL_TGZ_SHA1); + }); + + test('no device — custom patches not available disables patches card', async ({ page }) => { + await page.goto('/'); + + // In manual mode, NickelMenu should always be available, + // but custom patches card should be selectable in mode screen + await page.click('#btn-manual'); + await expect(page.locator('#step-mode')).not.toBeHidden(); + + // Both modes should be available in manual mode + await expect(page.locator('input[name="mode"][value="patches"]')).not.toBeDisabled(); + await expect(page.locator('input[name="mode"][value="nickelmenu"]')).not.toBeDisabled(); + }); +}); + +// ============================================================ +// Simulated device tests (mock File System Access API) +// ============================================================ + +/** + * Inject a mock File System Access API into the page, simulating a Kobo Libra Color. + * The mock provides: + * - .kobo/version file with serial N4280A0000000 and firmware 4.45.23646 + * - Optionally a .adds/nm/ directory (to simulate NickelMenu being installed) + * - writeFile tracking to verify what was written + * + * @param {import('@playwright/test').Page} page + * @param {object} opts + * @param {boolean} [opts.hasNickelMenu=false] - Whether .adds/nm/ exists on device + */ +async function injectMockDevice(page, opts = {}) { + await page.evaluate(({ hasNickelMenu }) => { + // In-memory filesystem for the mock device + const filesystem = { + '.kobo': { + _type: 'dir', + 'version': { + _type: 'file', + content: 'N4280A0000000,4.9.77,4.45.23646,4.9.77,4.9.77,00000000-0000-0000-0000-000000000390', + }, + 'Kobo': { + _type: 'dir', + 'Kobo eReader.conf': { + _type: 'file', + content: '[General]\nsome=setting\n', + }, + }, + }, + }; + + if (hasNickelMenu) { + filesystem['.adds'] = { + _type: 'dir', + 'nm': { + _type: 'dir', + 'items': { _type: 'file', content: 'menu_item:main:test:skip:' }, + }, + }; + } + + // Track files written to device + window.__mockWrittenFiles = {}; + + function getNode(pathParts) { + let node = filesystem; + for (const part of pathParts) { + if (!node[part]) return null; + node = node[part]; + } + return node; + } + + function ensureDir(pathParts) { + let node = filesystem; + for (const part of pathParts) { + if (!node[part]) { + node[part] = { _type: 'dir' }; + } + node = node[part]; + } + return node; + } + + function makeFileHandle(dirNode, fileName) { + return { + getFile: async () => { + const fileNode = dirNode[fileName]; + const content = fileNode ? (fileNode.content || '') : ''; + return { + text: async () => content, + arrayBuffer: async () => new TextEncoder().encode(content).buffer, + }; + }, + createWritable: async () => { + const chunks = []; + return { + write: async (chunk) => { chunks.push(chunk); }, + close: async () => { + const first = chunks[0]; + const bytes = first instanceof Uint8Array ? first : new TextEncoder().encode(String(first)); + if (!dirNode[fileName]) dirNode[fileName] = { _type: 'file' }; + dirNode[fileName].content = new TextDecoder().decode(bytes); + window.__mockWrittenFiles[fileName] = true; + }, + }; + }, + }; + } + + function makeDirHandle(node, name) { + return { + name: name, + kind: 'directory', + getDirectoryHandle: async (childName, opts2) => { + if (node[childName] && node[childName]._type === 'dir') { + return makeDirHandle(node[childName], childName); + } + if (opts2 && opts2.create) { + node[childName] = { _type: 'dir' }; + return makeDirHandle(node[childName], childName); + } + throw new DOMException('Not found: ' + childName, 'NotFoundError'); + }, + getFileHandle: async (childName, opts2) => { + if (node[childName] && node[childName]._type === 'file') { + return makeFileHandle(node, childName); + } + if (opts2 && opts2.create) { + node[childName] = { _type: 'file', content: '' }; + return makeFileHandle(node, childName); + } + throw new DOMException('Not found: ' + childName, 'NotFoundError'); + }, + }; + } + + const rootHandle = makeDirHandle(filesystem, 'KOBOeReader'); + + // Override showDirectoryPicker + window.showDirectoryPicker = async () => rootHandle; + }, { hasNickelMenu: opts.hasNickelMenu || false }); +} + +test.describe('With Kobo Libra Color', () => { + test('installing NickelMenu with config', async ({ page }) => { + test.skip(!hasNickelMenuAssets(), 'NickelMenu assets not found in webroot'); + + await page.goto('/'); + await expect(page.locator('h1')).toContainText('KoboPatch'); + + await injectMockDevice(page, { hasNickelMenu: false }); + + // Connect to device + await page.click('#btn-connect'); + await expect(page.locator('#step-device')).not.toBeHidden(); + await expect(page.locator('#device-model')).toHaveText('Kobo Libra Colour'); + await expect(page.locator('#device-firmware')).toHaveText('4.45.23646'); + await expect(page.locator('#device-status')).toContainText('recognized'); + + // Continue to mode selection + await page.click('#btn-device-next'); + await expect(page.locator('#step-mode')).not.toBeHidden(); + + // NickelMenu is pre-selected + await expect(page.locator('input[name="mode"][value="nickelmenu"]')).toBeChecked(); + await page.click('#btn-mode-next'); + + // NickelMenu configure step + await expect(page.locator('#step-nickelmenu')).not.toBeHidden(); + + // Remove option should be disabled (no NickelMenu installed) + await expect(page.locator('#nm-option-remove')).toHaveClass(/nm-option-disabled/); + + // Select "Install NickelMenu and configure" + await page.click('input[name="nm-option"][value="sample"]'); + await expect(page.locator('#nm-config-options')).not.toBeHidden(); + + // Enable all options for testing + await page.check('input[name="nm-cfg-simplify-tabs"]'); + await page.check('input[name="nm-cfg-simplify-home"]'); + + await page.click('#btn-nm-next'); + + // Review step + await expect(page.locator('#step-nm-review')).not.toBeHidden(); + await expect(page.locator('#nm-review-list')).toContainText('NickelMenu'); + await expect(page.locator('#nm-review-list')).toContainText('Readerly fonts'); + await expect(page.locator('#nm-review-list')).toContainText('Simplified tab menu'); + await expect(page.locator('#nm-review-list')).toContainText('Simplified homescreen'); + + // Both buttons visible when device is connected + await expect(page.locator('#btn-nm-write')).toBeVisible(); + await expect(page.locator('#btn-nm-download')).toBeVisible(); + + // Write to device + await page.click('#btn-nm-write'); + await expect(page.locator('#step-nm-done')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('#nm-done-status')).toContainText('installed'); + await expect(page.locator('#nm-write-instructions')).not.toBeHidden(); + }); + + test('removing NickelMenu', async ({ page }) => { + test.skip(!hasNickelMenuAssets(), 'NickelMenu assets not found in webroot'); + + await page.goto('/'); + await expect(page.locator('h1')).toContainText('KoboPatch'); + + await injectMockDevice(page, { hasNickelMenu: true }); + + // Connect to device + await page.click('#btn-connect'); + await expect(page.locator('#step-device')).not.toBeHidden(); + await expect(page.locator('#device-model')).toHaveText('Kobo Libra Colour'); + + // Continue to mode selection + await page.click('#btn-device-next'); + await page.click('#btn-mode-next'); + + // NickelMenu configure step + await expect(page.locator('#step-nickelmenu')).not.toBeHidden(); + + // Remove option should be enabled (NickelMenu is installed) + await expect(page.locator('#nm-option-remove')).not.toHaveClass(/nm-option-disabled/); + await expect(page.locator('input[name="nm-option"][value="remove"]')).not.toBeDisabled(); + + // Select remove + await page.click('input[name="nm-option"][value="remove"]'); + await page.click('#btn-nm-next'); + + // Review step + await expect(page.locator('#step-nm-review')).not.toBeHidden(); + await expect(page.locator('#nm-review-summary')).toContainText('removal'); + + // Download should be hidden for remove + await expect(page.locator('#btn-nm-download')).toBeHidden(); + // Write should show "Remove from Kobo" + await expect(page.locator('#btn-nm-write')).toContainText('Remove from Kobo'); + + // Execute removal + await page.click('#btn-nm-write'); + await expect(page.locator('#step-nm-done')).toBeVisible({ timeout: 30_000 }); + await expect(page.locator('#nm-done-status')).toContainText('removed'); + await expect(page.locator('#nm-reboot-instructions')).not.toBeHidden(); + }); + + test('installing custom patches', async ({ page }) => { + test.skip(!fs.existsSync(FIRMWARE_PATH), `Firmware not found at ${FIRMWARE_PATH}`); + + setupFirmwareSymlink(); + + await page.goto('/'); + await expect(page.locator('h1')).toContainText('KoboPatch'); + + await injectMockDevice(page, { hasNickelMenu: false }); + await overrideFirmwareURLs(page); + + // Connect to device + await page.click('#btn-connect'); + await expect(page.locator('#step-device')).not.toBeHidden(); + await expect(page.locator('#device-model')).toHaveText('Kobo Libra Colour'); + + // Continue to mode selection + await page.click('#btn-device-next'); + await expect(page.locator('#step-mode')).not.toBeHidden(); + + // Both modes should be available (firmware is supported) + await expect(page.locator('input[name="mode"][value="patches"]')).not.toBeDisabled(); + + // Select Custom Patches + await page.click('input[name="mode"][value="patches"]'); + await page.click('#btn-mode-next'); + + // Patches step (patches should already be loaded from device detection) + await expect(page.locator('#step-patches')).not.toBeHidden(); + await expect(page.locator('#patch-container .patch-file-section')).not.toHaveCount(0); + + // Enable a patch + const patchName = page.locator('.patch-name', { hasText: 'Remove footer (row3) on new home screen' }).first(); + const patchSection = patchName.locator('xpath=ancestor::details'); + await patchSection.locator('summary').click(); + await expect(patchName).toBeVisible(); + await patchName.locator('xpath=ancestor::label').locator('input').check(); + + await expect(page.locator('#patch-count-hint')).toContainText('1 patch selected'); + await page.click('#btn-patches-next'); + + // Build step + await expect(page.locator('#step-firmware')).not.toBeHidden(); + await expect(page.locator('#firmware-version-label')).toHaveText('4.45.23646'); + await expect(page.locator('#firmware-device-label')).toHaveText('Kobo Libra Colour'); + + await page.click('#btn-build'); + + const doneOrError = await Promise.race([ + page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), + page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), + ]); + + if (doneOrError === 'error') { + const errorMsg = await page.locator('#error-message').textContent(); + throw new Error(`Build failed: ${errorMsg}`); + } + + await expect(page.locator('#build-status')).toContainText('Patching complete'); + + // Both write and download should be visible with device connected + await expect(page.locator('#btn-write')).toBeVisible(); + await expect(page.locator('#btn-download')).toBeVisible(); + + // Download and verify checksums + const [download] = await Promise.all([ + page.waitForEvent('download'), + page.click('#btn-download'), + ]); + + expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); + const downloadPath = await download.path(); + const tgzData = fs.readFileSync(downloadPath); + const tarData = zlib.gunzipSync(tgzData); + const entries = parseTar(tarData); + + for (const [name, expectedHash] of Object.entries(EXPECTED_SHA1)) { + const data = entries[name]; + expect(data, `missing binary in output: ${name}`).toBeDefined(); + const actualHash = crypto.createHash('sha1').update(data).digest('hex'); + expect(actualHash, `SHA1 mismatch for ${name}`).toBe(expectedHash); + } + }); + + test('restoring original firmware', async ({ page }) => { + test.skip(!fs.existsSync(FIRMWARE_PATH), `Firmware not found at ${FIRMWARE_PATH}`); + + setupFirmwareSymlink(); + + await page.goto('/'); + await expect(page.locator('h1')).toContainText('KoboPatch'); + + await injectMockDevice(page, { hasNickelMenu: false }); + await overrideFirmwareURLs(page); + + // Connect to device + await page.click('#btn-connect'); + await expect(page.locator('#step-device')).not.toBeHidden(); + + // Use the "Restore Unpatched Software" shortcut button on device screen + await page.click('#btn-device-restore'); + + // Build step should show restore mode + await expect(page.locator('#step-firmware')).not.toBeHidden(); + await expect(page.locator('#firmware-description')).toContainText('without modifications'); + await expect(page.locator('#btn-build')).toContainText('Restore Original Software'); + + await page.click('#btn-build'); + + const doneOrError = await Promise.race([ + page.locator('#step-done').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'done'), + page.locator('#step-error').waitFor({ state: 'visible', timeout: 240_000 }).then(() => 'error'), + ]); + + if (doneOrError === 'error') { + const errorMsg = await page.locator('#error-message').textContent(); + throw new Error(`Restore failed: ${errorMsg}`); + } + + await expect(page.locator('#build-status')).toContainText('Software extracted'); + + // Download and verify original + const [download] = await Promise.all([ + page.waitForEvent('download'), + page.click('#btn-download'), + ]); + + expect(download.suggestedFilename()).toBe('KoboRoot.tgz'); + const downloadPath = await download.path(); + const tgzData = fs.readFileSync(downloadPath); + const actualHash = crypto.createHash('sha1').update(tgzData).digest('hex'); + expect(actualHash, 'restored KoboRoot.tgz SHA1 mismatch').toBe(ORIGINAL_TGZ_SHA1); + }); }); diff --git a/tests/e2e/run-e2e-local.sh b/tests/e2e/run-e2e-local.sh deleted file mode 100755 index 505f2ca..0000000 --- a/tests/e2e/run-e2e-local.sh +++ /dev/null @@ -1,38 +0,0 @@ -#!/bin/bash -set -euo pipefail - -# Run the E2E integration test with a visible browser window. -# Usage: ./run-e2e-local.sh - -cd "$(dirname "$0")" - -FIRMWARE_VERSION="4.45.23646" -FIRMWARE_URL="https://ereaderfiles.kobo.com/firmwares/kobo13/Mar2026/kobo-update-${FIRMWARE_VERSION}.zip" -FIRMWARE_DIR="../../kobopatch-wasm/testdata" -FIRMWARE_FILE="${FIRMWARE_DIR}/kobo-update-${FIRMWARE_VERSION}.zip" - -if [ ! -f "../../web/public/wasm/kobopatch.wasm" ]; then - echo "ERROR: kobopatch.wasm not found. Run kobopatch-wasm/build.sh first." - exit 1 -fi - -if [ ! -f "$FIRMWARE_FILE" ]; then - echo "Downloading firmware ${FIRMWARE_VERSION} (~150MB)..." - mkdir -p "$FIRMWARE_DIR" - curl -fL --progress-bar -o "$FIRMWARE_FILE.tmp" "$FIRMWARE_URL" - if ! file "$FIRMWARE_FILE.tmp" | grep -q "Zip archive"; then - echo "ERROR: downloaded file is not a valid zip" - rm -f "$FIRMWARE_FILE.tmp" - exit 1 - fi - mv "$FIRMWARE_FILE.tmp" "$FIRMWARE_FILE" -else - echo "Using cached firmware: $FIRMWARE_FILE" -fi - -npm install --silent 2>/dev/null -npx playwright install chromium 2>/dev/null - -echo "Running E2E integration test (headed)..." -FIRMWARE_ZIP="$(cd ../.. && pwd)/kobopatch-wasm/testdata/kobo-update-${FIRMWARE_VERSION}.zip" \ - npx playwright test --reporter=list --headed diff --git a/tests/e2e/run-e2e.sh b/tests/e2e/run-e2e.sh index 1373e3b..227dd43 100755 --- a/tests/e2e/run-e2e.sh +++ b/tests/e2e/run-e2e.sh @@ -1,17 +1,41 @@ #!/bin/bash set -euo pipefail -# E2E integration test: runs the full manual-mode patching flow in a browser -# and verifies SHA1 checksums of the patched binaries. +# E2E integration test: runs the full UI flows in a browser +# and verifies correct behavior for NickelMenu and custom patches. # -# Usage: ./run-e2e.sh +# Usage: ./run-e2e.sh [--headed] [-- ] +# +# Options: +# --headed Run with a visible browser window # # Prerequisites: # - kobopatch.wasm built (run kobopatch-wasm/build.sh first) # - Firmware zip cached at kobopatch-wasm/testdata/ (downloaded automatically) +# - NickelMenu assets in web/public/nickelmenu/ (set up automatically) cd "$(dirname "$0")" +PLAYWRIGHT_ARGS=("--reporter=list") + +while [[ $# -gt 0 ]]; do + case "$1" in + --headed) + PLAYWRIGHT_ARGS+=("--headed") + shift + ;; + --) + shift + PLAYWRIGHT_ARGS+=("$@") + break + ;; + *) + PLAYWRIGHT_ARGS+=("$1") + shift + ;; + esac +done + FIRMWARE_VERSION="4.45.23646" FIRMWARE_URL="https://ereaderfiles.kobo.com/firmwares/kobo13/Mar2026/kobo-update-${FIRMWARE_VERSION}.zip" FIRMWARE_DIR="../../kobopatch-wasm/testdata" @@ -23,6 +47,13 @@ if [ ! -f "../../web/public/wasm/kobopatch.wasm" ]; then exit 1 fi +# Set up NickelMenu assets if not present. +NM_DIR="../../web/public/nickelmenu" +if [ ! -f "$NM_DIR/NickelMenu.zip" ] || [ ! -f "$NM_DIR/kobo-config.zip" ]; then + echo "Setting up NickelMenu assets..." + ../../nickelmenu/setup.sh +fi + # Download firmware if not cached. if [ ! -f "$FIRMWARE_FILE" ]; then echo "Downloading firmware ${FIRMWARE_VERSION} (~150MB)..." @@ -43,7 +74,7 @@ fi npm install --silent npx playwright install chromium --with-deps 2>/dev/null || npx playwright install chromium -# Run the test. -echo "Running E2E integration test..." +# Run the tests. +echo "Running E2E integration tests..." FIRMWARE_ZIP="$(cd ../.. && pwd)/kobopatch-wasm/testdata/kobo-update-${FIRMWARE_VERSION}.zip" \ - npx playwright test --reporter=list + npx playwright test "${PLAYWRIGHT_ARGS[@]}" diff --git a/web/public/css/style.css b/web/public/css/style.css index 885f217..96ff466 100644 --- a/web/public/css/style.css +++ b/web/public/css/style.css @@ -308,19 +308,15 @@ h2 { /* NickelMenu config checkboxes */ .nm-config-options { - margin-top: 0.75rem; - padding: 0.75rem 1rem; - background: var(--card-bg); - border: 1px solid var(--border-light); - border-radius: 10px; - box-shadow: var(--shadow); + padding: 0 0.25rem; + margin-left: 1.5rem; } .nm-config-item { display: flex; - align-items: center; + align-items: flex-start; gap: 0.6rem; - padding: 0.4rem 0; + padding: 0.5rem 0; font-size: 0.88rem; color: var(--text); cursor: pointer; @@ -332,6 +328,7 @@ h2 { .nm-config-item input[type="checkbox"] { flex-shrink: 0; + margin-top: 0.15rem; accent-color: var(--primary); } @@ -339,8 +336,32 @@ h2 { opacity: 0.6; } -.nm-config-item span { +.nm-config-text { user-select: none; + margin-top: -2px; +} + +.nm-config-desc { + display: block; + font-size: 0.75rem; + color: var(--text-secondary); + line-height: 1.4; + margin-top: 0.1rem; +} + +.nm-config-link { + display: block; + margin-top: 0.75rem; + padding-top: 0.75rem; + padding-bottom: 0.75rem; + border-top: 1px solid var(--border-light); + font-size: 0.8rem; + color: var(--primary); + text-decoration: none; +} + +.nm-config-link:hover { + text-decoration: underline; } .nm-option input[type="radio"] { @@ -387,6 +408,12 @@ h2 { margin-left: auto; } +.step-actions-right { + display: flex; + gap: 0.75rem; + margin-left: auto; +} + /* Buttons */ button { font-size: 0.9rem; diff --git a/web/public/index.html b/web/public/index.html index f7ec31d..b154bc3 100644 --- a/web/public/index.html +++ b/web/public/index.html @@ -52,7 +52,7 @@
Connect my Kobo
-
Connect your Kobo via USB and select its drive. Files will be written directly to the device.
+
Connect your Kobo via USB and select its drive. You will have the option to apply these changes directly, or you can download a ZIP.
@@ -200,8 +216,10 @@
- - +
+ + +
@@ -226,6 +244,9 @@
  1. Connect your Kobo via USB so it appears as a removable drive.
  2. Extract the downloaded ZIP to the root of the Kobo drive, preserving the folder structure.
    3. +
  3. Safely eject the Kobo — do not just unplug the cable.
  4. The device will reboot and install NickelMenu automatically.
@@ -340,18 +361,27 @@

- KoboPatch Web UI is a fully client-side web application for applying custom - kobopatch patches - to Kobo e-readers. Nothing is uploaded to a server — everything runs in your browser. + KoboPatch Web UI is a fully client-side web application for customising + Kobo e-readers. Nothing is uploaded to a server — everything runs in your browser.

-

The patching process

+

NickelMenu

+

+ NickelMenu adds custom menu items + and tweaks to your Kobo. This tool can install NickelMenu along with an optional curated + configuration (custom menus, fonts, screensavers) or remove it. NickelMenu works with + most Kobo devices and includes a failsafe that automatically uninstalls itself if + something goes wrong. +

+ +

Custom patches

  1. Device selection — On Chromium-based browsers (Chrome, Edge), the app can auto-detect your Kobo via the File System Access API when connected over USB. On other browsers, you manually select your model and software version.
    2. -
  2. Patch configuration — You choose which patches to enable or disable. - Patches in the same group are mutually exclusive (radio buttons). +
  3. Patch configuration — You choose which + kobopatch patches + to enable or disable. Patches in the same group are mutually exclusive. The patches themselves are community-contributed via the MobileRead forums.
  4. Build — The correct software update is downloaded directly from Kobo's servers @@ -374,10 +404,11 @@

    Safety

    - Each patched binary is validated before being included in the output: ELF magic bytes, + NickelMenu includes a built-in failsafe mechanism. For custom patches, each patched binary + is validated before being included in the output: ELF magic bytes, 32-bit ARM architecture, file size (must match the original), and archive integrity are - all checked. If anything looks wrong, the build fails with an error. That said, patching - modifies system files, so you should know how to + all checked. If anything looks wrong, the build fails with an error. That said, both + NickelMenu and custom patches modify system files, so you should know how to manually reset your Kobo if needed.

    diff --git a/web/public/js/app.js b/web/public/js/app.js index e3a78e6..bdec227 100644 --- a/web/public/js/app.js +++ b/web/public/js/app.js @@ -401,10 +401,11 @@ // --- Step 2b: NickelMenu configuration --- const nmConfigOptions = $('nm-config-options'); - // Show/hide config checkboxes based on radio selection + // Show/hide config checkboxes based on radio selection, enable Continue for (const radio of $qa('input[name="nm-option"]', stepNickelMenu)) { radio.addEventListener('change', () => { nmConfigOptions.hidden = radio.value !== 'sample' || !radio.checked; + btnNmNext.disabled = false; }); } @@ -447,9 +448,9 @@ function goToNickelMenuConfig() { checkNickelMenuInstalled(); - // Reset config visibility based on current selection const currentOption = $q('input[name="nm-option"]:checked', stepNickelMenu); nmConfigOptions.hidden = !currentOption || currentOption.value !== 'sample'; + btnNmNext.disabled = !currentOption; setNavStep(3); showStep(stepNickelMenu); } @@ -478,7 +479,7 @@ list.innerHTML = ''; if (nickelMenuOption === 'remove') { - summary.textContent = 'NickelMenu will be removed from your device.'; + summary.textContent = 'NickelMenu will be updated and marked for removal. It will uninstall itself when your Kobo reboots.'; btnNmWrite.hidden = manualMode; btnNmWrite.textContent = 'Remove from Kobo'; btnNmDownload.hidden = true; @@ -531,7 +532,11 @@ try { if (nickelMenuOption === 'remove') { - nmProgress.textContent = 'Removing NickelMenu...'; + await nmInstaller.loadAssets((msg) => { nmProgress.textContent = msg; }); + nmProgress.textContent = 'Writing KoboRoot.tgz...'; + const tgz = await nmInstaller.getKoboRootTgz(); + await device.writeFile(['.kobo', 'KoboRoot.tgz'], tgz); + nmProgress.textContent = 'Marking NickelMenu for removal...'; await device.writeFile(['.adds', 'nm', 'uninstall'], new Uint8Array(0)); showNmDone('remove'); return; @@ -574,6 +579,8 @@ nmDoneStatus.textContent = 'Your NickelMenu package is ready to download.'; triggerDownload(resultNmZip, 'NickelMenu-install.zip', 'application/zip'); $('nm-download-instructions').hidden = false; + // Show eReader.conf step only when sample config is included + $('nm-download-conf-step').hidden = nickelMenuOption !== 'sample'; } setNavStep(5);