release: version 0.11.1 (#4123)

First-run users opening Readest with no books now see a typographic
hero instead of the previous generic "Welcome to your library" hero.

Key UX changes:
- 64px PiBooks glyph at base-content/60 anchors a single-column
  composition (max-w-md container, max-w-xs button stack)
- Headline "Start your library" — action-led, not "Welcome to X"
- Platform-aware description:
    desktop: "Drop a book anywhere on this window, or pick one from
             your computer."
    mobile : "Pick a book from your device to add it to your library."
  Branched on appService.isMobile so the touch-only flows don't see
  drag-and-drop language.
- Auth-aware secondary action: a quiet underlined "Sign in to sync
  your library" text link renders only when logged out; signed-in
  users get just the Import CTA (sync runs automatically).
- Primary CTA "Import Books" unchanged; routes to existing file
  picker. The surrounding hero drop-zone wrapper is preserved so
  drag-and-drop import keeps working on desktop.
- TODO marker for a future "Browse free catalogs" entry above the
  secondary action slot.

Implementation:
- Extracted as src/app/library/components/LibraryEmptyState.tsx
  (~60 lines, single onImport prop) so the empty branch can be
  unit-tested without mounting the full LibraryPageContent.
- src/app/library/page.tsx swaps ~17 lines of inline hero JSX for
  one <LibraryEmptyState onImport={handleImportBooksFromFiles} />.
- Four unit tests cover desktop render, mobile render, auth-aware
  sync-button hide, and import-click callback.

i18n: four new strings translated across 33 locales; en/translation.json
untouched per the project convention (non-plural strings live in
code). Stale "Welcome to your library..." key removed by the scanner.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules
+**/node_modules
+
+# Rust build artifacts
+target
+**/target
+
+# Git
+.git
+.gitignore
+
+# Build outputs
+.next
+**/.next
+out
+**/out
+
+# IDE
+.idea
+.vscode
+*.swp
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+

.github/dependabot.yml

@@ -8,6 +8,6 @@ updates:
     groups:
       github-actions:
         patterns:
-          - "*"  # Group all Actions updates into a single larger pull request
+          - '*' # Group all Actions updates into a single larger pull request
     schedule:
       interval: weekly

.github/workflows/codeql.yml

@@ -0,0 +1,103 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: 'CodeQL Advanced'
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+  schedule:
+    - cron: '38 20 * * 4'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: javascript-typescript
+            build-mode: none
+          - language: rust
+            build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      # Add any setup steps before running the `github/codeql-action/init` action.
+      # This includes steps like installing compilers or runtimes (`actions/setup-node`
+      # or others). This is typically only required for manual builds.
+      # - name: Setup runtime (example)
+      #   uses: actions/setup-example@v1
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      # If the analyze step fails for one of the languages you are analyzing with
+      # "We were unable to automatically build your code", modify the matrix above
+      # to set the build mode to "manual" for that language. Then modify this step
+      # to build your code.
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+      - name: Run manual build steps
+        if: matrix.build-mode == 'manual'
+        shell: bash
+        run: |
+          echo 'If you are using a "manual" build mode for one or more of the' \
+            'languages you are analyzing, replace this with the commands to build' \
+            'your code, for example:'
+          echo '  make bootstrap'
+          echo '  make release'
+          exit 1
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: '/language:${{matrix.language}}'

.github/workflows/pull-request.yml

@@ -1,5 +1,7 @@
 name: PR checks
 on:
+  push:
+    branches: [main]
   pull_request:
     branches: [main]
 permissions:
@@ -10,20 +12,30 @@ jobs:
     runs-on: ubuntu-latest
     env:
       RUSTFLAGS: '-C target-cpu=skylake'
+      SCCACHE_GHA_ENABLED: 'true'
+      RUSTC_WRAPPER: sccache
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           submodules: 'true'
+      - name: setup sccache
+        uses: mozilla-actions/sccache-action@v0.0.10
       - name: Install minimal stable with clippy and rustfmt
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           toolchain: stable
           override: true
+          components: rustfmt, clippy
+      - name: Cache apt packages
+        uses: actions/cache@v5
+        with:
+          path: /var/cache/apt/archives
+          key: apt-rust-lint-${{ runner.os }}
       - name: Install system dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y pkg-config libfontconfig-dev libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libsoup-3.0-dev
-      - name: Format
+      - name: Format check
         working-directory: apps/readest-app/src-tauri
         run: cargo fmt --check
       - name: Clippy Check
@@ -32,54 +44,162 @@ jobs:
 
   build_web_app:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        config:
-          - platform: 'web'
-          - platform: 'tauri'
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           submodules: 'true'
 
       - name: setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 10.14.0
+        uses: pnpm/action-setup@v6
 
       - name: setup node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
 
       - name: cache Next.js build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: apps/readest-app/.next/cache
-          key: nextjs-${{ matrix.config.platform }}-${{ github.sha }}-${{ hashFiles('pnpm-lock.yaml') }}
+          key: nextjs-web-${{ github.sha }}-${{ hashFiles('pnpm-lock.yaml') }}
           restore-keys: |
-            nextjs-${{ matrix.config.platform }}-${{ github.sha }}-
-            nextjs-${{ matrix.config.platform }}-
+            nextjs-web-${{ github.sha }}-
+            nextjs-web-
 
       - name: install Dependencies
         working-directory: apps/readest-app
         run: |
-          pnpm install && pnpm setup-pdfjs
+          pnpm install && pnpm setup-vendors
 
-      - name: run tests
+      - name: install LuaJIT (for koplugin lint)
+        run: sudo apt-get update && sudo apt-get install -y luajit
+
+      - name: run format check
+        run: |
+          pnpm format:check || (pnpm format && git diff && exit 1)
+
+      - name: run lint
         working-directory: apps/readest-app
         run: |
-          pnpm test -- --watch=false
+          pnpm lint
 
-      - name: build the web App
-        if: matrix.config.platform == 'web'
+      - name: build the web app
         working-directory: apps/readest-app
         run: |
           pnpm build-web && pnpm check:all
 
-      - name: build the Tauri App
-        if: matrix.config.platform == 'tauri'
+  test_web_app:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'true'
+
+      - name: setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: cache Next.js build
+        uses: actions/cache@v5
+        with:
+          path: apps/readest-app/.next/cache
+          key: nextjs-test-${{ github.sha }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            nextjs-test-${{ github.sha }}-
+            nextjs-test-
+
+      - name: install Dependencies
         working-directory: apps/readest-app
         run: |
-          pnpm build && pnpm check:all
+          pnpm install && pnpm setup-vendors
+
+      - name: install LuaJIT + busted (for koplugin tests)
+        run: |
+          sudo apt-get update
+          # luajit  — pnpm test:lua
+          # luarocks/libsqlite3-dev — required to build lsqlite3complete
+          sudo apt-get install -y luajit luarocks libsqlite3-dev
+          # Install busted + the SQLite binding the LibraryStore specs use,
+          # both pinned to Lua 5.1 (LuaJIT-compatible). System-wide install
+          # so `luarocks --lua-version=5.1 path` (sourced by
+          # scripts/test-koplugin.mjs) picks them up.
+          sudo luarocks --lua-version=5.1 install busted
+          sudo luarocks --lua-version=5.1 install lsqlite3complete
+
+      - name: install playwright browsers
+        working-directory: apps/readest-app
+        run: npx playwright install --with-deps chromium
+
+      - name: run web tests
+        working-directory: apps/readest-app
+        run: pnpm test:pr:web
+
+      - name: run koplugin tests
+        working-directory: apps/readest-app
+        run: pnpm test:lua
+
+  build_tauri_app:
+    runs-on: ubuntu-latest
+    env:
+      SCCACHE_GHA_ENABLED: 'true'
+      RUSTC_WRAPPER: sccache
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'true'
+
+      - name: setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: cache Next.js build
+        uses: actions/cache@v5
+        with:
+          path: apps/readest-app/.next/cache
+          key: nextjs-tauri-${{ github.sha }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            nextjs-tauri-${{ github.sha }}-
+            nextjs-tauri-
+
+      - name: install Dependencies
+        working-directory: apps/readest-app
+        run: |
+          pnpm install && pnpm setup-vendors
+
+      - name: setup sccache
+        uses: mozilla-actions/sccache-action@v0.0.10
+
+      - name: install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: tauri-cargo
+          cache-all-crates: 'true'
+
+      - name: Cache apt packages
+        uses: actions/cache@v5
+        with:
+          path: /var/cache/apt/archives
+          key: apt-tauri-${{ runner.os }}
+      - name: install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libfontconfig-dev libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libsoup-3.0-dev xvfb
+
+      - name: run tauri tests
+        working-directory: apps/readest-app
+        run: xvfb-run pnpm test:pr:tauri

.github/workflows/release.yml

@@ -17,14 +17,14 @@ jobs:
       release_version: ${{ steps.get-release-notes.outputs.release_version }}
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: setup node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
       - name: get version
         run: echo "PACKAGE_VERSION=$(node -p "require('./apps/readest-app/package.json').version")" >> $GITHUB_ENV
       - name: get release
         id: get-release
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
             const { data } = await github.rest.repos.getLatestRelease({
@@ -35,7 +35,7 @@ jobs:
             core.setOutput('release_tag', data.tag_name);
       - name: get release notes
         id: get-release-notes
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         with:
           script: |
             const fs = require('fs');
@@ -57,7 +57,7 @@ jobs:
     steps:
       - name: update release
         id: update-release
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
         env:
           release_id: ${{ needs.get-release.outputs.release_id }}
           release_tag: ${{ needs.get-release.outputs.release_tag }}
@@ -69,7 +69,7 @@ jobs:
               repo: context.repo.repo,
               tag_name: process.env.release_tag,
             })
-            const notes = process.env.release_note.split(/(?:\d\.\s)/).filter(Boolean);
+            const notes = process.env.release_note.split(/\d+\.\s/).filter(Boolean);
             const formattedNotes = notes.map(note => `* ${note.trim()}`).join("\n");
             const body = `## Release Highlight\n${formattedNotes}\n\n${data.body}`;
             github.rest.repos.updateRelease({
@@ -81,6 +81,41 @@ jobs:
               prerelease: false
             })
 
+  build-koreader-plugin:
+    needs: get-release
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: create KOReader plugin zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          version=${{ needs.get-release.outputs.release_version }}
+          plugin_zip="Readest-${version}-1.koplugin.zip"
+          meta_file="apps/readest.koplugin/_meta.lua"
+          perl -i -pe "s/^}/    version = \"${version}\",\n}/" "${meta_file}"
+
+          # Exclude dev-only artifacts from the published plugin zip:
+          #   scripts/  — i18n + build helpers
+          #   docs/     — design notes
+          #   spec/     — busted test suite
+          #   .busted   — busted runner config
+          # Mirror these in apps/readest.koplugin/scripts/build-koplugin.mjs
+          # for local builds.
+          cd apps
+          zip -r ../${plugin_zip} readest.koplugin \
+            -x 'readest.koplugin/scripts/*' \
+               'readest.koplugin/docs/*' \
+               'readest.koplugin/spec/*' \
+               'readest.koplugin/.busted'
+          cd ..
+
+          echo "Uploading ${plugin_zip} to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} ${plugin_zip} --clobber
+
   build-tauri:
     needs: get-release
     permissions:
@@ -100,11 +135,6 @@ jobs:
             release: linux
             arch: aarch64
             rust_target: aarch64-unknown-linux-gnu
-          - os: ubuntu-22.04-arm
-            release: linux
-            arch: armhf
-            rust_target: arm-unknown-linux-gnueabihf
-            args: '--target arm-unknown-linux-gnueabihf --bundles deb'
           - os: macos-latest
             release: macos
             arch: aarch64
@@ -124,42 +154,40 @@ jobs:
     runs-on: ${{ matrix.config.os }}
     timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: initialize git submodules
         run: git submodule update --init --recursive
 
       - name: setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 10.14.0
+        uses: pnpm/action-setup@v6
 
       - name: setup node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
 
       - name: setup Java (for Android build only)
         if: matrix.config.release == 'android'
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: 'zulu'
           java-version: '17'
 
       - name: setup Android SDK (for Android build only)
         if: matrix.config.release == 'android'
-        uses: android-actions/setup-android@v3
+        uses: android-actions/setup-android@v4
 
       - name: install NDK (for Android build only)
         if: matrix.config.release == 'android'
-        run: sdkmanager "ndk;27.0.11902837"
+        run: sdkmanager "ndk;28.2.13676358"
 
       - name: install dependencies
         run: pnpm install
 
-      - name: copy pdfjs-dist to public directory
-        run: pnpm --filter @readest/readest-app setup-pdfjs
+      - name: copy pdfjs-dist and simplecc-dist to public directory
+        run: pnpm --filter @readest/readest-app setup-vendors
 
       - name: install Rust stable
         uses: dtolnay/rust-toolchain@stable
@@ -174,7 +202,7 @@ jobs:
         if: contains(matrix.config.os, 'ubuntu') && matrix.config.release != 'android' && matrix.config.arch != 'armhf'
         run: |
           sudo apt-get update
-          sudo apt-get install -y pkg-config libfontconfig-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
+          sudo apt-get install -y pkg-config libfontconfig-dev libgtk-3-dev libwebkit2gtk-4.1 libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1 libjavascriptcoregtk-4.1-dev gir1.2-javascriptcoregtk-4.1 gir1.2-webkit2-4.1 libappindicator3-dev librsvg2-dev patchelf xdg-utils
 
       - name: install dependencies (ubuntu only - armhf specific)
         if: contains(matrix.config.os, 'ubuntu') && matrix.config.arch == 'armhf'
@@ -186,6 +214,7 @@ jobs:
           echo 'PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig:/usr/share/pkgconfig' >> $GITHUB_ENV
           echo 'PKG_CONFIG_SYSROOT_DIR=/usr/arm-linux-gnueabihf' >> $GITHUB_ENV
           echo 'CARGO_TARGET_ARM_UNKNOWN_LINUX_GNUEABIHF_LINKER=arm-linux-gnueabihf-gcc' >> $GITHUB_ENV
+          echo 'CARGO_TARGET_ARM_UNKNOWN_LINUX_GNUEABIHF_RUSTFLAGS=--cfg=io_uring_skip_arch_check' >> $GITHUB_ENV
 
       - name: create .env.local file for Next.js
         run: |
@@ -200,7 +229,7 @@ jobs:
         if: matrix.config.release == 'android'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NDK_HOME: ${{ env.ANDROID_HOME }}/ndk/27.0.11902837
+          NDK_HOME: ${{ env.ANDROID_HOME }}/ndk/28.2.13676358
           TAURI_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
         run: |
@@ -210,11 +239,6 @@ jobs:
           pnpm tauri icon ../../data/icons/readest-book.png
           git checkout .
 
-          MANIFEST="src-tauri/gen/android/app/src/main/AndroidManifest.xml"
-          PERMISSION_LINE='<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>'
-          grep -q 'REQUEST_INSTALL_PACKAGES' "$MANIFEST" || \
-            sed -i "/android.permission.INTERNET/a \    $PERMISSION_LINE" "$MANIFEST"
-
           pushd src-tauri/gen/android
           echo "keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}" > keystore.properties
           echo "password=${{ secrets.ANDROID_KEY_PASSWORD }}" >> keystore.properties
@@ -267,10 +291,15 @@ jobs:
           echo "Uploading updated latest.json to GitHub release"
           gh release upload ${{ needs.get-release.outputs.release_tag }} latest.json --clobber
 
+      - name: Override tauri-cli with custom AppImage format (Linux)
+        if: matrix.config.release == 'linux'
+        run: cargo install tauri-cli --git https://github.com/tauri-apps/tauri --branch feat/truly-portable-appimage --force
+
       - uses: tauri-apps/tauri-action@v0
         if: matrix.config.release != 'android'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAURI_BUNDLER_NEW_APPIMAGE_FORMAT: 'true'
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
           APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
@@ -293,12 +322,22 @@ jobs:
           echo "Uploading release notes to GitHub release"
           gh release upload ${{ needs.get-release.outputs.release_tag }} apps/readest-app/release-notes.json --clobber
 
-      - name: upload portable binaries (Windows only)
+      - name: build and upload portable binaries (Windows only)
         if: matrix.config.os == 'windows-latest'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAURI_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
         shell: bash
         run: |
+          echo "Building Portable Binaries"
+          pushd apps/readest-app/
+          echo "NEXT_PUBLIC_PORTABLE_APP=true" >> .env.local
+          pnpm tauri build ${{ matrix.config.args }}
+
+          popd
           echo "Uploading Portable Binaries"
           arch=${{ matrix.config.arch }}
           version=${{ needs.get-release.outputs.release_version }}
@@ -321,8 +360,51 @@ jobs:
           echo "Uploading $bin_file to GitHub release"
           gh release upload ${{ needs.get-release.outputs.release_tag }} $bin_file --clobber
 
+          echo "Signing portable binary"
+          pushd apps/readest-app/
+          pnpm tauri signer sign "../../$bin_file"
+          popd
+          echo "Uploading signature to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} $bin_file.sig --clobber
+
+      - name: download and update latest.json for Windows portable release
+        if: matrix.config.os == 'windows-latest'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          curl -sL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json
+
+          version=${{ needs.get-release.outputs.release_version }}
+          arch=${{ matrix.config.arch }}
+
+          if [ "$arch" = "x86_64" ]; then
+            bin_file="Readest_${version}_x64-portable.exe"
+            platform_key="windows-x86_64-portable"
+          elif [ "$arch" = "aarch64" ]; then
+            bin_file="Readest_${version}_arm64-portable.exe"
+            platform_key="windows-aarch64-portable"
+          else
+            echo "Unknown architecture: $arch"
+            exit 1
+          fi
+
+          portable_url="https://github.com/readest/readest/releases/download/${{ needs.get-release.outputs.release_tag }}/$bin_file"
+          portable_sig=$(cat $bin_file.sig)
+
+          jq --arg url "$portable_url" \
+              --arg sig "$portable_sig" \
+              --arg key "$platform_key" \
+              '.platforms[$key] = {signature: $sig, url: $url}' latest.json > tmp.$$.json && mv tmp.$$.json latest.json
+
+          echo "Uploading updated latest.json to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} latest.json --clobber
+
   upload-to-r2:
-    needs: [get-release, update-release]
+    needs: [get-release, build-tauri]
+    permissions:
+      contents: read
+      actions: write
     uses: ./.github/workflows/upload-to-r2.yml
     with:
       tag: ${{ needs.get-release.outputs.release_tag }}

.github/workflows/retry-workflow.yml

@@ -8,6 +8,8 @@ on:
 jobs:
   rerun:
     runs-on: ubuntu-latest
+    permissions:
+      actions: write
     steps:
       - name: rerun ${{ inputs.run_id }}
         env:

.github/workflows/upload-to-r2.yml

@@ -17,6 +17,8 @@ on:
 jobs:
   upload-to-r2:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     timeout-minutes: 3
     strategy:
       fail-fast: false
@@ -70,6 +72,8 @@ jobs:
     if: failure() && fromJSON(github.run_attempt) < 3
     needs: [upload-to-r2]
     runs-on: ubuntu-latest
+    permissions:
+      actions: write
     steps:
       - env:
           GH_REPO: ${{ github.repository }}

.github/workflows/vercel-merge.yml

@@ -11,10 +11,10 @@ jobs:
   build_and_deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           submodules: 'true'
-      - uses: amondnet/vercel-action@v25
+      - uses: amondnet/vercel-action@v42
         with:
           vercel-token: ${{ secrets.VERCEL_TOKEN }}
           github-token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,4 +1,5 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+docker/.env
 
 # dependencies
 /node_modules
@@ -40,6 +41,16 @@ next-env.d.ts
 target
 
 fastlane/report.xml
+fastlane/metadata/android/en-US/changelogs
 
 *.koplugin.zip
 
+# nix
+result*
+
+.playwright-mcp/
+.gstack
+
+.claude/worktrees
+.claude/settings.local.json
+

.gitmodules

@@ -7,3 +7,18 @@
 [submodule "packages/tauri-plugins"]
 	path = packages/tauri-plugins
 	url = https://github.com/readest/tauri-plugins-workspace.git
+[submodule "packages/simplecc-wasm"]
+	path = packages/simplecc-wasm
+	url = https://github.com/readest/simplecc-wasm.git
+[submodule "apps/readest-app/src-tauri/plugins/tauri-plugin-turso"]
+	path = apps/readest-app/src-tauri/plugins/tauri-plugin-turso
+	url = https://github.com/readest/tauri-plugin-turso.git
+[submodule "apps/readest-app/.claude/skills/gstack"]
+	path = apps/readest-app/.claude/skills/gstack
+	url = https://github.com/garrytan/gstack.git
+[submodule "packages/qcms"]
+	path = packages/qcms
+	url = https://github.com/mozilla/pdf.js.qcms.git
+[submodule "packages/js-mdict"]
+	path = packages/js-mdict
+	url = https://github.com/readest/js-mdict.git

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

.husky/pre-push

@@ -0,0 +1,2 @@
+pnpm -C apps/readest-app lint
+pnpm -C apps/readest-app test

.prettierignore

@@ -1 +1,38 @@
-packages/foliate-js/
+# Dependencies
+node_modules
+pnpm-lock.yaml
+
+# Build Artifacts (Web & Rust)
+.next
+.open-next
+.build
+.tauri
+out
+build
+dist
+target
+fastlane
+.wrangler
+
+# Autogenerated Tauri files
+gen
+**/autogenerated
+**/schemas
+
+# Submodules (External Repos)
+packages
+
+# Claude Code Skills & Config
+apps/readest-app/.claude
+
+# Vendored Assets (Generated/External Code)
+apps/readest-app/public/*.js
+apps/readest-app/public/vendor
+apps/readest-app/src-tauri/plugins/tauri-plugin-turso
+
+# Environment & Editor
+.env
+.env.*
+.vscode
+.idea
+*.log

.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "ms-vscode.vscode-typescript-next",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "rust-lang.rust-analyzer"
+  ]
+}

.vscode/settings.json

@@ -13,4 +13,19 @@
   "javascript.validate.enable": false,
   "javascript.format.enable": false,
   "typescript.format.enable": false,
-}
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "prettier.requireConfig": true,
+  "prettier.documentSelectors": ["**/*.{js,jsx,ts,tsx,css,json,md,html,yml}"]
+}

CONTRIBUTING.md

@@ -43,8 +43,8 @@ git submodule update --init --recursive
 ```bash
 # might need to rerun this when code is updated
 pnpm install
-# copy pdfjs-dist to Next.js public directory
-pnpm --filter @readest/readest-app setup-pdfjs
+# copy vendors dist libs to public directory
+pnpm --filter @readest/readest-app setup-vendors
 ```
 
 #### 3. Verify Dependencies Installation

Cargo.toml

@@ -2,11 +2,10 @@
 members = [
   "apps/readest-app/src-tauri",
   "packages/tauri/crates/tauri",
-  "packages/tauri/crates/tauri-utils",
-  "packages/tauri/crates/tauri-build",
-  "packages/tauri-plugins/plugins/fs",
-  "packages/tauri-plugins/plugins/dialog",
-  "packages/tauri-plugins/plugins/deep-link",
+  "packages/tauri-plugins/plugins/fs"
+]
+exclude = [
+  "packages/qcms"
 ]
 resolver = "2"
 
@@ -22,8 +21,12 @@ schemars = "0.8"
 serde_json = "1"
 thiserror = "2"
 glob = "0.3"
+zbus = "5.9"
 dunce = "1"
 url = "2"
+tar = "0.4.45"
+nix = "0.20.2"
+glib = "0.20.0"
 
 [workspace.package]
 authors = ["Bilingify LLC"]
@@ -36,9 +39,4 @@ rust-version = "1.77.2"
 
 [patch.crates-io]
 tauri = { path = "packages/tauri/crates/tauri" }
-tauri-utils = { path = "packages/tauri/crates/tauri-utils" }
-tauri-build = { path = "packages/tauri/crates/tauri-build" }
-tauri-plugin-os = { path = "packages/tauri-plugins/plugins/os" }
 tauri-plugin-fs = { path = "packages/tauri-plugins/plugins/fs" }
-tauri-plugin-dialog = { path = "packages/tauri-plugins/plugins/dialog" }
-tauri-plugin-deep-link = { path = "packages/tauri-plugins/plugins/deep-link" }

Dockerfile

@@ -1,38 +1,40 @@
-FROM node:22-slim
-
-ENV PNPM_HOME="/root/.local/share/pnpm"
-ENV PATH="${PATH}:${PNPM_HOME}"
-
-RUN npm install --global pnpm
-
-# Install necessary packages
-RUN apt update -y && apt install -y --no-install-recommends \
-    libwebkit2gtk-4.1-dev \
-    build-essential \
-    curl \
-    wget \
-    file \
-    libxdo-dev \
-    libssl-dev \
-    libayatana-appindicator3-dev \
-    librsvg2-dev \
-    ca-certificates \
-    && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# Install Rust and Cargo
-RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-ENV PATH="/root/.cargo/bin:${PATH}"
-
-COPY . /app
-
+FROM docker.io/node:22-slim AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+RUN corepack prepare pnpm@10.29.3 --activate
 WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY apps/readest-app/package.json ./apps/readest-app/
+COPY patches/ ./patches/
+COPY packages/ ./packages/
 
-RUN pnpm install
-
-RUN pnpm --filter @readest/readest-app setup-pdfjs
+FROM base AS dependencies
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
+RUN pnpm --filter @readest/readest-app setup-vendors
 
+FROM dependencies AS development-stage
+COPY . .
 WORKDIR /app/apps/readest-app
+EXPOSE 3000
+ENTRYPOINT ["pnpm", "dev-web", "-H", "0.0.0.0"]
 
+FROM base AS build
+ARG NEXT_PUBLIC_SUPABASE_URL
+ARG NEXT_PUBLIC_SUPABASE_ANON_KEY
+ARG NEXT_PUBLIC_APP_PLATFORM
+ARG NEXT_PUBLIC_API_BASE_URL
+ARG NEXT_PUBLIC_OBJECT_STORAGE_TYPE
+ARG NEXT_PUBLIC_STORAGE_FIXED_QUOTA
+ARG NEXT_PUBLIC_TRANSLATION_FIXED_QUOTA
+COPY --from=dependencies /app/node_modules /app/node_modules
+COPY --from=dependencies /app/apps/readest-app/node_modules /app/apps/readest-app/node_modules
+COPY --from=dependencies /app/apps/readest-app/public/vendor /app/apps/readest-app/public/vendor
+COPY --from=dependencies /app/packages/foliate-js/node_modules /app/packages/foliate-js/node_modules
+COPY . .
+WORKDIR /app/apps/readest-app
 RUN pnpm build-web
 
-ENTRYPOINT ["pnpm", "start-web"]
+FROM build as production-stage
+ENTRYPOINT ["pnpm", "start-web", "-H", "0.0.0.0"]
+EXPOSE 3000

README.md

@@ -5,20 +5,21 @@
   <h1>Readest</h1>
   <br>
 
-[Readest][link-website] is an open-source ebook reader designed for immersive and deep reading experiences. Built as a modern rewrite of [Foliate](https://github.com/johnfactotum/foliate), it leverages [Next.js 15](https://github.com/vercel/next.js) and [Tauri v2](https://github.com/tauri-apps/tauri) to deliver a smooth, cross-platform experience across macOS, Windows, Linux, Android, iOS, and the Web.
+[Readest][link-website] is an open-source ebook reader designed for immersive and deep reading experiences. Built as a modern rewrite of [Foliate](https://github.com/johnfactotum/foliate), it leverages [Next.js 16](https://github.com/vercel/next.js) and [Tauri v2](https://github.com/tauri-apps/tauri) to deliver a smooth, cross-platform experience across macOS, Windows, Linux, Android, iOS, and the Web.
 
 [![Website][badge-website]][link-website]
 [![Web App][badge-web-app]][link-web-readest]
 [![OS][badge-platforms]][link-website]
 <br>
-[![][badge-hellogithub]][link-hellogithub]
-[![][badge-discord]][link-discord]
+[![Discord][badge-discord]][link-discord]
+[![Reddit][badge-reddit]][link-reddit]
 [![AGPL Licence][badge-license]](LICENSE)
-[![Latest release][badge-release]][link-gh-releases]
+[![Language Coverage][badge-language-coverage]][link-locales]
 [![Donate][badge-donate]][link-donate]
-<br>
+[![Latest release][badge-release]][link-gh-releases]
 [![Last commit][badge-last-commit]][link-gh-commits]
 [![Commits][badge-commit-activity]][link-gh-pulse]
+[![][badge-hellogithub]][link-hellogithub]
 [![Ask DeepWiki][badge-deepwiki]][link-deepwiki]
 
 </div>
@@ -44,39 +45,38 @@
 
 <div align="left">✅ Implemented</div>
 
-| **Feature**                             | **Description**                                                                                | **Status** |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- |
-| **Multi-Format Support**                | Support EPUB, MOBI, KF8 (AZW3), FB2, CBZ, TXT, PDF (experimental)                              | ✅         |
-| **Scroll/Page View Modes**              | Switch between scrolling or paginated reading modes.                                           | ✅         |
-| **Full-Text Search**                    | Search across the entire book to find relevant sections.                                       | ✅         |
-| **Annotations and Highlighting**        | Add highlights, bookmarks, and notes to enhance your reading experience.                       | ✅         |
-| **Excerpt Text for Note-Taking**        | Easily excerpt text from books for detailed notes and analysis.                                | ✅         |
-| **Dictionary/Wikipedia Lookup**         | Instantly look up words and terms when reading.                                                | ✅         |
-| **[Parallel Read][link-parallel-read]** | Read two books or documents simultaneously in a split-screen view.                             | ✅         |
-| **Customize Font and Layout**           | Adjust font, layout, theme mode, and theme colors for a personalized experience.               | ✅         |
-| **File Association and Open With**      | Quickly open files in Readest in your file browser with one-click.                             | ✅         |
-| **Sync across Platforms**               | Synchronize book files, reading progress, notes, and bookmarks across all supported platforms. | ✅         |
-| **Translate with DeepL**                | From a single sentence to the entire book—translate instantly with DeepL.                      | ✅         |
-| **Translate with Yandex**               | Instantly translate text or books using Yandex Translate.                                      | ✅         |
-| **Text-to-Speech (TTS) Support**        | Enjoy smooth, multilingual narration—even within a single book.                                | ✅         |
-| **Library Management**                  | Organize, sort, and manage your entire ebook library.                                          | ✅         |
-| **Code Syntax Highlighting**            | Read software manuals with rich coloring of code examples.                                     | ✅         |
+| **Feature**                                | **Description**                                                                                                        | **Status** |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ---------- |
+| **Multi-Format Support**                   | Support EPUB, MOBI, KF8 (AZW3), FB2, CBZ, TXT, PDF                                                                     | ✅         |
+| **Scroll/Page View Modes**                 | Switch between scrolling or paginated reading modes.                                                                   | ✅         |
+| **Full-Text Search**                       | Search across the entire book to find relevant sections.                                                               | ✅         |
+| **Annotations and Highlighting**           | Add highlights, bookmarks, and notes to enhance your reading experience and use instant mode for quicker interactions. | ✅         |
+| **Dictionary/Wikipedia Lookup**            | Instantly look up words and terms when reading.                                                                        | ✅         |
+| **[Parallel Read][link-parallel-read]**    | Read two books or documents simultaneously in a split-screen view.                                                     | ✅         |
+| **Customize Font and Layout**              | Adjust font, layout, theme mode, and theme colors for a personalized experience.                                       | ✅         |
+| **Code Syntax Highlighting**               | Read software manuals with rich coloring of code examples.                                                             | ✅         |
+| **File Association and Open With**         | Quickly open files in Readest in your file browser with one-click.                                                     | ✅         |
+| **Library Management**                     | Organize, sort, and manage your entire ebook library.                                                                  | ✅         |
+| **OPDS/Calibre Integration**               | Integrate OPDS/Calibre to access online libraries and catalogs.                                                        | ✅         |
+| **Translate with DeepL and Yandex**        | From a single sentence to the entire book—translate instantly.                                                         | ✅         |
+| **Text-to-Speech (TTS) Support**           | Enjoy smooth, multilingual narration—even within a single book.                                                        | ✅         |
+| **Sync across Platforms**                  | Synchronize book files, reading progress, notes, and bookmarks across all supported platforms.                         | ✅         |
+| [**Sync with Koreader**][link-kosync-wiki] | Synchronize reading progress, notes, and bookmarks with [Koreader][link-koreader] devices.                             | ✅         |
+| **Accessibility**                          | Provides full keyboard navigation and supports for screen readers such as VoiceOver, TalkBack, NVDA, and Orca.         | ✅         |
+| **Visual & Focus Aids**                    | Reading ruler, paragraph-by-paragraph reading mode, and speed reading features.                                        | ✅         |
 
 ## Planned Features
 
 <div align="left">🛠 Building</div>
 <div align="left">🔄 Planned</div>
 
-| **Feature**                     | **Description**                                                                            | **Priority** |
-| ------------------------------- | ------------------------------------------------------------------------------------------ | ------------ |
-| **Sync with Koreader**          | Synchronize reading progress, notes, and bookmarks with [Koreader][link-koreader] devices. | 🛠           |
-| **AI-Powered Summarization**    | Generate summaries of books or chapters using AI for quick insights.                       | 🛠           |
-| **Keyboard Navigation**         | Implement vimium-style keybindings for book navigation.                                    | 🔄           |
-| **Support OPDS/Calibre**        | Integrate OPDS/Calibre to access online libraries and catalogs.                            | 🔄           |
-| **Audiobook Support**           | Extend functionality to play and manage audiobooks.                                        | 🔄           |
-| **Handwriting Annotations**     | Add support for handwriting annotations using a pen on compatible devices.                 | 🔄           |
-| **Advanced Reading Stats**      | Track reading time, pages read, and more for detailed insights.                            | 🔄           |
-| **In-Library Full-Text Search** | Search across your entire ebook library to find topics and quotes.                         | 🔄           |
+| **Feature**                     | **Description**                                                            | **Priority** |
+| ------------------------------- | -------------------------------------------------------------------------- | ------------ |
+| **AI-Powered Summarization**    | Generate summaries of books or chapters using AI for quick insights.       | 🛠           |
+| **Advanced Reading Stats**      | Track reading time, pages read, and more for detailed insights.            | 🛠           |
+| **Audiobook Support**           | Extend functionality to play and manage audiobooks.                        | 🔄           |
+| **Handwriting Annotations**     | Add support for handwriting annotations using a pen on compatible devices. | 🔄           |
+| **In-Library Full-Text Search** | Search across your entire ebook library to find topics and quotes.         | 🔄           |
 
 Stay tuned for continuous improvements and updates! Contributions and suggestions are always welcome—let's build the ultimate reading experience together. 😊
 
@@ -109,9 +109,10 @@ Stay tuned for continuous improvements and updates! Contributions and suggestion
 
 ### Platform-Specific Downloads
 
-- macOS / iOS / iPadOS : Search for "Readest" on the [App Store][link-appstore], also available on TestFlight for beta test (send your Apple ID to <readestapp@gmail.com> to request access).
-- Windows / Linux / Android: Visit [https://readest.com][link-website] or the [Releases on GitHub][link-gh-releases].
-- Web: Visit [https://web.readest.com][link-web-readest].
+- macOS / iOS / iPadOS : Search and install **Readest** on the [App Store][link-appstore], _also_ available on TestFlight for beta test (send your Apple ID to <readestapp@gmail.com> to request access).
+- Windows / Linux / Android: Visit and download **Readest** at [https://readest.com][link-website] or the [Releases on GitHub][link-gh-releases].
+- Linux users can also install [Readest on Flathub][link-flathub].
+- Web: Visit and use **Readest for Web** at [https://web.readest.com][link-web-readest].
 
 ## Requirements
 
@@ -121,8 +122,8 @@ Stay tuned for continuous improvements and updates! Contributions and suggestion
 For the best experience to build Readest for yourself, use a recent version of Node.js and Rust. Refer to the [Tauri documentation](https://v2.tauri.app/start/prerequisites/) for details on setting up the development environment prerequisites on different platforms.
 
 ```bash
-nvm install v22
-nvm use v22
+nvm install v24
+nvm use v24
 npm install -g pnpm
 rustup update
 ```
@@ -144,8 +145,8 @@ cd readest
 # might need to rerun this when code is updated
 git submodule update --init --recursive
 pnpm install
-# copy pdfjs-dist to Next.js public directory
-pnpm --filter @readest/readest-app setup-pdfjs
+# copy vendors dist libs to public directory
+pnpm --filter @readest/readest-app setup-vendors
 ```
 
 ### 3. Verify Dependencies Installation
@@ -175,7 +176,10 @@ For Android:
 
 ```bash
 # Initialize the Android environment (run once)
+rm apps/readest-app/src-tauri/gen/android
 pnpm tauri android init
+pnpm tauri icon ../../data/icons/readest-book.png
+git checkout apps/readest-app/src-tauri/gen/android
 
 pnpm tauri android dev
 # or if you want to dev on a real device
@@ -187,6 +191,7 @@ For iOS:
 ```bash
 # Set up the iOS environment (run once)
 pnpm tauri ios init
+pnpm tauri icon ../../data/icons/readest-book.png
 
 pnpm tauri ios dev
 # or if you want to dev on a real device
@@ -201,6 +206,9 @@ pnpm tauri android build
 pnpm tauri ios build
 ```
 
+Please refer to our release script if you experience any issues:
+https://github.com/readest/readest/blob/main/.github/workflows/release.yml
+
 ### 6. Setup dev environment with Nix
 
 If you have Nix installed, you can leverage flake to enter a development shell
@@ -249,6 +257,32 @@ Please check the [wiki][link-gh-wiki] of this project for more information on de
 
 - See Issue [readest/readest#358](https://github.com/readest/readest/issues/358) for further details, or head over to our [Discord][link-discord] server and open a support discussion with detailed logs of your environment and the steps you’ve taken.
 
+### 2. AppImage Launches but Only Shows a Taskbar Icon
+
+On some Arch Linux systems—especially those using Wayland—the Readest AppImage may briefly show an icon in the taskbar and then exit without opening a window.
+
+You might see logs such as:
+
+```
+Could not create default EGL display: EGL_BAD_PARAMETER. Aborting...
+```
+
+This behavior is usually caused by compatibility issues between the bundled AppImage libraries and the system’s EGL / Wayland environment.
+
+**Workaround 1: Launch with LD_PRELOAD (recommended)**
+
+You can preload the system Wayland client library before launching the AppImage:
+
+```
+LD_PRELOAD=/usr/lib/libwayland-client.so /path/to/Readest.AppImage
+```
+
+This workaround has been confirmed to resolve the issue on affected systems.
+
+**Workaround 2: Use the Flatpak Version**
+
+If you prefer a more reliable out-of-the-box experience on Arch Linux, consider using the [Flatpak build on Flathub][link-flathub] instead. The Flatpak runtime helps avoid system library mismatches and tends to behave more consistently across different Wayland and X11 setups.
+
 ## Contributors
 
 Readest is open-source, and contributions are welcome! Feel free to open issues, suggest features, or submit pull requests. Please **review our [contributing guidelines](CONTRIBUTING.md) before you start**. We also welcome you to join our [Discord][link-discord] community for either support or contributing guidance.
@@ -261,17 +295,15 @@ Readest is open-source, and contributions are welcome! Feel free to open issues,
 
 ## Support
 
-If Readest has been useful to you, consider supporting its development. Your contribution helps us squash bugs faster, improve performance, and keep building great features.
+If Readest has been useful to you, consider supporting its development. You can [become a sponsor on GitHub](https://github.com/sponsors/readest), [donate via Stripe](https://donate.stripe.com/4gMcN5aZdcE52kW3TFgjC01), or [donate with crypto](https://donate.readest.com). Your contribution helps us squash bugs faster, improve performance, and keep building great features.
 
-### How to Donate
+### Sponsors
 
-1. **GitHub Sponsors**  
-   Back the project directly on GitHub:  
-   👉 [https://github.com/sponsors/readest](https://github.com/sponsors/readest)
-
-2. **Crypto Donations**  
-   Prefer crypto? You can donate here:  
-   👉 [https://donate.readest.com/](https://donate.readest.com/)
+<p align="center">
+  <a title="Browser testing via TestMu AI" href="https://www.testmuai.com/?utm_medium=sponsor&utm_source=readest" target="_blank">
+    <img src="https://raw.githubusercontent.com/readest/readest/refs/heads/main/data/sponsors/testmu-ai-logo.png" style="vertical-align: middle;" width="250" />
+  </a>
+</p>
 
 ## License
 
@@ -292,7 +324,9 @@ The following libraries and frameworks are used in this software:
 
 The following fonts are utilized in this software, either bundled within the application or provided through web fonts:
 
-[Bitter](https://fonts.google.com/?query=Bitter), [Fira Code](https://fonts.google.com/?query=Fira+Code), [Literata](https://fonts.google.com/?query=Literata), [Merriweather](https://fonts.google.com/?query=Merriweather), [Noto Sans](https://fonts.google.com/?query=Noto+Sans), [Roboto](https://fonts.google.com/?query=Roboto), [LXGW WenKai](https://github.com/lxgw/LxgwWenKai), [MiSans](https://hyperos.mi.com/font/en/), [Source Han](https://github.com/adobe-fonts/source-han-sans/), [WenQuanYi Micro Hei](http://wenq.org/wqy2/)
+[Bitter](https://fonts.google.com/specimen/Bitter), [Fira Code](https://fonts.google.com/specimen/Fira+Code), [Inter](https://fonts.google.com/specimen/Inter), [Literata](https://fonts.google.com/specimen/Literata), [Merriweather](https://fonts.google.com/specimen/Merriweather), [Noto Sans](https://fonts.google.com/specimen/Noto+Sans), [Roboto](https://fonts.google.com/specimen/Roboto), [LXGW WenKai](https://github.com/lxgw/LxgwWenKai), [MiSans](https://hyperos.mi.com/font/en/), [Source Han](https://github.com/adobe-fonts/source-han-sans/), [WenQuanYi Micro Hei](http://wenq.org/wqy2/)
+
+We would also like to thank the [Web Chinese Fonts Plan](https://chinese-font.netlify.app) for offering open-source tools that enable the use of Chinese fonts on the web.
 
 ---
 
@@ -303,15 +337,18 @@ The following fonts are utilized in this software, either bundled within the app
 [badge-license]: https://img.shields.io/github/license/readest/readest?color=teal
 [badge-release]: https://img.shields.io/github/release/readest/readest?color=green
 [badge-platforms]: https://img.shields.io/badge/platforms-macOS%2C%20Windows%2C%20Linux%2C%20Android%2C%20iOS%2C%20Web%2C%20PWA-green
-[badge-last-commit]: https://img.shields.io/github/last-commit/readest/readest?color=green
-[badge-commit-activity]: https://img.shields.io/github/commit-activity/m/readest/readest
+[badge-last-commit]: https://img.shields.io/github/last-commit/readest/readest?color=blue
+[badge-commit-activity]: https://img.shields.io/github/commit-activity/m/readest/readest?color=blue
 [badge-discord]: https://img.shields.io/discord/1314226120886976544?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square
 [badge-hellogithub]: https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=8a5b6ade2aee461a8bd94e59200682a7&claim_uid=eRLUbPOy2qZtDgw&theme=small
 [badge-donate]: https://donate.readest.com/badge.svg
 [badge-deepwiki]: https://deepwiki.com/badge.svg
+[badge-reddit]: https://img.shields.io/reddit/subreddit-subscribers/readest?style=flat&logo=reddit&color=F37E41
+[badge-language-coverage]: https://img.shields.io/badge/coverage-53%25%20population%20🌍-green
 [link-donate]: https://donate.readest.com/?tickers=btc%2Ceth%2Csol%2Cusdc
 [link-appstore]: https://apps.apple.com/app/apple-store/id6738622779?pt=127463130&ct=github&mt=8
 [link-website]: https://readest.com?utm_source=github&utm_medium=referral&utm_campaign=readme
+[link-flathub]: https://flathub.org/en/apps/com.bilingify.readest
 [link-web-readest]: https://web.readest.com
 [link-gh-releases]: https://github.com/readest/readest/releases
 [link-gh-commits]: https://github.com/readest/readest/commits/main
@@ -322,3 +359,6 @@ The following fonts are utilized in this software, either bundled within the app
 [link-koreader]: https://github.com/koreader/koreader
 [link-hellogithub]: https://hellogithub.com/repository/8a5b6ade2aee461a8bd94e59200682a7
 [link-deepwiki]: https://deepwiki.com/readest/readest
+[link-locales]: https://github.com/readest/readest/tree/main/apps/readest-app/public/locales
+[link-kosync-wiki]: https://github.com/readest/readest/wiki/Sync-with-Koreader-devices
+[link-reddit]: https://reddit.com/r/readest/

SECURITY.md

@@ -0,0 +1,142 @@
+# Security Policy
+
+## Threat Model
+
+### Overview
+
+Readest is a cross-platform e-reader (macOS, Windows, Linux, Android, iOS, Web) built on Next.js and Tauri. It processes user-supplied ebook files, syncs data to the cloud, integrates with external services (OPDS catalogs, KOReader, DeepL, Yandex), and handles user authentication.
+
+### Assets
+
+| Asset                          | Description                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| Ebook files                    | User-uploaded EPUB, MOBI, PDF, and other formats stored locally and in cloud storage |
+| Reading progress & annotations | Highlights, bookmarks, and notes synced across devices                               |
+| User credentials               | Authentication tokens and session data for cloud sync                                |
+| User preferences & settings    | Reading preferences, custom fonts, theme configurations                              |
+| External API keys              | Translation service credentials (DeepL, Yandex) configured by users                  |
+
+### Threat Actors
+
+| Actor                   | Motivation                                                 |
+| ----------------------- | ---------------------------------------------------------- |
+| Malicious ebook author  | Craft a malformed file to exploit the parser or renderer   |
+| Network attacker (MitM) | Intercept sync traffic to steal credentials or inject data |
+| Malicious OPDS server   | Serve crafted catalog responses to exploit the client      |
+| Compromised dependency  | Supply chain attack via npm or Cargo ecosystem             |
+| Unauthorized user       | Access another user's synced library or annotations        |
+
+### Attack Surfaces & Mitigations
+
+#### 1. Ebook File Parsing
+
+- **Risk:** Malformed EPUB/MOBI/PDF files could trigger parser bugs, path traversal, or script injection via embedded HTML/JS.
+- **Mitigations:** Ebook content is rendered in a sandboxed iframe. External script execution is blocked. File parsing is isolated from the main process.
+
+#### 2. Cloud Sync & Authentication
+
+- **Risk:** Credential theft, session hijacking, or unauthorized access to another user's library data.
+- **Mitigations:** All sync traffic uses HTTPS/TLS. Authentication tokens are stored securely (OS keychain/secure storage). Server-side authorization ensures users can only access their own data.
+
+#### 3. OPDS / External Catalog Integration
+
+- **Risk:** A malicious OPDS server could serve crafted XML to exploit the parser, or redirect downloads to malicious files.
+- **Mitigations:** OPDS responses are parsed defensively. Users explicitly add catalog sources. Downloaded files are treated as untrusted user content.
+
+#### 4. Rendered HTML/JS in Ebook Content
+
+- **Risk:** Embedded JavaScript in EPUB files could attempt XSS or data exfiltration.
+- **Mitigations:** Book content is rendered in a sandboxed iframe with scripting restrictions. Navigation outside the book context is blocked.
+
+#### 5. Supply Chain
+
+- **Risk:** Compromised npm or Cargo packages could introduce malicious code.
+- **Mitigations:** Dependencies are pinned via `pnpm-lock.yaml` and `Cargo.lock`. Dependabot and GitHub's dependency review are enabled for automated vulnerability detection.
+
+#### 6. Desktop Native Code (Tauri)
+
+- **Risk:** Tauri IPC commands could be abused by malicious web content to access the filesystem or OS APIs.
+- **Mitigations:** Tauri's allowlist restricts which IPC commands are exposed. File system access is scoped to the application data directory.
+
+### Out of Scope
+
+- Vulnerabilities in user's operating system or browser outside of Readest's control
+- Physical access attacks to a user's device
+- Issues in third-party services (DeepL, Yandex, Calibre) themselves
+
+## Supported Versions
+
+Readest does not currently maintain separate release channels. Security updates are provided only for the latest release series.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.10.x  | :white_check_mark: |
+| < 0.10  | :x:                |
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities privately. Do not open a public GitHub
+issue or discussion for security-sensitive reports.
+
+Use GitHub's private vulnerability reporting for this repository:
+
+<https://github.com/readest/readest/security/advisories/new>
+
+When submitting a report, include:
+
+- A clear description of the issue and the affected component
+- Steps to reproduce, proof of concept, or a minimal test case
+- The versions, platforms, or environments you tested
+- Any suggested remediation or mitigating details, if available
+
+What to expect after you report:
+
+- We will aim to acknowledge receipt within 3 business days.
+- We may contact you for additional details, reproduction steps, or validation.
+- If the report is accepted, we will work on a fix and coordinate disclosure.
+- If the report is declined, we will explain why, for example if the behavior is
+  expected, unsupported, or not reproducible.
+
+Please keep vulnerability details private until a fix is available and the
+maintainers have approved disclosure.
+
+## Incident Response Plan
+
+When a security vulnerability is confirmed, we follow this process:
+
+### 1. Triage (Day 1–2)
+
+- Assign a severity level (Critical / High / Medium / Low) based on impact and exploitability.
+- Identify affected versions, components, and users.
+- Assign an owner responsible for coordinating the response.
+
+### 2. Containment (Day 1–3)
+
+- Assess whether an immediate mitigation or workaround can be published.
+- Limit further exposure where possible (e.g., disable affected features, update dependencies).
+
+### 3. Remediation (Day 3–14, depending on severity)
+
+- Develop and internally review a fix.
+- Validate the fix does not introduce regressions.
+- Prepare a patched release and update changelog.
+
+### 4. Disclosure & Release
+
+- Coordinate disclosure timing with the reporter.
+- Publish a GitHub Security Advisory with CVE if applicable.
+- Release the patched version and notify users via release notes.
+
+### 5. Post-Incident Review
+
+- Document the root cause, timeline, and resolution.
+- Update processes or controls to prevent recurrence.
+
+### Severity Definitions
+
+| Severity | Description                                                           |
+| -------- | --------------------------------------------------------------------- |
+| Critical | Remote code execution, full data compromise, or authentication bypass |
+| High     | Significant data exposure, privilege escalation, or denial of service |
+| Medium   | Limited data exposure or functionality disruption                     |
+| Low      | Minor issues with minimal security impact                             |

apps/readest-app/.claude/memory/MEMORY.md

@@ -0,0 +1,47 @@
+# Readest Project Memory
+
+## Key Reference Documents
+- [Bug Fixing Patterns](bug-patterns.md) - Common bug categories, root causes, and fix strategies
+- [CSS & Style Fixes](css-style-fixes.md) - EPUB CSS override patterns and the style.ts pipeline
+- [TTS Fixes](tts-fixes.md) - Text-to-Speech architecture and bug patterns
+- [Layout & UI Fixes](layout-ui-fixes.md) - Safe insets, z-index, platform-specific UI issues
+- [Platform Compat Fixes](platform-compat-fixes.md) - Android, iOS, Linux, macOS platform-specific bugs
+- [Annotator & Reader Fixes](annotator-reader-fixes.md) - Highlight, selection, accessibility bugs
+
+## Critical Files (Most Bug-Prone)
+- `src/utils/style.ts` - Central EPUB CSS transformation hub (14+ bug fixes)
+- `packages/foliate-js/paginator.js` - Page layout, image sizing, backgrounds
+- `src/services/tts/TTSController.ts` - TTS state machine, section tracking
+- `src/hooks/useSafeAreaInsets.ts` - Safe area inset management
+- `src/app/reader/components/FoliateViewer.tsx` - Reader view orchestration
+- `src/app/reader/components/annotator/Annotator.tsx` - Annotation lifecycle
+
+## Feature Notes
+- [D-pad Navigation](dpad-navigation.md) — Android TV remote / keyboard arrow navigation design, key files, and pitfalls
+- [Cloudflare Workers WebSocket](cloudflare-workers-websocket.md) — use fetch() Upgrade pattern (not `ws` npm); CF delivers binary frames as Blob (must serialize async decodes)
+- [Share-a-Book Feature (in progress)](share-feature.md) — locked decisions for the /s/{token} share-link feature; plan at ~/.claude/plans/ok-we-will-learn-cosmic-acorn.md
+- [readest.koplugin i18n](koplugin-i18n.md) — gettext loader at `apps/readest.koplugin/i18n.lua`, `.po` catalog at `locales/<i18next-code>/translation.po`, extract/apply scripts in `scripts/`
+
+## Patterns
+- [Virtuoso + OverlayScrollbars](virtuoso_overlayscrollbars.md) — useOverlayScrollbars hook integration for overlay scrollbars on mobile webviews
+- [Design system → DESIGN.md](feedback_design_system_doc.md) — codify recurring UI/UX rules in `apps/readest-app/DESIGN.md`; never `pl/pr/ml/mr/text-left/text-right` (RTL); §5 boxed list anatomy has uniform `min-h-14` rows and chromeless controls
+
+## Architecture Notes
+- foliate-js is a git submodule at `packages/foliate-js/`
+- Multiview paginator: loads adjacent sections in background, multiple View/Overlayer instances per book
+- Style overrides: `getLayoutStyles()` (always), `getColorStyles()` (when overriding color)
+- `transformStylesheet()` does regex-based EPUB CSS rewriting at load time
+- TTS uses independent section tracking (`#ttsSectionIndex`) decoupled from view
+- Safe area insets flow: Native plugin -> useSafeAreaInsets hook -> component styles
+- Dropdown menus use `DropdownContext` (not blur-based) for screen reader compat
+
+## Workflow
+- [Test file filter](feedback_test_file_filter.md) — use `pnpm test <path>` without `--` to run a single file
+- [Always rebase before PR](feedback_pr_rebase.md) — rebase onto origin/main before creating PRs
+- [New branch per PR](feedback_pr_new_branch.md) — always create a fresh branch from main for each new PR/issue
+- [Upgrade gstack locally](feedback_gstack_upgrade.md) — always upgrade from the project's .claude/skills/gstack, not global
+- [No lookbehind regex](feedback_no_lookbehind_regex.md) — never use `(?<=)` or `(?<!)` in JS/TS; build check rejects them
+- [Use worktree](feedback_use_worktree.md) — never `git worktree add` directly; always `pnpm worktree:new` before PR review, issue fix, or feature work
+- [en/translation.json holds ONLY plural variants + proper nouns](feedback_en_plurals_manual.md) — non-plural strings stay out (defaultValue: key is the en source); plural strings (`_('...', { count })`) need hand-added `_one`/`_other` entries or the singular renders as "1 days"
+- [Never push on every change](feedback_dont_push_every_change.md) — hold pushes during active bug iteration; commit locally only until user confirms or work hits a clean done-state
+- [No test seams in production code](feedback_no_test_seams_in_prod.md) — production must never import or call `__reset*ForTests`; cross-module test resets belong in the test file's beforeEach/afterEach

apps/readest-app/.claude/memory/annotator-reader-fixes.md

@@ -0,0 +1,90 @@
+# Annotator & Reader Fixes Reference
+
+## Annotation System Architecture
+
+### Key Components
+- `Annotator.tsx` - Annotation lifecycle, popup display, style/color management
+- `AnnotationRangeEditor.tsx` - Drag handles for adjusting selection range
+- `MagnifierLoupe.tsx` - Magnifying glass during handle drag (mobile only)
+- `useTextSelector.ts` - Text selection detection and processing
+- `useAnnotationEditor.ts` - Editing existing annotations
+- `useInstantAnnotation.ts` - Creating new annotations on selection
+
+### Highlight Rendering
+- Highlights rendered by foliate-js `Overlayer` (SVG overlayer in paginator shadow DOM, not iframe)
+- Each view in multiview paginator has its own `Overlayer` instance with unique clipPath ID
+- `Overlayer.add()` stores range + draw function; `redraw()` recalculates positions from stored ranges
+- Colors stored as color names mapped to custom hex via `globalReadSettings.customHighlightColors`
+- Sidebar uses `color-mix()` CSS function with custom colors, not Tailwind utility classes (#3273)
+- Rounded highlight style supported via `vertical` option passed to overlayer (#3208)
+
+### Multiview Overlayer Pitfalls
+- **Duplicate SVG IDs**: Each overlayer creates `<clipPath>` for loupe hole — IDs MUST be unique per instance or `url(#id)` resolves to wrong element, clipping everything
+- **docLoadHandler scope**: `FoliateViewer.tsx` re-adds annotations on `load` event — MUST filter by `detail.index` (loaded section), not re-add ALL annotations (overwrites drag edits)
+- **MagnifierLoupe lifecycle**: Don't destroy/recreate loupe on every drag tick — `hideLoupe()` should only run on unmount, `showLoupe()` fast path updates position only
+- **Stale closures in useTextSelector**: `getProgress()` must be called inside callbacks, not captured at hook top-level (useFoliateEvents deps are `[view]` only)
+
+## Fix History
+
+| Issue | Problem | Root Cause | Fix |
+|-------|---------|------------|-----|
+| #3286 | Selection stuck on first annotation | `initializedRef` guard blocked re-computation | Remove guard, consolidate style/color effects |
+| #3273 | Custom colors not in sidebar | Hardcoded Tailwind classes | Use inline `style` with `color-mix()` |
+| #3234 | Letter-by-letter selection on mobile | No word boundary snapping | Add `snapRangeToWords()` using `Intl.Segmenter` |
+| #3208 | Hard rectangular highlights | No border radius support | Pass `vertical` option, update foliate-js |
+| #3002 | Can't see text under finger | No magnification UI | New `MagnifierLoupe` component using `view.renderer.showLoupe()` |
+| #3082 | No page numbers on annotations | `pageNumber` field missing | Add `pageNumber` to BookNote type, compute on create |
+| #3225 | Android tools unresponsive | Premature `makeSelection()` call | Remove premature re-selection in Android path |
+
+## Common Annotation Bugs
+
+### Selection Issues
+- **Word snapping**: Uses `Intl.Segmenter` with `granularity: 'word'` to snap selection to word boundaries
+- **Android re-selection**: Don't call `makeSelection(sel, index, true)` immediately on pointer-up; let the popup flow complete
+- **Range editor handles**: Remove `initializedRef` guards that prevent re-computation when switching annotations
+
+### Color/Style Issues
+- **Custom colors in sidebar**: Use inline `style={{ backgroundColor: 'color-mix(...)' }}` not Tailwind classes
+- **Style synchronization**: Consolidate `selectedStyle` and `selectedColor` into one `useEffect`
+- **Switching annotations**: Must call `setShowAnnotPopup(false)` and `setEditingAnnotation(null)` before setting up new annotation
+
+## Reader/Content Fixes
+
+### Progress Display
+- Use physical `view.renderer.page` and `view.renderer.pages` for page counts (#3213, #3200)
+- Last page shows 100% by fixing boundary condition (#3383)
+- FB2 subsections need special handling for progress (#3136)
+
+### Translation View (#3078)
+- Problem: Page jumps back during full-text translation
+- Root cause: DOM mutations from sequential translation insertions cause paginator relayout
+- Fix: Batch DOM updates with 50ms timer, use bounded concurrent queue (max 5), show loading overlay
+
+### TOC Navigation (#3124)
+- Problem: Expanding TOC chapter scrolls back to current chapter
+- Fix: Only scroll-into-view on navigation, not on expand/collapse
+
+## Accessibility (a11y) Fixes
+
+### Screen Reader (TalkBack) Support
+- **Page indicator updates** (#2276): Add focus handlers on `<p>` elements that call `view.goTo(cfi)` to update position
+- **Navigation buttons** (#3036): Always show prev/next buttons when screen reader active; `PageNavigationButtons.tsx`
+- **Dropdown menus** (#3035): Use `DropdownContext` with overlay dismiss instead of blur-based closing
+
+### Dropdown Architecture for a11y
+- `DropdownContext` (`src/context/DropdownContext.tsx`) manages which dropdown is open globally
+- Uses `useId()` for unique identification
+- One dropdown open at a time
+- `<Overlay>` for dismissal (tap/click outside) instead of `onBlur`
+- `<details>` element with `open={isOpen}` for semantic structure
+- No auto-focus-first-item (conflicts with TalkBack)
+
+## E-ink Readability
+- Use `not-eink:` Tailwind variant for colors and opacity (#3258)
+- Don't use `text-primary` (blue) or low opacity on e-ink
+- Highlights use foreground color in dark mode e-ink (#3299)
+
+## Key Utility Functions
+- `snapRangeToWords()` in `src/utils/sel.ts` - Word boundary snapping
+- `handleAccessibilityEvents()` in `src/utils/a11y.ts` - Screen reader focus handling
+- `color-mix()` CSS function for custom highlight colors with opacity

apps/readest-app/.claude/memory/bug-patterns.md

@@ -0,0 +1,126 @@
+# Bug Fixing Patterns & Strategies
+
+## Common Root Cause Categories
+
+### 1. Overly Broad CSS Selectors
+**Pattern:** A CSS rule targets too many elements, causing unintended visual side effects.
+**Examples:**
+- `hr { mix-blend-mode: multiply }` applied to ALL hr elements instead of only decorative ones (#3086)
+- `p img { mix-blend-mode }` applied to block images, not just inline (#3112)
+- `svg, img { height: auto; width: auto }` overrode explicit HTML width/height attributes (#3274)
+- Background-color override applied unconditionally instead of only when user enabled color override (#3316)
+
+**Fix Strategy:** Narrow selectors with class qualifiers (`.background-img`, `.has-text-siblings`) or attribute pseudo-selectors (`:where(:not([width]))`). Check if the rule should be conditional on a user setting.
+
+### 2. Conditional vs Unconditional Style Overrides
+**Pattern:** CSS rules meant for "Override Book Color/Layout" mode are placed in the always-active stylesheet.
+**Examples:**
+- Calibre `.calibre { color: unset }` was in `getLayoutStyles()` instead of `getColorStyles()` (#3448)
+- Image background-color override applied without checking `overrideColor` flag (#3316, #3377)
+
+**Fix Strategy:** Move rules to the correct conditional block: `getColorStyles()` for color overrides, `getLayoutStyles()` for layout overrides. Check the `overrideColor`/`overrideLayout` flags.
+
+### 3. Missing EPUB Stylesheet Transformations
+**Pattern:** EPUB stylesheets contain CSS that conflicts with app functionality.
+**Examples:**
+- `user-select: none` prevents text selection (#3370) -> regex replace in `transformStylesheet()`
+- `font-family: serif/sans-serif` on body bypasses user font (#3334) -> detect and unset
+- Hardcoded Calibre backgrounds persist in dark mode (#3448) -> unset in color override
+
+**Fix Strategy:** Add regex-based transformation passes in `transformStylesheet()` in `style.ts`.
+
+### 4. Stale State / Refs Not Reset
+**Pattern:** A `useRef` or state variable is set once and never properly reset, blocking re-entry.
+**Examples:**
+- TTS `ttsOnRef` prevented restarting TTS from a new location (#3292)
+- `initializedRef` in AnnotationRangeEditor prevented handle position updates (#3286)
+- `view.tts` not nulled on shutdown prevented clean TTS restart (#3400)
+- TTS safety timeout fired after pause, advancing to next sentence (#3244)
+
+**Fix Strategy:** Check all refs/guards in the affected flow. Ensure cleanup in shutdown/unmount. Remove overly aggressive guards that prevent re-entry.
+
+### 5. Platform API Differences
+**Pattern:** A Web API behaves differently or is unavailable on certain platforms.
+**Examples:**
+- `navigator.getGamepads()` returns null on older Android WebView (#3245)
+- `CompressionStream` unavailable on some Android versions (#3255)
+- `btoa()` throws on non-ASCII characters (#3436)
+- View Transitions API unsupported in WebKitGTK/Linux (#3417)
+- `document.startViewTransition()` crashes on Linux
+
+**Fix Strategy:** Always check API availability before use. Add fallback paths. Use feature detection, not platform detection when possible.
+
+### 6. Safe Area Inset Issues
+**Pattern:** UI elements overlap system bars (status bar, navigation bar, notch) on mobile.
+**Examples:**
+- Zoom controls behind status bar (#3426)
+- Android navigation bar overlap (#3466)
+- iPad sidebar insets incorrect (#3395)
+- Reader page layout jump after system UI change (#3469)
+
+**Fix Strategy:** Use `gridInsets` and `statusBarHeight` from `useSafeAreaInsets`. Use `env(safe-area-inset-*)` CSS functions. Call `onUpdateInsets()` after system UI visibility changes. See `docs/safe-area-insets.md`.
+
+### 7. Z-Index Layering Issues
+**Pattern:** Interactive elements rendered behind other layers, becoming unclickable.
+**Examples:**
+- Navigation buttons invisible on mobile (#3201) -> added `z-10`
+- Annotation nav bar too prominent (#3386) -> reduced from `z-30` to `z-10`
+- Page nav buttons behind TTS control (#3184)
+
+**Fix Strategy:** Check z-index ordering. Use minimum necessary z-index. Reference the z-index hierarchy in the codebase.
+
+### 8. Event Handling Race Conditions
+**Pattern:** Timing issues between pointer events, native menus, and React state updates.
+**Examples:**
+- macOS context menu steals pointer event loop (#3324) -> 100ms setTimeout delay
+- Traffic light buttons flicker due to timeout race (#3488, #3129)
+- Android tool buttons unresponsive due to premature re-selection (#3225)
+
+**Fix Strategy:** Add small delays before native menu calls. Check event state machine consistency. Remove premature re-triggers on Android.
+
+### 9. foliate-js Rendering Issues
+**Pattern:** Bugs in the lower-level EPUB renderer (paginator.js, epub.js).
+**Examples:**
+- Image size not constrained in double-page mode (#3432)
+- Background not shown in scrolled mode (#3344)
+- Section content cached incorrectly after mode switch (#3242, #3206)
+- Swipe sensitivity too low for non-animated paging (#3310)
+
+**Fix Strategy:** Check both `columnize()` and `scrolled()` code paths in paginator.js. Verify CSS variables (`--available-width`, `--available-height`) are computed correctly. Test in both paginated and scrolled modes.
+
+### 10. Progress/Navigation Calculation Errors
+**Pattern:** Page counts, progress percentages, or position tracking are wrong.
+**Examples:**
+- Progress shows 99.9% at last page (#3383) -> boundary condition
+- Pages left shows estimated instead of physical count (#3213, #3200)
+- FB2 subsection progress wrong (#3136) -> nested structure not handled
+- TOC auto-scrolls on expand (#3124) -> scroll-into-view triggered too broadly
+
+**Fix Strategy:** Use physical `view.renderer.page`/`view.renderer.pages` instead of estimated section metadata. Check boundary conditions (0-indexed vs 1-indexed, inclusive vs exclusive).
+
+### 11. Debounced State Stale on User-Initiated Layout Change
+**Pattern:** A scroll/resize handler is debounced for performance, but during the debounce window any code path that re-runs layout based on saved state (e.g. `#anchor`, `#primaryIndex`) sees stale values.
+**Example:**
+- Scrolled-mode toggle reverted to previous chapter (#3987): the paginator's scroll handler is debounced 250 ms, so toggling `flow=scrolled → flow=paginated` within that window made `render() → scrollToAnchor(#anchor)` restore the anchor from before the user scrolled into the next section. Both `#anchor` and `#primaryIndex` were stale together, sending the position back.
+
+**Fix Strategy:** When an external trigger forces a re-render (here, `setAttribute('flow', ...)`), flush the debounced state synchronously *before* changing the layout. In paginator.js this means overriding `setAttribute` and calling `#detectPrimaryView()` + `#getVisibleRange()` while `this.scrolled` is still true.
+
+### 12. Multiview Paginator Side Effects
+**Pattern:** The multiview paginator (e925e9d+) loads adjacent sections in background. Events from these loads can interfere with user interactions on the primary section.
+**Examples:**
+- `load` event from adjacent section triggers `docLoadHandler` which re-adds ALL annotations, overwriting drag edits
+- Multiple overlayers with duplicate SVG `<clipPath>` IDs cause `url(#id)` to resolve to wrong element
+- `MagnifierLoupe` destroying/recreating body clone on every drag tick triggers ResizeObserver → expand → redraw
+
+**Fix Strategy:** Scope event handlers to the loaded section's index. Use unique IDs for SVG elements across overlayer instances. Minimize iframe DOM mutations during drag operations.
+
+## Debugging Workflow
+
+1. **Identify the category** from the issue description
+2. **Check `style.ts`** first for any CSS-related visual bugs
+3. **Check foliate-js** for rendering/layout bugs
+4. **Check platform-specific code** for mobile/desktop differences
+5. **Write a failing test** before implementing the fix
+6. **Test in both paginated and scrolled modes** for layout changes
+7. **Test on multiple platforms** for any UI change
+8. **Run `pnpm build-check`** before submitting

apps/readest-app/.claude/memory/cloudflare-workers-websocket.md

@@ -0,0 +1,73 @@
+---
+name: Cloudflare Workers WebSocket
+description: How to open and read WebSockets from Cloudflare Workers (the Node `ws` package does not work) and the Blob binary-frame gotcha
+type: project
+originSessionId: ec3d5424-adc2-4fca-836f-df323797489c
+---
+# Cloudflare Workers WebSocket on readest-app
+
+## Why the Node `ws` package fails
+
+The Node `ws` npm package (used transitively by `isomorphic-ws`) opens WebSockets by calling `http.request({ createConnection })`. The Cloudflare Workers runtime does not implement `options.createConnection`, so any attempt to `new WebSocket(url, { headers })` in a Worker throws:
+
+```
+The options.createConnection option is not implemented
+```
+
+This applies even with `compatibility_flags = ["nodejs_compat"]`.
+
+## Correct pattern: fetch-based upgrade
+
+On Workers you open a WebSocket by calling `fetch()` with an `Upgrade: websocket` header against the **https://** (not `wss://`) form of the URL. The response has `status === 101` and a non-standard `webSocket` property that must be `accept()`ed before use:
+
+```ts
+const upgradeUrl = url.replace(/^wss:\/\//i, 'https://');
+const response = (await fetch(upgradeUrl, {
+  headers: { ...baseHeaders, Upgrade: 'websocket' },
+})) as Response & { webSocket?: WebSocket & { accept(): void } };
+
+if (response.status !== 101 || !response.webSocket) {
+  throw new Error(`WebSocket upgrade failed with status ${response.status}`);
+}
+
+const ws = response.webSocket;
+ws.addEventListener('message', onMessage);
+ws.accept();
+ws.send(payload);
+```
+
+Detect the Workers runtime with `typeof globalThis.WebSocketPair !== 'undefined'` — `WebSocketPair` is a Workers-only global.
+
+## Binary frames arrive as Blob (critical)
+
+Cloudflare Workers deliver WebSocket binary frames as **`Blob`** — not `ArrayBuffer` (browsers) and not `Uint8Array` (Node `ws`). Blob decoding is async via `blob.arrayBuffer()`, so:
+
+1. You must serialize decodes through a promise chain to keep frames in receive order — otherwise parallel awaits can merge bytes out of order.
+2. Any terminal text message (e.g. Edge TTS's `Path: turn.end`) arrives **synchronously** and will finalize the stream before the in-flight Blob decodes have flushed. Always `await pendingBinary` in the turn.end handler and the close handler before checking whether data was received.
+
+Example skeleton:
+
+```ts
+let pending: Promise<void> = Promise.resolve();
+const enqueue = (getBuf: () => Promise<ArrayBufferLike> | ArrayBufferLike) => {
+  pending = pending.then(async () => {
+    const buf = await getBuf();
+    appendBinary(buf);
+  });
+};
+
+ws.addEventListener('message', (event) => {
+  const data = event.data;
+  if (data instanceof Blob) enqueue(() => data.arrayBuffer());
+  else if (data instanceof ArrayBuffer) enqueue(() => data);
+  else if (data instanceof Uint8Array) enqueue(() => data.buffer.slice(
+    data.byteOffset, data.byteOffset + data.byteLength,
+  ));
+  // ... handle text path: turn.end
+  //     -> await pending, then resolve
+});
+```
+
+## Where this is used
+
+`src/libs/edgeTTS.ts` `#fetchEdgeSpeechWs` has three branches: Tauri (plugin-websocket), Cloudflare Workers (fetch upgrade + Blob handling), and browser/Node fallback (`isomorphic-ws`). The route that exercises the CF branch is `src/app/api/tts/edge/route.ts`, hit when the web client falls back from direct `wss://` (which browsers can't set headers on) to the `/api/tts/edge` HTTPS endpoint.

apps/readest-app/.claude/memory/css-style-fixes.md

@@ -0,0 +1,74 @@
+# CSS & Style Fixes Reference
+
+## The `style.ts` Pipeline (`src/utils/style.ts`)
+
+This is the most bug-prone file in the codebase (14+ fixes). It handles all EPUB CSS transformations.
+
+### Key Functions
+
+#### `getLayoutStyles()`
+- Always-active styles applied to every EPUB section
+- Controls: line-height, hyphens, image sizing, table display
+- Rules here should NOT be conditional on user settings
+- Common mistake: putting color-related rules here instead of `getColorStyles()`
+
+#### `getColorStyles()`
+- Conditionally applied when user enables "Override Book Color"
+- Controls: foreground/background colors, mix-blend modes, image backgrounds
+- Gate rules on `overrideColor` flag
+
+#### `transformStylesheet()`
+- Regex-based rewriting of EPUB CSS at load time
+- Runs on every stylesheet loaded from the EPUB
+- Used to neutralize problematic EPUB CSS declarations
+
+#### `applyTableStyle()`
+- Post-render function that scales tables to fit available width
+- Uses `getComputedStyle()` (not inline `style.width`) to read actual width
+- Has two scaling paths: column-width-based and parent-container-based
+
+### Fix History by Issue
+
+| Issue | Problem | Fix in style.ts |
+|-------|---------|-----------------|
+| #3494 | Line spacing not on `<li>` | Added `li` CSS rule for `line-height` and `hyphens` |
+| #3448 | Calibre colors persist | Moved `.calibre` unset to `getColorStyles()`, added `background-color: unset` |
+| #3441 | Body padding/margin | Added `padding: unset; margin: unset` to body in `getLayoutStyles()` |
+| #3316 | Image bg unconditional | Made `background-color` rule conditional on `overrideColor` |
+| #3377 | Image bg override | Same pattern as #3316, only override when `overrideColor` is true |
+| #3334 | Generic font-family | `transformStylesheet()` replaces `font-family: serif/sans-serif` with `unset` on body |
+| #3370 | user-select: none | `transformStylesheet()` replaces all `user-select: none` with `unset` |
+| #3284 | Table scaling | Added fallback when `totalTableWidth` is 0 but parent has width |
+| #3351 | Table display broken | Added `display: table !important` to table rule |
+| #3274 | Image dimensions | Changed selectors to `:where(:not([width]))` and `:where(:not([height]))` |
+| #3205 | Table width reading | Changed from `style.width` to `getComputedStyle().width`, fixed CSS var unit |
+| #3112 | Mix-blend on all images | Narrowed selector to `.has-text-siblings` class |
+| #3086 | Mix-blend on hr | Narrowed selector to `hr.background-img` |
+| #3012 | Vertical alignment | Fixed available dimensions (subtract insets), replaced `100vw/vh` with CSS vars |
+
+### Common Patterns
+
+1. **Adding new element rules:** Copy the pattern from `p` rules (e.g., adding `li` for #3494)
+2. **EPUB CSS neutralization:** Add regex in `transformStylesheet()` to replace problematic declarations
+3. **Conditional overrides:** Use `overrideColor`/`overrideLayout` flags to gate rules
+4. **Selector narrowing:** Use class qualifiers or attribute pseudo-selectors to avoid over-matching
+5. **Table fixes:** Always use `getComputedStyle()`, not inline style. Check both width paths.
+
+### CSS Variables from foliate-js
+
+- `--available-width` - Usable content width (set by paginator.js)
+- `--available-height` - Usable content height
+- `--full-width` - Full viewport width (numeric, multiply by 1px)
+- `--full-height` - Full viewport height (numeric, multiply by 1px)
+- `--overlayer-highlight-opacity` - Highlight transparency (default 0.3)
+
+### foliate-js Rendering (`packages/foliate-js/paginator.js`)
+
+Key functions:
+- `columnize()` - Paginated layout path
+- `scrolled()` - Scrolled layout path
+- `setImageSize()` - Constrains image dimensions to available space
+- `#replaceBackground()` - Transfers EPUB backgrounds to paginator layer
+- `snap()` - Swipe gesture detection for page turning
+
+Common issue: A fix applied to `columnize()` but not `scrolled()` (or vice versa). Always check both paths.

apps/readest-app/.claude/memory/dpad-navigation.md

@@ -0,0 +1,40 @@
+---
+name: D-pad Navigation Design
+description: Android TV / Bluetooth remote D-pad navigation architecture, key files, and pitfalls encountered during implementation
+type: project
+---
+
+## D-pad Navigation Architecture
+
+D-pad support enables Bluetooth remote controller navigation on Android TV (and keyboard arrow navigation on desktop).
+
+### Key Files
+
+- `src/app/reader/hooks/useSpatialNavigation.ts` — Reader toolbar D-pad navigation. Left/Right navigates between buttons, Up/Down moves between header↔footer. Auto-focuses first button on show. Uses focus-probe technique for visibility detection.
+- `src/app/library/hooks/useSpatialNavigation.ts` — Library grid D-pad navigation. Arrow keys move between BookshelfItem elements. ArrowDown from outside bookshelf (e.g. header) enters the grid via window-level listener.
+- `src/helpers/shortcuts.ts` — `onToggleToolbar` (Enter key) toggles reader toolbar visibility.
+- `src/app/reader/hooks/useBookShortcuts.ts` — `toggleToolbar` handler shows/hides header+footer bars. Skips when a `<button>` is focused (lets native click fire).
+- `src/__tests__/hooks/useSpatialNavigation.test.tsx` — Unit tests for reader toolbar navigation.
+
+### Design Decisions
+
+- **No third-party library**: Tried `@noriginmedia/norigin-spatial-navigation` but it failed due to init timing issues (React child effects run before parent effects) and conflicts with the existing `useShortcuts` system. Custom solution is simpler and more reliable.
+- **Two `useSpatialNavigation` hooks**: Same name in different directories — library version handles grid navigation, reader version handles toolbar button navigation. Different navigation patterns but same concept.
+- **Platform-agnostic hooks**: Both `useSpatialNavigation` hooks work on all platforms, not just Android.
+- **Focus-probe for visibility**: `offsetParent` is unreliable for detecting visible buttons (returns null inside `position: fixed` containers on mobile). Instead, try `btn.focus()` and check if `document.activeElement === btn` — this correctly handles all hiding methods (display:none, visibility:hidden, fixed positioning).
+
+### Pitfalls
+
+1. **WebView spatial navigation conflict**: Android WebView has built-in spatial navigation that intercepts D-pad arrow keys and moves DOM focus between `tabIndex>=0` elements. Added `tabIndex={-1}` to non-interactive overlay elements (HeaderBar trigger, ProgressBar, FooterBar trigger, SectionInfo) to prevent focus theft.
+
+2. **`eventDispatcher.dispatchSync` short-circuits**: When multiple handlers are registered for `native-key-down`, the first handler returning `true` stops propagation. The FooterBar's Back handler fires before the Reader's. Both must independently call `blur()` — can't rely on the Reader's handler running.
+
+3. **Must blur on toolbar dismiss**: When Back/Escape dismisses the toolbar, the focused button must be blurred. Otherwise `document.activeElement` remains a hidden button, and `toggleToolbar` skips Enter when `activeElement.tagName === 'BUTTON'`. Blur is called in FooterBar's handleKeyDown (for Back and Escape) and in Reader's handleKeyDown.
+
+4. **Arrow key trapping must use `stopPropagation`**: Without it, arrow keys bubble to `window` where `useShortcuts` handles them as page turns. The toolbar keydown handler on the container div calls `e.stopPropagation()` + `e.preventDefault()` to prevent this.
+
+5. **Library grid needs window-level listener**: The bookshelf container keydown handler only fires when focus is inside it. A separate `window` keydown listener handles ArrowDown from the header into the grid (when focus is outside the container).
+
+6. **Auto-focus race on toolbar show**: Both header and footer bars auto-focus their first button when `isVisible` becomes true simultaneously. The last effect to run wins. This is acceptable — user can navigate between them with Up/Down.
+
+7. **`offsetParent` null in fixed containers**: On mobile, `.footer-bar` uses `position: fixed`. All child buttons have `offsetParent === null`, making `offsetParent`-based visibility checks useless. The focus-probe approach (try focus, check activeElement) is the reliable alternative.

apps/readest-app/.claude/memory/feedback_design_system_doc.md

@@ -0,0 +1,49 @@
+---
+name: Design rules live in DESIGN.md
+description: Readest has a design system doc — codify recurring UI/UX rules there, don't just apply them ad-hoc. Memory points at the canonical location and the patterns it covers.
+type: feedback
+originSessionId: 85757e57-a029-40f8-b098-88039c43514b
+---
+The project's design system is documented at `apps/readest-app/DESIGN.md`.
+**When the user articulates a UI/UX rule** ("X should always Y", "we follow Z
+convention"), add it to DESIGN.md so it persists for the team and for future
+sessions — don't just apply it inline and move on.
+
+**Why:** Readest's UI is Adwaita-aligned, e-ink-first, cross-platform-aware.
+A doc'd system avoids drift across panels and gives reviewers a reference
+point. The user explicitly asked to "remember the UI/UX rules somewhere"
+when refining the OPDS Integration sub-page.
+
+**How to apply:** When the user surfaces a new rule:
+1. Add it to the appropriate `DESIGN.md` section (numbered principles in §2,
+   anatomy details in §5, anti-patterns in §10).
+2. Cross-reference from related sections so it's discoverable from multiple
+   entry points.
+3. Save the actual code change reference if it captures a canonical example.
+
+**Rules already codified there (don't re-invent — reference instead):**
+- §2.1–2.7: surface continuity, color discipline, two-step depth, localized
+  hover, motion=color, eink-first, focus visibility.
+- §2.8: RTL — always use logical properties (`ps`/`pe`/`ms`/`me`/`text-start`
+  /`text-end`/`border-s`/`border-e`/`start-*`/`end-*`). Never `pl`/`pr`/`ml`
+  /`mr`/`text-left`/`text-right`/`left-*`/`right-*`. The user is strict on
+  this — Readest ships RTL languages.
+- §2.9: every panel/sub-page must open with title + one-line description.
+- §3: surface tier hierarchy (window/view/card → base-200/100-tinted/100).
+- §4: action vocabulary (Accent CTA, Suggested, Flat, Pill, Destructive,
+  ListExtension).
+- §5: boxed list anatomy + uniform row height (`min-h-14 items-center`,
+  never `py-3`) + chromeless controls inside the box + end-aligned values
+  with custom `<MdArrowDropDown>` icon (don't trust daisyui's bg-image
+  chevron for trailing-edge alignment).
+- §8: e-ink overlay rules.
+- §10: anti-pattern catalog with real before/after examples.
+
+**Common file paths to remember:**
+- `apps/readest-app/DESIGN.md` — source of truth.
+- `apps/readest-app/src/components/settings/SubPageHeader.tsx` — title +
+  description sub-page primitive that embodies §2.9.
+- `apps/readest-app/src/components/settings/integrations/` — the canonical
+  reference implementation of the boxed-list-with-rows pattern.
+- `apps/readest-app/src/styles/globals.css` — eink overlay rules at
+  `[data-eink='true']`.

apps/readest-app/.claude/memory/feedback_dont_push_every_change.md

@@ -0,0 +1,11 @@
+---
+name: Don't push on every change
+description: Commit when work is done; don't auto-push every iteration during active debugging
+type: feedback
+originSessionId: 49a72b36-8f45-4a57-87e1-e10563bac47a
+---
+Don't `git push` after each commit while a bug is being actively iterated on. Commit locally as needed but hold the push.
+
+**Why:** When a fix doesn't actually solve the user-reported bug, every push is wasted CI cycles + remote churn the user has to look past on the PR. The user is testing live and will tell us when something's actually verified.
+
+**How to apply:** During debugging or fix iterations on a single user-reported bug, commit locally only. Push when (a) the user confirms the fix works, (b) the user explicitly asks to push, or (c) we hit a clean done-state on a multi-step task. New commits + lint/test green is not enough.

apps/readest-app/.claude/memory/feedback_en_plurals_manual.md

@@ -0,0 +1,28 @@
+---
+name: en/translation.json holds ONLY plural variants and proper-noun overrides
+description: For non-plural strings, do NOT add to en/translation.json — the source-code key IS the en value via `defaultValue: key`. ONLY plural strings need explicit `_one`/`_other` entries in en, because i18next needs the forms to pick from.
+type: feedback
+originSessionId: e4ddc690-b1a9-4557-855f-d4e67055824f
+---
+
+**Rule:** `public/locales/en/translation.json` is hand-curated and contains essentially two kinds of entries:
+
+1. **Plural variants** (`<base>_one`, `<base>_other`, and locale-specific `_few`/`_many`/etc. as needed by CLDR). i18next MUST find these to know which form to render — without them, `count: 1` falls back to the bare key like `{{count}} days` and renders "1 days" instead of "1 day".
+2. **Proper-noun overrides** (e.g., font names like `LXGW WenKai GB Screen`) where the en value differs from the key.
+
+Everything else — ordinary translatable strings like `Sign in to share books` — does NOT belong in en/translation.json. The translation hook calls `t(key, { defaultValue: key, ...options })`, so for any string not in en/translation.json, i18next renders the key itself. That's why a 51-key en file works for a codebase with thousands of `_()` callsites.
+
+**Why en is hand-curated:** the project's `i18next-scanner.config.cjs` lists every locale EXCEPT `en` in its `lngs` array. The scanner generates `__STRING_NOT_TRANSLATED__` placeholders only for the listed locales; `en` is never touched.
+
+**Workflow when adding `_(...)` calls:**
+
+- **Non-plural string** (e.g. `_('Sign in to share books')`): add the `_(...)` call, run `pnpm run i18n:extract`, translate the new placeholders in non-en locales. **Do NOT touch `en/translation.json`** — the key itself is the en value.
+- **Plural string** (e.g. `_('{{count}} days', { count: n })`): same as above, PLUS hand-add `<base>_one` and `<base>_other` to `en/translation.json` (and `_few`/`_many`/etc. only if the source language ever needs them, which English doesn't). Convention from existing entries (e.g., `Are you sure to delete {{count}} selected book(s)?_one` → `Are you sure to delete {{count}} selected book?`): keep `{{count}}` interpolated even in `_one`, and swap any `(s)` placeholder to the proper singular/plural noun.
+
+**Audit script:** walk `src/`, regex-match `_('...', { ..., count: ... })`, for each base key verify both `<base>_one` and `<base>_other` exist in `en/translation.json`. (See conversation history for an implementation.)
+
+**Where this bit us:**
+
+- Initial bug: `_('{{count}} days', { count: n })` rendered "1 days" because en had no `_one` form.
+- Audit found 16 missing en plural keys from earlier PRs (OPDS / TTS / dictionary import) silently rendering wrong.
+- Then overcorrected and added non-plural keys like `Sign in to share books` to en/translation.json — wrong, breaks the project's convention. en stays clean for non-plural strings.

apps/readest-app/.claude/memory/feedback_gstack_upgrade.md

@@ -0,0 +1,11 @@
+---
+name: gstack upgrade location
+description: Always upgrade gstack from the project directory (.claude/skills/gstack), not from a global install
+type: feedback
+---
+
+When upgrading gstack, always run the upgrade from the current project's `.claude/skills/gstack` directory (local-git install), not from a global install path.
+
+**Why:** The project uses a local-git gstack install at `apps/readest-app/.claude/skills/gstack`. Previous mistakes upgraded a global copy while the project's local copy stayed outdated.
+
+**How to apply:** When `/gstack-upgrade` is invoked, ensure the `cd` and `git reset --hard origin/main && ./setup` happen inside the project's `.claude/skills/gstack` directory.

apps/readest-app/.claude/memory/feedback_no_lookbehind_regex.md

@@ -0,0 +1,11 @@
+---
+name: No lookbehind regex
+description: Never use lookbehind assertions in JS/TS code — the build check rejects them for browser compatibility
+type: feedback
+---
+
+Never use lookbehind regex (`(?<=...)` or `(?<!...)`) in JavaScript/TypeScript source code. Use `(?:^|[^...])` or other alternatives instead.
+
+**Why:** The project has a `check:lookbehind-regex` build check (`pnpm check:all`) that scans the Next.js output chunks and fails if any lookbehind assertions are found. Older WebViews (especially on some Android devices) don't support lookbehinds.
+
+**How to apply:** When writing regex that needs to assert what comes before a match, use a non-capturing group with alternation (e.g., `(?:^|[^a-z-])`) instead of a negative lookbehind (`(?<![a-z-])`). This applies to all `.ts`/`.tsx`/`.js` files that end up in the build output.

apps/readest-app/.claude/memory/feedback_no_test_seams_in_prod.md

@@ -0,0 +1,24 @@
+---
+name: No test seams in production code
+description: Never import or call `__reset*ForTests` (or any test-only helper) from production modules — keep test orchestration on the test side
+type: feedback
+originSessionId: 49a72b36-8f45-4a57-87e1-e10563bac47a
+---
+Production code must never import or call functions named `__reset*ForTests`
+(or any other test-only seam). If a `__resetXForTests` function in module A
+needs to also clear state owned by module B, the test file is responsible
+for calling both resets — not module A's reset chaining into module B's.
+
+**Why:** Importing a test-only helper into a production module pulls the
+test seam into the prod import graph, blurs the test/prod boundary, and
+risks the helper being shipped or mistakenly called at runtime. Caught
+once in `src/services/sync/replicaSync.ts` where
+`__resetReplicaSyncForTests` had been changed to call
+`__resetSettledEventsForTests` from `@/utils/event` for "convenience."
+
+**How to apply:**
+- A `__resetXForTests` function should clear ONLY its own module's state.
+- If a test needs a coordinated reset across modules, do it in the test
+  file's `beforeEach` / `afterEach` — call each module's seam directly.
+- Never `import { __reset...ForTests }` inside `src/` outside of
+  `src/__tests__/`. A grep `grep -rn "__reset.*ForTests" src/ --include="*.ts" --include="*.tsx" | grep -v __tests__ | grep -v "^.*export const __reset"` should return zero hits.

apps/readest-app/.claude/memory/feedback_pr_new_branch.md

@@ -0,0 +1,11 @@
+---
+name: Always use a new branch for new PRs
+description: Each new PR/issue should get its own fresh branch from main, never reuse an existing feature branch
+type: feedback
+---
+
+Always create a new branch from main for each new PR or issue. Never reuse an existing feature branch for unrelated work.
+
+**Why:** The user corrected this when a storage fix was committed on the `feat/full-sync-annotations` branch instead of a dedicated branch. Mixing unrelated changes on the same branch makes PRs harder to review and manage.
+
+**How to apply:** Before committing fixes, create a new branch like `fix/<topic>` from `origin/main`. Only reuse a branch if the work is directly related to that branch's existing purpose.

apps/readest-app/.claude/memory/feedback_pr_rebase.md

@@ -0,0 +1,11 @@
+---
+name: Always rebase before PR
+description: Rebase to origin/main before creating pull requests
+type: feedback
+---
+
+Always rebase the branch onto origin/main before creating a pull request.
+
+**Why:** The user wants PRs to be up-to-date with main to avoid merge conflicts and keep a clean history.
+
+**How to apply:** Before running `gh pr create`, always run `git fetch origin && git rebase origin/main` first. If there are conflicts, resolve them before proceeding.

apps/readest-app/.claude/memory/feedback_test_file_filter.md

@@ -0,0 +1,11 @@
+---
+name: test-file-filter
+description: Use pnpm test/test:browser with path directly (no --) to run a single test file
+type: feedback
+---
+
+Run a specific test file with `pnpm test <path>` or `pnpm test:browser <path>` — no `--` separator.
+
+**Why:** Adding `--` before the path (e.g. `pnpm test:browser -- <path>`) causes vitest to ignore the file filter and run all test files. Without `--`, pnpm appends the path directly to the vitest command, which correctly filters to that file only.
+
+**How to apply:** Always use `pnpm test src/__tests__/foo.test.ts` or `pnpm test:browser src/__tests__/foo.browser.test.tsx` when verifying a specific test file.

apps/readest-app/.claude/memory/feedback_use_worktree.md

@@ -0,0 +1,18 @@
+---
+name: Use worktree for PR/issue/feature work
+description: Always create a git worktree with pnpm worktree:new before reviewing PRs, fixing issues, or implementing features
+type: feedback
+originSessionId: 650f8ff2-980d-459f-ad23-ba0af56e28b5
+---
+Always use `pnpm worktree:new <branch-name|pr-number>` to create an isolated worktree before starting work on:
+- Reviewing a GitHub PR (e.g., `pnpm worktree:new 3809`) → worktree at `~/dev/readest-pr-3809`
+- Fixing a GitHub issue (e.g., `pnpm worktree:new fix/issue-123`) → worktree at `~/dev/readest-fix-issue-123`
+- Implementing a feature request (e.g., `pnpm worktree:new feat/my-feature`) → worktree at `~/dev/readest-feat-my-feature`
+
+Worktree directory convention: `readest-<name>` in the parent of the repo root (`~/dev/`), with slashes replaced by dashes.
+
+Use `pnpm worktree:rm <branch-name|pr-number>` to clean up when done.
+
+**Why:** Keeps the current bare repo branch untouched. Each task gets its own isolated workspace with submodules, dependencies, env files, and vendor assets already set up.
+
+**How to apply:** Before touching any code for a PR review, bug fix, or feature, run `pnpm worktree:new` first. Work inside the new worktree directory (e.g., `~/dev/readest-pr-3809/apps/readest-app/`). Clean up with `pnpm worktree:rm` after merging or finishing.

apps/readest-app/.claude/memory/koplugin-i18n.md

@@ -0,0 +1,44 @@
+---
+name: readest.koplugin i18n system
+description: Custom gettext loader, .po catalog layout, and extract/apply scripts for the KOReader plugin at apps/readest.koplugin/
+type: reference
+originSessionId: 08cfd0cd-b710-4674-9c90-d2ae4827d071
+---
+The KOReader plugin (`apps/readest.koplugin/`) has its own gettext-based i18n system, parallel to but separate from the readest-app i18next setup.
+
+## Loader
+
+- File: `apps/readest.koplugin/i18n.lua` — isolated module, returns a callable table via `setmetatable({}, {__call = ...})`, so `_("msg")` syntax works as a drop-in replacement for `require("gettext")`. Provides `ngettext`/`pgettext`/`npgettext` too. Falls back to KOReader's native `gettext` for missing strings.
+- All Lua sources do `local _ = require("i18n")` (not `require("gettext")`).
+- **Never rename `i18n.lua` to `gettext.lua`** — it would shadow KOReader's module via `require("gettext")` and break the fallback chain (recursive require / never loaded).
+
+## Catalog layout
+
+- `apps/readest.koplugin/locales/<lang>/translation.po` — mirrors `apps/readest-app/public/locales/<lang>/translation.json` exactly, using **i18next-style codes** (`zh-CN`, not `zh_CN`).
+- The loader converts KOReader's locale (e.g. `zh_CN.utf8` → `zh-CN`) before lookup.
+- Fallback chain: full code → base lang (`pt_BR` → `pt`) → `zh-CN` for any unspecified zh variant.
+- Language list is the single source of truth at `apps/readest-app/i18next-scanner.config.cjs` (`options.lngs`) — currently 31 languages.
+
+## Scripts (in `apps/readest.koplugin/scripts/`)
+
+- **`extract-i18n.js`** — primary tool. Run with `node scripts/extract-i18n.js`. Scans `*.lua` for `_("...")`, `_('...')`, and `_([[...]])` (with proper Lua-escape handling), reads each `.po`, **preserves existing translations**, adds new msgids with empty `msgstr`, drops obsolete msgids. Idempotent.
+- **`apply-translations.js`** — bulk applier. Reads `/tmp/koplugin-translations/<lang>.json` files (key = msgid, value = translation) and fills empty `msgstr ""` lines only — **never overwrites** existing translations.
+
+## Workflow for adding/changing strings
+
+1. Edit Lua source(s). Use `_("Foo")` or `T(_("Foo %1"), arg)` (`T` from `require("ffi/util").template`) — **never** `_("Foo ") .. arg`, because RTL/verb-final languages can't reorder the placeholder.
+2. `node scripts/extract-i18n.js` — adds new empty msgids, drops obsolete.
+3. To translate: drop `<lang>.json` files into `/tmp/koplugin-translations/`, then `node scripts/apply-translations.js`.
+4. Verify with `luac -p apps/readest.koplugin/*.lua` and re-run `extract-i18n.js` (should report no changes — idempotency check).
+
+## Translation conventions
+
+- Brand names "Readest" and "KOReader" stay untranslated.
+- Technical terms ("PDF", "API", "URL", "Supabase", "Hash") generally kept as-is, sometimes transliterated in non-Latin scripts.
+- Dialog title = title case (`Sync Info`); menu item label = sentence case (`Sync info`).
+- Lower-confidence translations (bo, si, ta, bn, sl, fa) deserve native-speaker review.
+
+## Storage conventions for plugin state
+
+- Global plugin state: `G_reader_settings:saveSetting("readest_sync", settings)` — login tokens, auto-sync flag, etc.
+- Per-book state: `ui.doc_settings:readSetting("readest_sync")` table — keys like `meta_hash_v1`, `last_synced_at_config`, `last_synced_at_notes` (seconds since epoch).

apps/readest-app/.claude/memory/layout-ui-fixes.md

@@ -0,0 +1,70 @@
+# Layout & UI Fixes Reference
+
+## Safe Area Insets
+
+### Architecture
+- Native plugins push inset values: iOS (`NativeBridgePlugin.swift`), Android (`NativeBridgePlugin.kt`)
+- `useSafeAreaInsets` hook (`src/hooks/useSafeAreaInsets.ts`) reads and caches values
+- Components use `gridInsets` for positioning relative to safe areas
+- CSS: `env(safe-area-inset-top/bottom/left/right)` for CSS-level insets
+
+### Common Issues
+- **Stale insets after system UI change** (#3469): Call `onUpdateInsets()` after `setSystemUIVisibility()`
+- **iPad sidebar insets wrong** (#3395): Different inset handling needed for sidebar vs main view
+- **Android nav bar overlap** (#3466): Use `calc(env(safe-area-inset-bottom) + 16px)` for Android bottom padding
+- **Zoom controls behind status bar** (#3426): Pass `gridInsets` through component chain, use `Math.max(gridInsets.top, statusBarHeight)`
+
+### Rules (see also `docs/safe-area-insets.md`)
+- Always pass `gridInsets` to overlay/floating components near screen edges
+- On Android, account for system navigation bar with `env(safe-area-inset-bottom)`
+- After toggling system UI visibility, force-refresh insets via `onUpdateInsets()`
+
+## Z-Index Hierarchy
+- Navigation buttons: `z-10` (when visible)
+- Annotation nav bar: `z-10` (reduced from z-30 in #3386)
+- TTS control button: ensure above page nav buttons
+- Floating overlays: check against `gridInsets` positioning
+
+## macOS Traffic Lights
+- Managed by `trafficLightStore.ts` and `HeaderBar.tsx`
+- **Fullscreen check required** (#3129): `await currentWindow.isFullscreen()` before hiding
+- **Timeout for visibility toggle** (#3488): Use 100ms delay to prevent flickering
+- **Sidebar interaction** (#3488): Check `getIsSideBarVisible()` before hiding traffic lights
+- Never hide traffic lights when sidebar is open
+
+## Touch/Input Issues
+- **Slider hit area on iOS** (#3382): Use min-h-12, strip browser appearance with CSS
+- **Context menu on macOS** (#3324): 100ms delay before `onContextMenu()` to let pointer events complete
+- **Swipe sensitivity** (#3310): Use average velocity (distance/time) instead of instantaneous velocity for non-animated paging
+- **Touchpad natural scrolling** (#3127): Respect system natural scrolling setting in `usePagination.ts`
+
+## Dialog/Menu Layout
+- **Dialog header** (#3352): Use `px-2 sm:pe-3 sm:ps-2` padding to align with border radius
+- **Settings alignment** (#3151): Use `Menu` component instead of raw `div` for consistent styling
+- **Dropdown for screen readers** (#3035): Use `DropdownContext` with overlay dismiss, not blur-based closing
+
+## Component-Specific Fixes
+
+### HeaderBar.tsx
+- Traffic light visibility management
+- Sidebar toggle persistent position (#3193)
+- Library button placement
+
+### PageNavigationButtons.tsx
+- z-10 when visible (#3201)
+- Always shown for screen readers (#3036)
+- Toggle via `showPageNavButtons` setting
+
+### ProgressInfo.tsx
+- Use physical `page`/`pages` from renderer, not estimated values (#3213, #3200)
+- CSS classes: `time-left-label`, `pages-left-label`, `progress-info-label` (#3343)
+
+### ReadingRuler.tsx
+- Remove `containerStyle` from overlay so dimmed area covers full screen (#3304)
+
+### NavigationBar.tsx
+- Handle `gridInsets` internally, not via pre-computed `navPadding` (#3466)
+
+### ContentNavBar.tsx (annotation search results)
+- Floating buttons with drop shadow, not full-width bar (#3386)
+- z-10 z-index

apps/readest-app/.claude/memory/platform-compat-fixes.md

@@ -0,0 +1,85 @@
+# Platform Compatibility Fixes Reference
+
+## Android
+
+### WebView API Issues
+- **`navigator.getGamepads()`** returns null on older WebView (#3245): Always null-check before `.some()`
+- **`CompressionStream`** unavailable on some Android WebView versions (#3255): Add fallback zip compression path
+- **Annotation tools unresponsive** (#3225): Don't call `makeSelection()` immediately on pointer-up; let popup flow complete naturally
+- **Safe inset updates** (#3469): Call `onUpdateInsets()` after `setSystemUIVisibility()`
+- **Navigation bar overlap** (#3466): Use `calc(env(safe-area-inset-bottom) + 16px)` for bottom padding
+
+### General Android Rules
+- Test with older WebView versions (97+)
+- Always check API availability before calling Web APIs
+- Touch event handling differs from iOS - avoid premature re-selection
+
+## iOS
+
+### Common Issues
+- **Slider touch dead zones** (#3382): Strip native appearance, use larger hit areas (min-h-12)
+- **Safe area insets stale** (#3395): Native Swift plugin must push updated insets
+- **Section content caching** (#3242, #3206): Don't cache section content in foliate-js when updating subitems; cached content retains stale styles after mode switch
+- **CompressionStream** (#3255): Also broken on iOS 15.x; zip.js has its own native API disable
+- **zip.js native API** (#3170): Disable native `CompressionStream`/`DecompressionStream` on iOS 15.x
+
+### iOS-Specific Code
+- `src-tauri/plugins/tauri-plugin-native-bridge/ios/Sources/NativeBridgePlugin.swift`
+- Slider CSS: `-webkit-appearance: none; appearance: none` in globals.css
+- `useSafeAreaInsets.ts` hook
+
+## macOS
+
+### Traffic Lights (Window Controls)
+- Check `isFullscreen()` before hiding (#3129)
+- Use timeouts (100ms) for visibility transitions (#3488)
+- Don't hide when sidebar is open (#3488)
+
+### Input Issues
+- **Context menu steals event loop** (#3324): 100ms setTimeout before calling menu.popup()
+- **Touchpad natural scrolling** (#3127): Respect system setting in `usePagination.ts`
+- **Two-finger swipe** (#3127): Support trackpad two-finger swipe for pagination
+
+### macOS-Specific Code
+- `src-tauri/src/macos/` - Platform-specific Rust code
+- `src/store/trafficLightStore.ts`
+- `src/hooks/useTrafficLight.ts`
+
+## Linux
+
+### WebKitGTK Issues
+- **View Transitions API unsupported** (#3417): Feature-detect `document.startViewTransition` before calling
+- Use `useAppRouter.ts` to avoid transitions on Linux
+
+## E-ink Devices
+
+### Legibility Issues
+- **Low contrast colors** (#3258): Use `not-eink:` Tailwind variant prefix for colors/opacity
+- **Links invisible** (#3258): Don't apply `text-primary` (blue) on e-ink; use default text color
+- **Opacity too low** (#3258): Don't apply `opacity-60`/`opacity-75` on e-ink devices
+- **Highlight visibility** (#3299): Use foreground color for highlights in dark mode e-ink
+
+### E-ink CSS Pattern
+```
+// Instead of:
+className="text-primary opacity-60"
+// Use:
+className="not-eink:text-primary not-eink:opacity-60"
+```
+
+## Docker/Self-Hosting
+- **Missing submodules** (#3233): Run `git submodule update --init --recursive` before build
+- Simplecc WASM module must be initialized
+
+## OPDS
+- **Non-ASCII credentials** (#3436): Use `TextEncoder` + manual Base64 instead of `btoa()`
+- **Author parsing** (#3120): Handle varied metadata structures in OPDS 2.0 feeds
+- **Responsive layout** (#3418): Ensure catalog and download button layout works on small screens
+
+## Cross-Platform Testing Checklist
+1. Android (old WebView + current)
+2. iOS (15.x + current)
+3. macOS (traffic lights, trackpad)
+4. Linux (WebKitGTK)
+5. E-ink devices (contrast, colors)
+6. Web (CloudFlare Workers deployment)

apps/readest-app/.claude/memory/share-feature.md

@@ -0,0 +1,53 @@
+---
+name: Share-a-Book Feature (in progress)
+description: Active implementation of /s/{token} share links + cherry-picks (CFI auto-include, 1-tap library import, branded OG images). All locked decisions and the plan file path.
+type: project
+originSessionId: e4ddc690-b1a9-4557-855f-d4e67055824f
+---
+Active feature on branch `dev` as of 2026-05-02. Plan file: `/Users/chrox/.claude/plans/ok-we-will-learn-cosmic-acorn.md` (always read for source of truth before continuing).
+
+**Why:** complement just-shipped annotation deep-links (PRs #4018, #4019) with whole-book sharing. Cloud-sync infra exists; this layers public time-limited links on top.
+
+**How to apply:** these decisions are locked across CEO + eng + design reviews. Do NOT re-litigate when implementing.
+
+## Locked decisions (authoritative)
+
+- **Universal 7-day cap** on share expiry, no tier differentiation, no "Never". All users pick `[1, 3, 7]` days. DMCA-risk reduction.
+- **App Router** for all share routes (mirrors `/o` precedent + recent Stripe / AI / IAP / OPDS). Pages API `storage/*` neighbors stay where they are.
+- **Single non-dynamic landing page** at `src/app/s/page.tsx` + rewrite `'/s/:token' → '/s?token=:token'` in `next.config.mjs`. Mirrors `/o`'s pattern exactly. Avoids `[token]` dynamic-segment trap under `output: 'export'`.
+- **R2 server-side byte-copy** for `/import` (recipient-side library import). NOT a reference. Preserves invariant that every `files` row's `file_key` starts with that row's `user_id` — keeps stats / purge / delete / download routes working unchanged.
+- **`token_hash` (sha256) in DB**, never the raw token. Raw token shown to user once at create.
+- **Live `(user_id, book_hash)` resolution** at every access (no FK to `files`). Re-uploads of the same hash follow the share automatically.
+- **GET `/download` is a 302 redirect with NO DB writes**. Count via separate `POST /download/confirm` so unfurlers / prefetchers can't inflate counts.
+- **Atomic SQL `download_count = download_count + 1`**, not read-modify-write.
+- **Per-user 50-share cap**, enforced at create-time.
+- **Auth detection on /s landing**: server-render via Supabase auth cookie in `app/s/layout.tsx`. No layout shift. Falls back to anonymous flow + post-hydration upgrade if SSR fails.
+- **Cover-less `og.png` fallback**: text-only display-type card. NO placeholder rectangle, NO procedural pattern.
+- **Universal Links / App Links**: handle `https://web.readest.com/s/...` in v1 via `useOpenShareLink`. Tauri's `applinks` config already covers the host.
+
+## Cherry-picks accepted (CEO review SELECTIVE EXPANSION)
+
+1. **Position-aware share** — every share initiated from the reader auto-includes `cfi`; recipient lands at sharer's paragraph. Toggle in dialog (default on, only visible when reader-context).
+3. **1-tap "Add to my library"** — logged-in recipient on `/s` gets primary action that calls `/import` (R2 byte-copy) and navigates to `/reader?ids=...&cfi=...`.
+4. **Branded OG image** — `/api/share/[token]/og.png` server-renders via `@vercel/og`. Spec includes anti-slop checklist.
+
+Deferred to TODOS.md: QR code on landing, notify-on-download toggle.
+
+## Open implementation questions (resolve mid-build)
+
+1. Upload-confirmation: HEAD R2 in `/create`, or add `uploaded_at` column to `files`? — recommend HEAD.
+2. Migration directory: project has no `apps/readest-app/supabase/migrations/`. Confirm where SQL actually lands before writing the file.
+3. `@vercel/og` runtime compat with CloudFlare Workers (OpenNextJS). Verify before relying on it; fallback to Satori + sharp if incompatible.
+4. App Router route handlers under `src/app/api/share/...` should be silently dropped by `output: 'export'` in Next 16.2.3. Confirm during first Tauri build.
+
+## Critical files for implementation
+
+See "Critical Files (modify or create)" table in the plan. Key starting points:
+- `src/libs/storage-server.ts` — extract `getDownloadSignedUrl` from `pages/api/storage/download.ts`
+- `src/libs/share-server.ts` (new) — `generateShareToken()`, `hashShareToken(raw)`
+- `src/libs/share.ts` (new) — typed client used by dialog, manage section, deeplink hook, landing page
+- `src/utils/share.ts` (new) — `buildShareUrl(token)`, `parseShareDeepLink(url)`
+- Dialog reference: `src/components/Dialog.tsx`, `BookDetailModal.tsx`
+- Landing reference: `src/app/o/page.tsx` (lift `Card`, `BrandHeader`, `PageFooter` to `src/components/landing/`)
+- Deeplink hook reference: `src/hooks/useOpenAnnotationLink.ts`, `useOpenWithBooks.ts`
+- App-level upload entry: `appService.uploadBook(book)` at `src/services/appService.ts:269` (NOT `cloudService.uploadBook` — lower-level fn)

apps/readest-app/.claude/memory/tts-fixes.md

@@ -0,0 +1,50 @@
+# TTS (Text-to-Speech) Fixes Reference
+
+## Architecture
+
+### Key Components
+- `TTSController` (`src/services/tts/TTSController.ts`) - Core state machine
+- `EdgeTTSClient` (`src/services/tts/EdgeTTSClient.ts`) - Edge TTS provider
+- `useTTSControl` hook (`src/app/reader/hooks/useTTSControl.ts`) - React integration
+- `useTTSMediaSession` hook (`src/app/reader/hooks/useTTSMediaSession.ts`) - Media controls
+
+### Section-Aware TTS Model
+TTS tracks its own section independently from the view via `#ttsSectionIndex`:
+- `#initTTSForSection()` - Creates TTS document for a section without changing the view
+- `#initTTSForNextSection()` / `#initTTSForPrevSection()` - Navigate TTS across sections
+- `#getHighlighter()` - Only returns highlighter if view section matches TTS section
+- `onSectionChange` callback - Notifies UI when TTS crosses section boundary
+- Highlights use CFI strings (not raw Range objects) for cross-section compatibility
+
+### State Management Pitfalls
+1. **`#ttsSectionIndex` must match view section for highlights to work**
+   - If `-1`, all highlight calls are suppressed
+   - `shutdown()` sets it to `-1` but must also null out `this.view.tts`
+
+2. **Guards/Refs that block re-entry:**
+   - The old `ttsOnRef` guard blocked TTS restart from annotations (removed in #3292)
+   - `view.tts` reference surviving shutdown blocked re-initialization (#3400)
+
+3. **Timeouts that fire after pause:**
+   - Edge TTS had a safety timeout that advanced sentences even when paused (#3244)
+   - Solution: removed the entire `ontimeupdate` safety timeout mechanism
+
+## Fix History
+
+| Issue | Problem | Root Cause | Fix |
+|-------|---------|------------|-----|
+| #3100 | TTS scrolls too far | TTS coupled to view section | Added `#ttsSectionIndex`, "Back to TTS Location" button |
+| #3198 | TTS doesn't follow to next section | No `onSectionChange` callback | Added section change notification, extracted hooks |
+| #3244 | Paused TTS advances | Safety timeout fires after pause | Removed `ontimeupdate` timeout mechanism |
+| #3291 | TTS fails without lang attribute | Invalid SSML from missing lang | Set lang/xml:lang on html element from `ttsLang` |
+| #3292 | Can't restart TTS from annotation | `ttsOnRef` blocks re-entry | Removed the guard ref entirely |
+| #3400 | TTS highlight stops after restart | `view.tts` not nulled on shutdown | Added `this.view.tts = null` in `shutdown()` |
+
+## Debugging TTS Issues
+
+1. **TTS doesn't start:** Check `#initTTSForSection()` - does `view.tts.doc === doc` shortcut early?
+2. **No highlights:** Check `#ttsSectionIndex` matches view's section index
+3. **Advances when paused:** Look for setTimeout/timer callbacks that bypass pause state
+4. **Can't restart:** Check for refs/guards that prevent re-entry into speak handlers
+5. **Fails on some chapters:** Check if chapter has lang attribute and XHTML namespace
+6. **SSML errors:** Check `src/utils/ssml.ts` for proper namespace/lang handling

apps/readest-app/.claude/memory/virtuoso_overlayscrollbars.md

@@ -0,0 +1,92 @@
+---
+name: Virtuoso + OverlayScrollbars pattern
+description: How to integrate OverlayScrollbars with react-virtuoso for overlay scrollbars on Android/iOS webviews
+type: reference
+originSessionId: 9da59a46-3dff-4a77-b7a4-8de4d07297b6
+---
+Virtuoso manages its own internal scroller. On Android WebView (and similar) native scrollbars auto-hide, so users see no scrollbar. The fix: wrap Virtuoso with OverlayScrollbars using the `useOverlayScrollbars` hook — **not** the `OverlayScrollbarsComponent`.
+
+## Migration from `customScrollParent`
+
+The previous approach used `customScrollParent` to let an outer `OverlayScrollbarsComponent` own the scroll. This was replaced: Virtuoso now owns its own scroller, and OverlayScrollbars wraps it. This means:
+- Remove `customScrollParent` prop from Virtuoso/VirtuosoGrid
+- Remove the outer `OverlayScrollbarsComponent` wrapper
+- Use `scrollerRef` instead to capture Virtuoso's scroller element
+- If the parent needs the scroller ref (e.g. for pull-to-refresh, scroll save/restore), expose it via a callback prop like `onScrollerRef`
+
+## Boilerplate
+
+```tsx
+import { useOverlayScrollbars } from 'overlayscrollbars-react';
+import 'overlayscrollbars/overlayscrollbars.css';
+
+// Inside the component:
+const osRootRef = useRef<HTMLDivElement>(null);
+const [scroller, setScroller] = useState<HTMLElement | null>(null);
+const [initialize, osInstance] = useOverlayScrollbars({
+  defer: true,
+  options: { scrollbars: { autoHide: 'scroll' } },
+  events: {
+    initialized(instance) {
+      const { viewport } = instance.elements();
+      viewport.style.overflowX = 'var(--os-viewport-overflow-x)';
+      viewport.style.overflowY = 'var(--os-viewport-overflow-y)';
+    },
+  },
+});
+
+useEffect(() => {
+  const root = osRootRef.current;
+  if (scroller && root) {
+    initialize({ target: root, elements: { viewport: scroller } });
+  }
+  return () => osInstance()?.destroy();
+}, [scroller, initialize, osInstance]);
+
+const handleScrollerRef = useCallback((el: HTMLElement | Window | null) => {
+  const div = el instanceof HTMLElement ? el : null;
+  setScroller(div);
+  // If parent needs the scroller (e.g. for pull-to-refresh):
+  onScrollerRef?.(div as HTMLDivElement | null);
+}, [onScrollerRef]);
+```
+
+## JSX structure
+
+```tsx
+<div ref={osRootRef} data-overlayscrollbars-initialize='' className='h-full'>
+  <Virtuoso
+    scrollerRef={handleScrollerRef}
+    style={{ height: containerHeight }}
+    totalCount={items.length}
+    itemContent={renderItem}
+    overscan={200}
+  />
+</div>
+```
+
+For `VirtuosoGrid`, same pattern — pass `scrollerRef={handleScrollerRef}`.
+
+## Footer spacer
+
+When Virtuoso owns its own scroller (no `customScrollParent`), the last items may be hidden behind bottom UI (tab bars, safe area). Add a Virtuoso `Footer` component to the components config:
+
+```tsx
+const VIRTUOSO_COMPONENTS = {
+  List: MyListComponent,
+  Footer: () => <div style={{ height: 34 }} />,
+};
+```
+
+## Key points
+
+- **`useOverlayScrollbars`** hook, not `OverlayScrollbarsComponent` — the component can't share a viewport with Virtuoso
+- Wrapper div needs `ref={osRootRef}` and `data-overlayscrollbars-initialize=""`
+- `initialize({ target: root, elements: { viewport: scroller } })` tells OverlayScrollbars to use Virtuoso's existing scroller as its viewport (no new DOM element)
+- The `initialized` event **must** restore overflow CSS vars (`--os-viewport-overflow-x/y`) so OverlayScrollbars doesn't fight Virtuoso's scroll management
+- No custom Scroller component needed — `scrollerRef` replaces the old `Scroller` component pattern (e.g. `TOCScroller` was removed)
+
+## Used in
+
+- `src/app/library/components/Bookshelf.tsx` — library grid/list with parent scroller exposure for pull-to-refresh and scroll save/restore
+- `src/app/reader/components/sidebar/TOCView.tsx` — sidebar TOC (self-contained, no parent scroller needed)

apps/readest-app/.claude/rules/test-first.md

@@ -0,0 +1,5 @@
+## Test-First Development
+
+- Always write a failing unit test **before** implementing a fix.
+- Run the test to confirm it reproduces the bug or fails as expected, then apply the fix and verify the test passes.
+- Run the full test suite (`pnpm test`) after changes to ensure no regressions.

apps/readest-app/.claude/rules/typescript.md

@@ -0,0 +1,5 @@
+## TypeScript
+
+- Never use the `any` type. Use `unknown`, proper types, or generics instead.
+- Strict mode is enabled. Target is ES2022.
+- Unused vars prefixed with `_` are allowed (ESLint configured).

apps/readest-app/.claude/rules/verification.md

@@ -0,0 +1,9 @@
+## Verification (done-conditions)
+
+Before marking work complete, all applicable checks must pass:
+
+1. `pnpm test` — unit tests (vitest)
+2. `pnpm lint` — Biome + tsgo (also runs `pnpm lint:lua` if luajit is installed)
+3. `pnpm test:lua` — busted unit tests for `apps/readest.koplugin/spec/` (only when koplugin Lua files changed; soft-skips when busted/luajit not installed)
+4. `pnpm fmt:check` — Rust format check (only when `src-tauri/` files changed)
+5. `pnpm clippy:check` — Rust lint (only when `src-tauri/` files changed)

apps/readest-app/.claude/skills/i18n-koplugin/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: i18n-koplugin
+description: >
+  Extract i18n strings from readest.koplugin Lua sources and translate empty
+  msgstrs in apps/readest.koplugin/locales. Use when the user invokes
+  /i18n-koplugin or asks to extract/translate koplugin i18n strings.
+  Runs scripts/extract-i18n.js to sync .po catalogs from `_("...")` calls,
+  then fills any empty `msgstr ""` entries across all locale files.
+user_invocable: true
+---
+
+Extract/translate i18n strings for `readest.koplugin`. The catalogs are gettext `.po` files (not JSON like the main app). Run from the repo root or any worktree — the script resolves paths relative to the plugin dir.
+
+## Step 1: Determine the working directory
+
+If currently in a PR worktree (e.g., `/Users/chrox/dev/readest-pr-*`), use that. Otherwise use the main repo. The plugin dir is `<repo-root>/apps/readest.koplugin`.
+
+## Step 2: Extract msgids from Lua sources
+
+```bash
+cd <repo-root>/apps/readest.koplugin
+node scripts/extract-i18n.js
+```
+
+This scans every `*.lua` file under `apps/readest.koplugin/` (except `spec/` and dotdirs) for `_("...")` and `_([[...]])` calls, then for each language listed in `apps/readest-app/i18next-scanner.config.cjs`:
+
+- appends new msgids with empty `msgstr ""`
+- preserves existing translations
+- drops obsolete msgids
+- rewrites the `.po` header (Plural-Forms etc.)
+
+The output prints `<lang>  <kept>/<total>  (-<dropped> obsolete)` per locale.
+
+## Step 3: Find untranslated entries
+
+An untranslated entry is a non-empty `msgid` followed by an empty `msgstr ""` (the file's header pair `msgid ""` / `msgstr ""` is NOT a translation — skip it).
+
+```bash
+cd <repo-root>/apps/readest.koplugin/locales
+# List locales that still have untranslated strings, with counts
+for f in */translation.po; do
+  # Count empty msgstrs that follow a non-empty msgid
+  n=$(awk '
+    /^msgid "/  { msgid=$0; next }
+    /^msgstr ""$/ { if (msgid != "msgid \"\"") c++; next }
+  ' "$f")
+  [ "$n" -gt 0 ] && echo "$f: $n untranslated"
+done
+```
+
+If no results, report that all strings are translated and stop.
+
+To list the actual untranslated msgids in one locale:
+
+```bash
+awk '
+  /^msgid "/  { msgid=$0; next }
+  /^msgstr ""$/ { if (msgid != "msgid \"\"") print msgid; next }
+' <repo-root>/apps/readest.koplugin/locales/<lang>/translation.po
+```
+
+## Step 4: Translate empty msgstrs
+
+For each empty `msgstr ""` found:
+
+1. Read the preceding `msgid "..."` — that's the English source string.
+2. Identify the target locale from the file path (e.g., `locales/ja/translation.po` → Japanese; see table below).
+3. Provide an accurate translation. Use the locale reference table for the language; match the tone/terminology already used in the same file (check existing translated entries for context).
+4. Preserve `printf`-style placeholders verbatim: `%s`, `%d`, `%1$s`, `%(name)s`, etc.
+5. Preserve newlines as `\n`, tabs as `\t`, and escape `"` as `\"` and backslashes as `\\` inside the msgstr.
+
+Edit the `.po` files directly with the Edit tool — do NOT use sed for this, because msgids may contain characters that confuse shell quoting. Each replacement should target the unique `msgid "<English>"\nmsgstr ""` block:
+
+Old:
+```
+msgid "<English string>"
+msgstr ""
+```
+
+New:
+```
+msgid "<English string>"
+msgstr "<translation>"
+```
+
+Batch all locales for the same key together when possible — keeps the translation set consistent.
+
+### Locale reference
+
+The supported language set is **not hardcoded in this skill**. The ground truth is `apps/readest-app/i18n-langs.json` — both `i18next-scanner.config.cjs` (via `require`) and `src/i18n/i18n.ts` (via JSON import) source from it, and `extract-i18n.js` reads `lngs` from the scanner config at runtime. To list the current set:
+
+```bash
+cat <repo-root>/apps/readest-app/i18n-langs.json
+```
+
+Map each code to a language name when translating. If a code in `i18n-langs.json` is missing from the `LANG_META` table inside `extract-i18n.js`, the script prints `<code> skipped (no metadata in extract-i18n.js)` — in that case, add the metadata entry there first, then re-run extraction.
+
+## Step 5: Verify
+
+Re-run the count loop from Step 3 and confirm zero untranslated strings remain. Report:
+
+- number of msgids extracted
+- per-locale count of strings translated
+- any locales that were already complete
+
+Optionally, run the koplugin Lua tests if `busted`/`luajit` are installed:
+
+```bash
+cd <repo-root>/apps/readest-app
+pnpm test:lua
+```

apps/readest-app/.claude/skills/i18n/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: i18n
+description: >
+  Extract i18n strings, translate missing translations, or add a new language to readest-app.
+  Use when the user invokes /i18n or asks to extract/translate i18n strings or add a new locale.
+  Runs i18next-scanner to extract keys, then translates any __STRING_NOT_TRANSLATED__
+  placeholders across all locale files.
+user_invocable: true
+---
+
+Extract/translate i18n strings or add a new language for readest-app. Run from the app directory (either the main repo or a worktree).
+
+## Step 0: Determine the mode
+
+- If the user asks to **add a new language/locale**, go to **Adding a New Language** below.
+- Otherwise, go to **Extracting & Translating Strings** below.
+
+## Step 1: Determine the working directory
+
+If currently in a PR worktree (e.g., `/Users/chrox/dev/readest-pr-*`), use that. Otherwise use the main repo. The app directory is `<repo-root>/apps/readest-app`.
+
+---
+
+## Adding a New Language
+
+When the user asks to add a new language (e.g., "add Hungarian", "add hu locale"):
+
+### Step A1: Register the locale in two places
+
+1. **`i18n-langs.json`** — Append the locale code to the array. Both `i18next-scanner.config.cjs` and `src/i18n/i18n.ts` import from this file, so they pick up the new entry automatically.
+2. **`src/services/constants.ts`** — Add an entry to `TRANSLATED_LANGS` with the locale code and native language name (e.g., `hu: 'Magyar'`). If the locale already exists in `TRANSLATOR_LANGS`, remove the duplicate there since it will be inherited via the spread.
+
+### Step A2: Generate the translation file
+
+```bash
+cd <app-dir>
+pnpm run i18n:extract
+```
+
+This creates `public/locales/<code>/translation.json` with all keys set to `__STRING_NOT_TRANSLATED__`.
+
+### Step A3: Translate all strings
+
+Follow **Step 4** below to translate every `__STRING_NOT_TRANSLATED__` entry in the new locale file.
+
+### Step A4: Verify
+
+Follow **Step 5** below to confirm zero remaining untranslated strings for the new locale.
+
+---
+
+## Extracting & Translating Strings
+
+### Step 2: Extract i18n strings
+
+```bash
+cd <app-dir>
+pnpm run i18n:extract
+```
+
+This runs `i18next-scanner` which scans source files for translation keys and adds any new keys to all locale files with `__STRING_NOT_TRANSLATED__` as the placeholder value.
+
+### Step 3: Find untranslated strings
+
+```bash
+grep -r "__STRING_NOT_TRANSLATED__" <app-dir>/public/locales/
+```
+
+If no results, report that all strings are already translated and stop.
+
+### Step 4: Translate missing strings
+
+For each `__STRING_NOT_TRANSLATED__` found:
+
+1. Identify the English key (e.g., `"Hide Scrollbar"`)
+2. Identify the target locale from the file path (e.g., `locales/ja/translation.json` -> Japanese)
+3. Provide an accurate translation for each locale
+
+Use `sed -i ''` on macOS to replace in-place. Handle all locales in one batch:
+
+```bash
+cd <app-dir>/public/locales
+sed -i '' 's/"<Key>": "__STRING_NOT_TRANSLATED__"/"<Key>": "<translation>"/' <locale>/translation.json
+```
+
+### Locale reference
+
+The canonical, complete list of supported locales lives in `i18n-langs.json` (codes only) and `TRANSLATED_LANGS` in `src/services/constants.ts` (codes → native display names). Read those for the source of truth — translate every locale that appears in `i18n-langs.json`. Don't carry forward older "out-of-scope" exclusions like `pt-BR` or `uz`; if it's in `i18n-langs.json` it ships, and it needs translation.
+
+### Step 5: Verify
+
+```bash
+grep -r "__STRING_NOT_TRANSLATED__" <app-dir>/public/locales/
+```
+
+Confirm zero remaining untranslated strings. Report the number of keys translated and locales updated.

apps/readest-app/.env

@@ -3,7 +3,7 @@ PDFJS_FONTS_PATH=../../packages/foliate-js/node_modules/pdfjs-dist
 PDFJS_STYLE_PATH=../../packages/foliate-js/vendor/pdfjs
 
 NEXT_PUBLIC_DEFAULT_POSTHOG_URL_BASE64="aHR0cHM6Ly91cy5pLnBvc3Rob2cuY29t"
-NEXT_PUBLIC_DEFAULT_POSTHOG_KEY_BASE64="cGhjX2ViNXowbVRxWm8yZm5YYnZGNmE3bFh5TThpTmRSNTNsR1A3VFM3VGh4S08="
+NEXT_PUBLIC_DEFAULT_POSTHOG_KEY_BASE64="cGhjX0x3ekhZRWtsZUVub3ZSc05ZQlRpTVRTV2MyS1NUOFdZMzBIWWFhN0ZPa1IK"
 
 NEXT_PUBLIC_DEFAULT_SUPABASE_URL_BASE64="aHR0cHM6Ly9yZWFkZXN0LnN1cGFiYXNlLmNv"
 NEXT_PUBLIC_DEFAULT_SUPABASE_KEY_BASE64="ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKemRYQmhZbUZ6WlNJc0luSmxaaUk2SW5aaWMzbDRablZ6YW1weFpIaHJhbkZzZVhOaklpd2ljbTlzWlNJNkltRnViMjRpTENKcFlYUWlPakUzTXpReE1qTTJOekVzSW1WNGNDSTZNakEwT1RZNU9UWTNNWDAuM1U1VXFhb3VfMVNnclZlMWVvOXJBcGMwdUtqcWhwUWRVWGh2d1VIbVVmZw=="

apps/readest-app/.env.local.example

@@ -28,3 +28,5 @@ S3_ACCESS_KEY_ID=PLACE_HOLDER
 S3_SECRET_ACCESS_KEY=PLACE_HOLDER
 S3_BUCKET_NAME=PLACE_HOLDER
 S3_REGION=PLACE_HOLDER
+
+TEMP_STORAGE_PUBLIC_BUCKET_NAME=PLACE_HOLDER

apps/readest-app/.env.tauri

@@ -1 +1,3 @@
-NEXT_PUBLIC_APP_PLATFORM=tauri
+NEXT_PUBLIC_APP_PLATFORM=tauri
+
+DBUS_ID=com.bilingify.readest

apps/readest-app/.env.tauri.example

@@ -0,0 +1,2 @@
+NEXT_PUBLIC_APP_PLATFORM=tauri
+AI_GATEWAY_API_KEY=your_key_here

apps/readest-app/.env.web.example

@@ -0,0 +1,3 @@
+NEXT_PUBLIC_APP_PLATFORM=web
+AI_GATEWAY_API_KEY=your_key_here
+NEXT_PUBLIC_AI_GATEWAY_API_KEY=your_key_here

apps/readest-app/.gitignore

@@ -8,6 +8,8 @@
 
 # testing
 /coverage
+.test-sandbox-node/
+.vitest-attachments/
 
 # next.js
 /.next/
@@ -48,6 +50,9 @@ tauri.*.conf.json
 *.tsbuildinfo
 next-env.d.ts
 
+# eslint
+.eslintcache
+
 #generated
 src-tauri/gen
 
@@ -60,3 +65,9 @@ src-tauri/gen
 /public/fallback-*.js
 /public/swe-worker-*.js
 
+/dist/
+
+.context/
+.claude/settings.local.json
+.claude/skills
+

apps/readest-app/AGENTS.md

@@ -0,0 +1,111 @@
+## Project Overview
+
+Readest is a cross-platform ebook reader built as a **Next.js 16 + Tauri v2** hybrid app. It's part of a pnpm monorepo at `/apps/readest-app/`. The app runs on web (CloudFlare Workers), desktop (macOS/Windows/Linux via Tauri), and mobile (iOS/Android via Tauri).
+
+## Common Commands
+
+```bash
+# Development
+pnpm dev-web               # Web-only dev server (no Rust compilation needed)
+pnpm tauri dev             # Desktop dev with Tauri (compiles Rust backend)
+
+# Building
+pnpm build                 # Build Next.js for Tauri
+pnpm build-web             # Build Next.js for web deployment
+
+# Testing (see [docs/testing.md](docs/testing.md) for full details)
+pnpm test                  # Unit tests (vitest + jsdom)
+pnpm test -- src/__tests__/utils/misc.test.ts  # Run a single test file
+pnpm test -- --watch       # Watch mode
+pnpm test:browser          # Browser tests (Chromium via Playwright)
+pnpm tauri:dev:test        # Start Tauri app with webdriver
+pnpm test:tauri            # Run Tauri integration tests
+
+# Linting & Formatting
+pnpm lint                  # Biome (linter) + tsgo (type check)
+pnpm format                # Prettier (runs from monorepo root)
+pnpm format:check          # Check formatting without writing
+
+# Rust
+pnpm fmt:check             # Check formatting Rust code (src-tauri)
+pnpm clippy:check          # Lint Rust code (src-tauri)
+```
+
+### Source Layout
+
+| Directory         | Purpose                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `src/app/`        | Next.js App Router pages and API routes                       |
+| `src/components/` | React components (reader, settings, library, assistant, etc.) |
+| `src/services/`   | Business logic: TTS, translators, OPDS, sync, AI, metadata    |
+| `src/store/`      | Zustand state stores                                          |
+| `src/hooks/`      | Custom React hooks                                            |
+| `src/libs/`       | Document loaders, payment, storage, sync                      |
+| `src/utils/`      | Pure utility functions                                        |
+| `src/types/`      | TypeScript type definitions                                   |
+| `src/context/`    | React Context providers (Auth, Env, Sync, etc.)               |
+| `src/workers/`    | Web Workers for background tasks                              |
+| `src-tauri/`      | Rust backend: Tauri plugins, platform-specific code           |
+
+### Path Aliases (tsconfig)
+
+- `@/*` → `./src/*`
+- `@/components/ui/*` → `./src/components/primitives/*`
+
+### Rust Backend (`src-tauri/`)
+
+Platform-specific code lives in `src-tauri/src/{macos,windows,android,ios}/`. Custom Tauri plugins are in `src-tauri/plugins/`.
+
+## Git Worktrees
+
+Always use `pnpm worktree:new <branch-name|pr-number>` to create worktrees. Never use `git worktree add` directly — the script handles submodule initialization (simplecc WASM, foliate-js), dependency installation, `.env` copying, vendor assets, and Tauri gen symlinks that are required for lint and tests to pass.
+
+```bash
+pnpm worktree:new feat/my-feature   # New branch from origin/main
+pnpm worktree:new 3837              # Checkout PR #3837 with push access to fork
+```
+
+## Project Rules
+
+Rules are in `.claude/rules/`: test-first, typescript, verification.
+
+### i18n
+
+See [docs/i18n.md](docs/i18n.md) for the key-as-content translation approach, `stubTranslation` usage in non-React modules, and extraction workflow.
+
+### Safe Area Insets
+
+See [docs/safe-area-insets.md](docs/safe-area-insets.md) for rules on handling top/bottom insets for UI elements near screen edges.
+
+### Design System
+
+UI/UX rules — surface tiers, action vocabulary, settings primitives (`BoxedList`, `SettingsRow`, `SettingsSwitchRow`, `SettingsSelect`, `NavigationRow`, `Tips`, etc.), boxed-list anatomy, RTL conventions, e-ink overlay, and anti-patterns — live in [DESIGN.md](DESIGN.md). Codify recurring decisions there so they persist for the team and future contributors. Reach for the primitives in `src/components/settings/primitives/` instead of inlining chassis classes.
+
+### E-ink mode
+
+Every new UI widget must look right under `[data-eink='true']`. E-ink screens have no shadows, no gradients, slow refresh, and need crisp 1px borders for delineation. The conventions live in `src/styles/globals.css` — reuse the existing classes instead of inventing new ones:
+
+- **Surfaces / inputs** — add `eink-bordered`. In eink mode it swaps to `bg-base-100` + 1px `base-content` border. Use it on inputs, custom button backgrounds, ghost-styled cancel buttons, and any container that needs a visible boundary.
+- **Primary action buttons** — add `btn-primary` (alongside whatever Tailwind classes you use for color themes). The `[data-eink] .btn-primary` rule inverts to `base-content` bg + `base-100` text so the primary CTA stays distinct from secondary actions.
+- **`.modal-box`** picks up no-shadow + 1px border automatically; dialogs that use it don't need additions.
+- **Don't rely on color/shadow alone for hierarchy.** Two same-tone buttons differ only by hover on color themes, and hover doesn't exist on e-ink touchscreens. Pair a borderless ghost (cancel) with a solid CTA (submit) so eink can invert one without flattening the difference.
+
+When in doubt, toggle E-ink in Settings → Misc and check. The rules in `globals.css` cover most cases automatically, but composite components (custom buttons, layered cards) often need `eink-bordered` on the right element to stay legible.
+
+Available gstack skills:
+
+- `/plan-ceo-review` — CEO/founder-mode plan review
+- `/plan-eng-review` — Eng manager-mode plan review
+- `/plan-design-review` — Designer's eye review of a live site
+- `/design-consultation` — Design system consultation
+- `/review` — Pre-landing PR review
+- `/ship` — Ship workflow (merge, test, review, bump, PR)
+- `/browse` — Fast headless browser for QA and site interaction
+- `/qa` — QA test and fix bugs
+- `/qa-only` — QA report only (no fixes)
+- `/qa-design-review` — Designer's eye QA with fixes
+- `/setup-browser-cookies` — Import cookies for authenticated testing
+- `/retro` — Weekly engineering retrospective
+- `/document-release` — Post-ship documentation update
+
+If gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.

apps/readest-app/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

apps/readest-app/DESIGN.md

@@ -0,0 +1,972 @@
+## Readest Design Language
+
+Readest's UI is **Adwaita-aligned**, **e-ink-first**, **cross-platform-aware**. This doc is the
+reference for that language: principles, vocabulary, anti-patterns. New work should read it
+before reaching for daisyui defaults; existing work is gradually migrating toward it.
+
+### Status
+
+This doc is the **first articulation** of the system, not a retrospective. Many existing
+components don't fully match it yet (especially older buttons and ad-hoc panels). The goal
+is that **new code uses these conventions** and **migrations land opportunistically** as
+features get touched.
+
+---
+
+### 1. Identity & lineage
+
+Readest's visual language descends from **Adwaita / libadwaita** — GNOME's design system —
+adapted for a cross-platform Tauri + Next.js app that also runs on iOS, Android, web, and
+e-ink readers.
+
+What we take from Adwaita:
+
+- **Content first, chrome recedes.** The reading surface is the product. Settings, toolbars,
+  popups never compete with the page.
+- **Boldly minimal.** Restraint over density. Whitespace is structural.
+- **Surface hierarchy** — window → view → card — three explicit elevation tiers, no shadow
+  gymnastics.
+- **Color discipline.** Brand color is rare and earned. Neutral palette carries the weight.
+- **Boxed lists are the chassis.** AdwActionRow's prefix · title · suffix anatomy is the
+  canonical settings/list row everywhere.
+- **Pills, ghosts, flats.** Three-tier button palette: pill/circular ghost in headers, flat
+  secondary over view-bg, accent CTA only when truly primary.
+- **Banner vs Toast.** AdwBanner = inline, top-of-window, persistent. AdwToast = transient,
+  bottom slide-in.
+- **Switches over checkboxes** for boolean settings.
+- **Subtle motion.** Short, ease-out, never bouncy.
+
+What's Readest-specific:
+
+- **E-ink as a first-class mode.** Every surface flips to flat 1px contrast borders under
+  `[data-eink='true']`. Adwaita is desktop-GNOME-only; we ship to e-ink readers and the
+  visual language has to survive there.
+- **Cross-platform reality.** Readest runs on macOS, Windows, Linux, iOS, Android, web. The
+  identity stays Adwaita; platform grace notes (radii, target sizes) follow host
+  conventions where they matter.
+
+---
+
+### 2. Principles
+
+The seven rules. When in doubt, work backward from these.
+
+#### 2.1 Surfaces continue surfaces
+
+A control that extends a list/card should match its parent's border + fill. The
+"+ Import Dictionary" button at `src/components/settings/CustomDictionaries.tsx` reads as
+detached card siblings of the dictionary list above it because they share
+`border-base-200 bg-base-100 rounded-lg`.
+
+> **Bad**: a list of dictionaries in a `bg-base-100` card, followed by a `btn-outline btn-primary`
+> add button. The button shouts; the list whispers; the eye bounces.
+>
+> **Good**: list and add-button share the same surface vocabulary. The eye flows.
+
+#### 2.2 Color is earned
+
+Brand `primary` is reserved for **the** primary action of a surface. Most actions don't have
+a primary action — they have a list of equally-weighted choices, or a single accent.
+
+- Settings dialog has no primary. Every panel is a list of toggles. **Zero brand color.**
+- "Import a Book" in onboarding is a primary CTA. **One brand color.**
+- "Add Web Search" extends a list — it's not the surface's primary action. **Neutral.**
+
+#### 2.3 Two-step depth
+
+State changes cycle through **`base-100 → base-200 → base-300`** instead of recoloring.
+Hover lifts, active deepens, disabled fades opacity. This is theme-safe (works across all
+11 color themes), e-ink-friendly (depth is preserved as borders, not shades), and
+calmer than recoloring.
+
+#### 2.4 Localize the hover signal
+
+When a button hovers, **one focal element changes**, not the whole button. The icon chip
+inverts; the label stays steady. The badge intensifies; the row stays neutral. This reads
+as deliberate, not decorative.
+
+#### 2.5 Motion is color, not transform
+
+Default to `transition-colors duration-150`. No `scale`, no `translate`, no `rotate` unless
+the motion **is** the message (a chevron rotating to indicate expansion is fine; a button
+that scales on hover is not). Transforms break under `[data-eink='true']` and feel
+gimmicky under Adwaita's calm rhythm.
+
+#### 2.6 Eink-first by default
+
+Every custom-styled bordered surface gets the `eink-bordered` class. Every primary action
+gets `btn-primary` (which has dedicated eink rules). Don't rely on color or shadow alone
+for hierarchy — eink screens have neither.
+
+If you can't toggle Settings → Misc → Eink and still tell which button is the CTA, the
+hierarchy is broken.
+
+#### 2.7 Focus is visible but quiet
+
+Keyboard focus needs a visible ring. `focus-visible:ring-2 focus-visible:ring-base-content/15`
+is the canonical treatment for custom buttons. Loud `ring-primary` reserved for inputs
+where the focus state IS the affordance.
+
+#### 2.8 RTL: always use logical properties (REQUIRED)
+
+Readest ships with RTL languages enabled. **Never use direction-bound Tailwind
+utilities** when a logical equivalent exists — the visual edges flip in RTL,
+the logical ones don't.
+
+| Don't use                          | Use instead                        |
+| ---------------------------------- | ---------------------------------- |
+| `pl-*` / `pr-*`                    | `ps-*` (start) / `pe-*` (end)      |
+| `ml-*` / `mr-*`                    | `ms-*` / `me-*`                    |
+| `text-left` / `text-right`         | `text-start` / `text-end`          |
+| `border-l` / `border-r`            | `border-s` / `border-e`            |
+| `rounded-l-*` / `rounded-r-*`      | `rounded-s-*` / `rounded-e-*`      |
+| `left-*` / `right-*` (positioning) | `start-*` / `end-*`                |
+| `justify-start` / `justify-end`    | (these ARE direction-aware) — keep |
+
+The `flex-row` direction is automatically reversed in RTL by the browser, so
+you usually don't need to do anything for `flex` / `gap`. Only **explicit
+edges** (padding, margin, borders, radius, absolute positioning) need
+logical properties.
+
+**Quick scan when reviewing a diff:** grep for `\b(pl|pr|ml|mr|left-|right-|text-left|text-right|border-l|border-r|rounded-l|rounded-r)-` in changed files. Any hit that isn't a deliberate LTR-only
+case (rare — usually only icon glyphs that have a fixed orientation) should
+be flipped to the logical equivalent.
+
+#### 2.9 Every panel and sub-page starts with title + description (REQUIRED)
+
+Every settings panel and every sub-page must open with:
+
+1. **A title** — the panel name. Style: `text-lg font-semibold tracking-tight`. In a
+   top-level panel this is an `<h2>`; in a sub-page this is the `parentLabel /
+currentLabel` breadcrumb in `SubPageHeader` (which uses the same typography so the
+   word stays anchored visually as the user navigates in/out).
+2. **A one-line description** — a short sentence under the title explaining what this
+   surface does or how it fits in the user's workflow. Style: `text-sm
+text-base-content/70 leading-relaxed`. Skip it only when the surface is so trivial
+   the breadcrumb already says everything (rare — when in doubt, write one).
+
+Why: orientation, visual rhythm, and Adwaita parity (`AdwPreferencesPage` always has
+both). The same vertical opening across every surface makes the system feel cohesive
+and gives users a predictable place to learn what a screen does.
+
+**Canonical components.** The `<SubPageHeader>` primitive in
+`src/components/settings/SubPageHeader.tsx` accepts a `description?: React.ReactNode`
+prop that renders the description in the canonical style — sub-pages should pass it
+there rather than rolling their own `<p>` below the header. Top-level panels currently
+inline the title + description; if a third or fourth panel needs the same pattern,
+extract a `<PanelHeader>` primitive following the same shape.
+
+**Examples.**
+
+```tsx
+// Sub-page (Integrations → OPDS Catalogs)
+<SubPageHeader
+  parentLabel={_('Integrations')}
+  currentLabel={_('OPDS Catalogs')}
+  description={_('Browse and download books from online catalogs')}
+  onBack={() => setSubPage(null)}
+/>
+
+// Top-level panel (Integrations panel root)
+<div className='w-full'>
+  <h2 className='mb-1.5 text-lg font-semibold tracking-tight'>{_('Integrations')}</h2>
+  <p className='text-base-content/70 text-sm leading-relaxed'>
+    {_('Connect Readest to external services for sync, highlights, and catalogs.')}
+  </p>
+</div>
+```
+
+---
+
+### 3. Surface hierarchy
+
+Three named tiers, mapped onto daisyui tokens. Use these terms in conversation and code
+comments even though the classes are still daisyui-native.
+
+| Tier       | Token                                | Role                                                                          | Example                                         |
+| ---------- | ------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------- |
+| **Window** | `bg-base-200`                        | The outermost backdrop. Modal scrims, dialog content area, scroll containers. | `<Dialog>` body                                 |
+| **View**   | `bg-base-100/60` or `bg-base-200/40` | Mid-tier surface inside a window. Tip boxes, secondary panels.                | The "提示 / Tips" callout in CustomDictionaries |
+| **Card**   | `bg-base-100`                        | Top-tier content surface. Boxed lists, popovers, modal-box.                   | The dictionaries list card                      |
+
+Border treatment:
+
+- **Window** has no border (it IS the boundary).
+- **View** uses no border or `border-base-200/60` for very soft delineation.
+- **Card** uses `border border-base-200`. In e-ink, `eink-bordered` flips it to 1px
+  `border-base-content`.
+
+Corner radius:
+
+- **Card / View**: `rounded-lg` (8px) — Readest's house radius. Adwaita uses 9px; 8px is
+  close enough and matches Tailwind's scale.
+- **Modal / Sheet**: `modal-box` default (~1rem / 16px) — bigger surfaces get bigger radii.
+- **Pills / Chips**: `rounded-full`.
+- **Inputs / small buttons**: `rounded-md` (6px) or `rounded-lg` (8px).
+
+#### Surface continuity rule
+
+When a control extends a card (an "add row" affordance, a footer button bar attached to a
+list), it inherits the card's surface treatment: same `bg-base-100`, same
+`border-base-200`, same `rounded-lg`. It is the card grown by one row.
+
+---
+
+### 4. Action vocabulary
+
+Six archetypes. Pick by **role**, not by **appearance**.
+
+#### 4.1 Accent CTA
+
+The primary, accent-colored button. **One per surface, max.** Submit on a form, "Open
+Book", "Sign In".
+
+```tsx
+className = 'btn btn-primary';
+```
+
+Eink: `btn-primary` has dedicated rules (inverts to base-content bg + base-100 text) so it
+stays distinct from secondary actions on monochrome screens.
+
+#### 4.2 Suggested
+
+A non-accent-but-emphasized action. Used when there are multiple equally-weighted actions
+and one is the recommended path. Adwaita's "suggested-action" CSS class.
+
+```tsx
+className = 'btn btn-neutral';
+```
+
+Rare. Most surfaces don't need this tier.
+
+#### 4.3 Flat
+
+The default secondary button. Sits on a view or card surface, no border, hover lifts to
+`base-200`. The bulk of buttons should be flat.
+
+```tsx
+className="btn btn-ghost"
+// or for a custom surface treatment:
+className={clsx(
+  'rounded-lg px-4 py-2 text-sm font-medium',
+  'hover:bg-base-200 transition-colors duration-150',
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-base-content/15',
+)}
+```
+
+#### 4.4 Pill / Circular ghost
+
+Compact icon-only buttons in header bars and toolbars. Always `rounded-full`,
+`btn-circle` or hand-rolled circular ghost.
+
+```tsx
+className = 'btn btn-ghost btn-circle h-8 min-h-8 w-8 p-0';
+```
+
+The window controls in `SettingsDialog.tsx` (search, menu, close) use this archetype.
+
+#### 4.5 Destructive
+
+Delete, remove, irreversible. Adwaita uses `destructive-action`. Readest uses red
+sparingly — usually only the icon, not the whole button.
+
+```tsx
+// Icon-only delete X in delete mode:
+className = 'btn btn-ghost btn-sm shrink-0 px-1';
+// with <IoMdCloseCircleOutline className="text-error h-4 w-4" />
+```
+
+For destructive **dialogs** (confirmation modals), the confirm button can be `btn-error`,
+but only in the modal — never on the main surface.
+
+#### 4.6 ListExtension
+
+A Readest-named archetype for "add another row to the list above" affordances. The two
+buttons at the bottom of `CustomDictionaries.tsx` are the canonical example.
+
+Anatomy:
+
+- Surface matches the parent card (`border border-base-200 bg-base-100 rounded-lg`)
+- Height ~h-11
+- Centered: small icon chip + label
+- Icon chip: `bg-base-200 text-base-content/60 rounded-full h-5 w-5`
+- Hover: border deepens to `base-300`, bg lightens to `bg-base-200/60`, icon chip inverts
+  to `bg-base-content text-base-100`
+- `eink-bordered` on the button itself
+
+```tsx
+<button
+  type='button'
+  onClick={handleAdd}
+  className={clsx(
+    'eink-bordered group flex h-11 items-center justify-center gap-2.5',
+    'border-base-200 bg-base-100 rounded-lg border px-4',
+    'text-base-content text-sm font-medium',
+    'transition-colors duration-150',
+    'hover:border-base-300 hover:bg-base-200/60',
+    'active:bg-base-200/80',
+    'focus-visible:ring-base-content/15 focus-visible:outline-none focus-visible:ring-2',
+  )}
+>
+  <span
+    className={clsx(
+      'flex h-5 w-5 items-center justify-center rounded-full',
+      'bg-base-200 text-base-content/60',
+      'transition-colors duration-150',
+      'group-hover:bg-base-content group-hover:text-base-100',
+    )}
+  >
+    <MdAdd className='h-3.5 w-3.5' />
+  </span>
+  <span className='line-clamp-1'>{label}</span>
+</button>
+```
+
+Use this for: "Import Dictionary", "Add Web Search", "Add Custom Theme", any "+ add new
+to this list" pattern. **Do not** use `btn-outline btn-primary` for these.
+
+---
+
+### 5. Boxed list anatomy
+
+The settings UI is built on boxed lists. One pattern, used everywhere.
+
+#### Container
+
+Use the `<BoxedList>` primitive at `src/components/settings/primitives/BoxedList.tsx`
+rather than inlining the chassis classes:
+
+```tsx
+<BoxedList title={_('Reading Sync')} data-setting-id='settings.section.id'>
+  {/* rows */}
+</BoxedList>
+```
+
+The primitive renders:
+
+```tsx
+<div className='card eink-bordered border-base-200 bg-base-100 border'>
+  <div className='divide-base-200 divide-y'>{children}</div>
+</div>
+```
+
+- `card` for the radius
+- `border border-base-200` for the boundary (eink upgrades this automatically)
+- `eink-bordered` for the e-ink-mode contrast border
+- `divide-base-200 divide-y` for inter-row separators
+
+> **No `overflow-hidden` on the card.** Children may host popovers (color
+> pickers, dropdowns, tooltips) that need to escape the card bounds. The
+> `divide-y` rules sit between rows and don't touch the card's rounded
+> corners, so omitting overflow-clip is visually safe AND keeps embedded
+> popovers from getting clipped.
+
+#### Row anatomy
+
+Three slots, in order, always:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ [prefix]   Title text                          [suffix slots]   │
+│ [        ] Subtitle text (optional)            [       ][      ]│
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Slot         | Contents                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------- |
+| **Prefix**   | Drag handle, leading icon, avatar, status dot, or empty.                                          |
+| **Title**    | Primary label. `font-medium`. Truncates with `truncate`.                                          |
+| **Subtitle** | Optional secondary line. `text-sm text-base-content/70`. Used for warnings, descriptions, status. |
+| **Suffix**   | Badge, switch, button, chevron, value, or any combination. End-aligned.                           |
+
+Canonical example: `SortableRow` in `src/components/settings/CustomDictionaries.tsx`. The
+drag handle is the prefix, the dict name is the title, the warning reason is the
+subtitle, and the badge + toggle + edit/delete buttons stack as suffixes.
+
+#### Row variants
+
+- **ActionRow** — title + suffix is a single button or chevron. Tap anywhere navigates.
+- **SwitchRow** — title + suffix is a toggle. Tap anywhere toggles.
+- **ComboRow** — title + suffix is a dropdown/select.
+- **ExpanderRow** — chevron suffix; tap expands to reveal nested rows.
+
+These names come from libadwaita and apply 1:1 to Readest's lists. Use the names in code
+comments and PR descriptions.
+
+#### Spacing
+
+- Row vertical padding: `py-2` (8px) for compact lists, `py-3` (12px) for breathing room.
+- Row horizontal padding: `px-3` (12px) or `px-4` (16px). Stay consistent within a list.
+- Slot gap: `gap-2` (8px) between prefix/title/suffix elements.
+
+#### Disabled rows
+
+Disabled rows fade the title to `text-base-content/60` and disable the suffix control. The
+row itself stays at full opacity — only the **content** dims, not the row.
+
+#### Toggle size
+
+| Daisyui class                   | Use case                                                                                                              |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `toggle` (default, h-5 / ~20px) | **Settings panel boxed-list rows** — `<SettingsSwitchRow>` uses this. Visible weight matches the 56px `min-h-14` row. |
+| `toggle-sm` (h-4 / ~16px)       | Inline secondary switches in tighter contexts — e.g. dictionary list rows in `CustomDictionaries`.                    |
+| `toggle-xs` (h-3 / ~12px)       | Compact metadata toggles inside cards — e.g. OPDS catalog "Auto-download".                                            |
+
+The `<SettingsSwitchRow>` primitive bakes in the default `toggle`. **Don't override
+to `toggle-sm` inside boxed-list rows** — it looks orphaned in the row's vertical
+breathing room. Use the smaller sizes only when the row itself is shorter than 56px.
+
+#### Typography inherits from `.settings-content`
+
+The Settings dialog (and any settings-style sheet/popup) wraps its content
+in `.settings-content`, which is defined in `src/styles/globals.css` as:
+
+```css
+.dropdown-content,
+.settings-content {
+  font-size: 14px; /* desktop */
+}
+@media (max-width: 768px) {
+  .dropdown-content,
+  .settings-content {
+    font-size: 16px; /* mobile bump — high-DPI phones need bigger body text */
+  }
+}
+```
+
+**Don't hardcode `text-sm` on row labels, NavigationRow titles, or panel
+descriptions** — that locks the text to 14px on every viewport and kills
+the mobile bump. Instead:
+
+- **Primary labels** (SettingsRow label, NavigationRow title, SubPageHeader
+  description, ad-hoc row labels in panels and integration forms): no
+  font-size class — inherits 14/16 from the wrapper. Use `<SettingLabel>`
+  rather than inlining a `<span>`; it adds `font-medium` for cased scripts
+  and drops the weight for caseless scripts (CJK / Arabic / Hebrew / Indic
+  / Thai / Tibetan), since those bold poorly at body size and `font-medium`
+  on Han / Hangul / Devanagari renders as uneven stroke-thickening across
+  system fonts.
+- **Secondary text** (SettingsRow description, NavigationRow status, Tips
+  body, BoxedList description): use `text-[0.85em]` so it stays
+  proportional (≈12px desktop, ≈13.6px mobile).
+- **Form controls** (`<input>`, `<select>`): browsers don't inherit
+  font-size onto form elements, so add the `settings-content` class
+  _directly on the element_ to re-apply the 14/16 cascade. The legacy
+  NumberInput already does this — match its pattern.
+- **Section headers** (`BoxedList` uppercase title): use `text-[0.85em]
+font-semibold uppercase tracking-wider`. The em-relative size keeps it
+  proportional with the `.settings-content` cascade. **Caseless-script
+  exception:** when `isCaselessUILang()` is true, bump to `text-[1em]`.
+  The `uppercase` rule is a no-op in scripts without case (CJK, Arabic,
+  Hebrew, Devanagari/Bengali/Tamil/Sinhala, Thai, Tibetan), so the size
+  has to carry the emphasis those scripts can't pick up from casing. The
+  helper lives in `src/utils/misc.ts`; the underlying `isCaselessLang`
+  predicate lists every covered language code in `src/utils/lang.ts`.
+
+Why this matters: Tailwind's `text-xs` / `text-sm` are rem-based — they
+ignore the parent's `font-size` because rem is rooted at the document.
+The `.settings-content` cascade is in `px`, so any child that picks a
+Tailwind size literally tunes itself to the desktop default and never
+grows on mobile. iOS and Android have small physical screens but high
+DPI, so the mobile bump is what makes the text legible at typical reading
+distance.
+
+#### Uniform row height
+
+Settings rows in a boxed list MUST all be the same visual height. Use
+`min-h-14 items-center` (56px) on each row container — toggle, select, and
+input rows then center their controls vertically inside identical boxes.
+**Don't use `py-3`** — content-driven padding produces uneven heights
+because toggles, selects (`h-9`), and inputs (`h-9`) have different
+intrinsic sizes.
+
+```tsx
+// ✓ Right — no text-sm; label inherits .settings-content (14/16)
+<label className='flex min-h-14 items-center justify-between px-4'>
+  <span className='font-medium'>{_('Sync Enabled')}</span>
+  <input type='checkbox' className='toggle' ... />
+</label>
+
+// ✗ Wrong — toggle row will be 48px, select rows 60px
+<label className='flex items-center justify-between px-4 py-3'>...</label>
+
+// ✗ Wrong — text-sm hardcodes 14px even on mobile (kills the bump)
+<span className='text-sm font-medium'>{_('Sync Enabled')}</span>
+```
+
+#### Controls inside a boxed list have no chrome
+
+When a control sits inside a bordered card, it shouldn't carry its own
+border or fill. The card supplies the visual boundary; the control just
+sits on the row.
+
+- **Selects:** drop `select-bordered` and `eink-bordered`. Add
+  `!bg-transparent !bg-none !appearance-none` to suppress daisyui's
+  background chevron and native arrow. Render a real `<MdArrowDropDown>`
+  icon at the cell's trailing edge for the affordance — see "End-aligned
+  values" below.
+- **Inputs:** drop `input-bordered` and `eink-bordered`. Add `!bg-transparent`
+  with `hover:!bg-base-200/60 focus:!bg-base-200/60` so the field still
+  signals interactability. Use `text-end` and `!pe-0` so the value sits
+  flush against the row's trailing edge.
+- **Toggles:** untouched — they're already chromeless.
+
+This is the iOS Settings / Adwaita PreferencesGroup convention: list
+chrome belongs to the container, not its children.
+
+#### End-aligned values + chevron alignment
+
+The selected value of a select/input MUST end-align (`text-end`). The
+**visible right edge** of every row's value (toggle, chevron icon, input
+text) MUST land at the same X — the row's trailing padding.
+
+The trap: daisyui's select renders its chevron via background-image at
+`calc(100% - 1rem) center`, which floats the glyph 16px _inside_ the
+select's right edge. So if the toggle in row 1 ends at the row's `pe-4`
+edge, the chevron in row 2 ends 16px before that — visibly misaligned.
+
+**Fix:** suppress daisyui's bg-image chevron and render an explicit icon at
+the cell's trailing edge. The select's own daisyui focus chrome (outline +
+box-shadow + ring) is suppressed; **no focus ring** on controls inside the
+boxed list — focus state is signaled by a subtle wrapper bg-shift instead
+(hover and focus-within both lift to `bg-base-200/60`). Rings would compete
+with the card's own border and double-stack with adjacent rows.
+
+```tsx
+<div className='hover:bg-base-200/60 focus-within:bg-base-200/60 flex max-w-[60%] items-center rounded-md'>
+  <select className='select h-9 min-w-0 cursor-pointer !appearance-none truncate !border-0 !bg-transparent !bg-none !pe-1 !ps-2 text-end text-sm focus:!border-0 focus:!shadow-none focus:!outline-none focus:!ring-0'>
+    {/* options */}
+  </select>
+  <MdArrowDropDown
+    aria-hidden='true'
+    className='text-base-content/55 pointer-events-none h-5 w-5 flex-shrink-0'
+  />
+</div>
+```
+
+> **Why so many `!` overrides?** daisyui's `.select` and `.input` apply
+> `border-width: 1px` + `border-color` (transparent at rest, `var(--bc)` on
+> focus), plus `outline`, `box-shadow`, and `ring` chrome on focus. To make
+> the control truly chromeless inside a boxed list, you need to kill all
+> four properties. Missing any of them — especially `border-0` — leaves a
+> visible focus border leaking through.
+
+The `<MdArrowDropDown>` icon's trailing edge now lives at the same X as the
+toggle's trailing edge in adjacent rows, because both are flush with the
+row's `pe-4` padding.
+
+For inputs, no wrapper is needed — the input is one element, so put the
+hover/focus bg directly on it. Suppress daisyui's own focus chrome the
+same way:
+
+```tsx
+<input className='input hover:!bg-base-200/60 focus:!bg-base-200/60 h-9 max-w-[60%] rounded-md !border-0 !bg-transparent !pe-0 !ps-2 text-end text-sm focus:!border-0 focus:!shadow-none focus:!outline-none focus:!ring-0' />
+```
+
+> **Why no ring here when §2.7 says "focus needs a visible ring"?** §2.7 is
+> for standalone custom buttons (Submit, Cancel, ListExtension, etc.). In a
+> boxed list, the row already provides strong visual containment via the
+> card border + dividers, and stacking a per-control ring inside that
+> creates double chrome. The bg-shift IS the focus indicator — keyboard
+> users still get clear feedback; the surface stays calm.
+
+---
+
+### 6. Header bars, dialogs, popups, sheets
+
+#### Header bar
+
+The dialog/page header. Adwaita's AdwHeaderBar.
+
+- **48–56px tall** (`h-12` to `h-14`).
+- **Center-aligned title** in `font-semibold text-base`.
+- **Leading slot**: back chevron (mobile) or empty (desktop).
+- **Trailing slot**: window controls — search (pill ghost), menu (pill ghost),
+  close (pill ghost circle with `bg-base-300/65`).
+- No bottom border; rely on tab/divider that follows.
+
+`SettingsDialog.tsx`'s mobile header is the canonical example. The desktop header is
+slightly different — tabs sit in the same row as window controls, no center title — but
+it's the same archetype adapted for screen real estate.
+
+#### Dialog (modal)
+
+```tsx
+<Dialog
+  isOpen={...}
+  onClose={...}
+  boxClassName="sm:min-w-[520px] overflow-hidden"
+  header={<HeaderBar />}
+>
+  {/* content */}
+</Dialog>
+```
+
+- `modal-box` provides the radius, max-width, and shadow (auto-removed in eink).
+- Width ~520px on desktop, full-width on mobile.
+- Bottom sheets on mobile via `snapHeight` prop.
+- Backdrop: `sm:!bg-black/50` (or `/20` when nested over a darker surface).
+
+#### Popup (popover)
+
+For dictionary lookups, annotation editors, and other anchored overlays. Uses the
+`Popup` component with a triangle pointer.
+
+- **Width**: clamp to fit content; ~320–420px typical.
+- **Surface**: `bg-base-100`, `rounded-lg`, soft shadow (eink removes shadow).
+- **Triangle**: pointer toward the anchor; eink has special triangle classes.
+- **Padding**: `p-3` to `p-4` for content.
+
+#### Sheet (mobile bottom)
+
+Reserved for mobile contextual menus and full-screen secondary panels. Uses the dialog's
+`snapHeight` prop. Adwaita doesn't have a native sheet but Readest's mobile pattern is
+the closest analog.
+
+- Always full-width.
+- Top corners rounded; bottom corners flat (it's anchored to the bottom).
+- Drag handle at top (the small horizontal pill) is mandatory if the sheet supports
+  swipe-to-dismiss.
+
+---
+
+### 7. Motion + a11y
+
+#### Motion
+
+- Default duration: **150ms** for color transitions.
+- Default easing: browser default (`ease`) or `ease-out`. Never `ease-in`.
+- Longer transitions (300ms+) only for layout changes (sheet snap, panel slide).
+- **Never** use `transform` for hover unless the transform IS the message
+  (chevron rotation, drag-handle drag visualization). E-ink doesn't render mid-transitions
+  cleanly and Adwaita's identity is calm.
+
+```tsx
+// Good — hover:bg-base-200 with transition-colors
+className = 'transition-colors duration-150 hover:bg-base-200';
+
+// Bad — scale on hover
+className = 'transition-transform hover:scale-105';
+```
+
+Existing exceptions: `.window-button` in globals.css uses `hover:scale-105`. That's
+legacy; new code shouldn't follow it.
+
+#### Reduced motion
+
+Reduced-motion preference is honored via the `no-transitions` class
+(`globals.css:624`). Layout-changing transitions should respect
+`prefers-reduced-motion: reduce` either via this class or `motion-safe:` Tailwind
+prefixes.
+
+#### Focus
+
+- Every focusable element must have a visible focus indicator.
+- Custom buttons:
+  `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-base-content/15`.
+- Inputs: rely on daisyui's input focus ring; inputs with custom styling use
+  `focus:ring-2 focus:ring-primary/40`.
+- Don't use `outline-none` without `focus-visible:` replacement.
+
+#### Hit targets
+
+- **Minimum**: 32px (the size of `btn-sm`).
+- **Recommended**: 40px (`btn`) on touch surfaces.
+- **Mobile**: 44px+ for taps that aren't fail-safe (delete, navigate-away).
+- The `touch-target` class in globals.css extends a small visual control's hit area to
+  44px without changing its rendered size — use it on icon-sized buttons in mobile UIs.
+
+#### Color contrast
+
+- Body text on background: WCAG AA (4.5:1) minimum.
+- Large text: WCAG AA Large (3:1) minimum.
+- Interactive text on hover state: still passes contrast on the new background.
+- Theme palette is generated from `(bg, fg, primary)`; the tinycolor pipeline keeps
+  contrast within range, but custom themes can break this — Settings → Color flags
+  low-contrast custom themes.
+
+#### Keyboard
+
+- Tab order matches visual order. If you use `flex-row-reverse` for visual layout,
+  consider `tabIndex` to fix order.
+- Modal focus trap: `<Dialog>` handles this.
+- Esc to dismiss: `<Dialog>` and `<Popup>` handle this.
+- Arrow keys for grouped controls (radio-like tab strips, sortable lists). dnd-kit's
+  `KeyboardSensor` is wired for sortable lists.
+
+---
+
+### 8. E-ink overlay (cross-cutting)
+
+E-ink mode is toggled by `[data-eink='true']` on the document. It applies a global
+override layer in `src/styles/globals.css:484-622` that:
+
+- Removes all `box-shadow`.
+- Forces `text-base-content`, `text-blue-*`, `text-red-*`, `text-neutral-content` to a
+  single foreground color.
+- Inverts `btn-primary` and `btn-outline` to base-content bg + base-100 text.
+- Adds 1px contrast borders to `.eink-bordered`, `.modal-box`, `.menu-container`,
+  `.popup-container`, `.alert`, `.opds-navigation .card`, `.booknote-item`,
+  `.bookitem-main`.
+
+What this means for new components:
+
+| Surface type                         | Required class          | Why                                                           |
+| ------------------------------------ | ----------------------- | ------------------------------------------------------------- |
+| Custom bordered button or input      | `eink-bordered`         | Gets the 1px contrast border in eink                          |
+| Primary CTA                          | `btn-primary`           | Picks up the inverted treatment                               |
+| Cancel / secondary action            | `btn-ghost` (no border) | Reads as "outlined" only after pairing with the CTA           |
+| Card / panel using `border-base-200` | `eink-bordered`         | Otherwise the soft border vanishes in eink                    |
+| Modal / Popup                        | (auto)                  | `modal-box` and `.popup-container` are handled in globals.css |
+
+Verification checklist before shipping a new UI:
+
+- [ ] Toggle Settings → Misc → Eink mode and re-test every screen.
+- [ ] Every container that has a soft border (`border-base-200`) still has visible
+      delineation.
+- [ ] Every CTA is distinguishable from its neighbors (cancel, secondary).
+- [ ] No hover transforms make the UI feel jumpy.
+- [ ] Text is fully opaque (no `text-base-content/60` content; eink can't render the
+      reduced opacity well).
+
+#### What's NOT compatible with e-ink
+
+- Drop shadows for hierarchy (use borders).
+- Color-only state changes (use border weight or fill swap).
+- Hover scale / translate (they look broken on slow refresh).
+- Animations longer than ~200ms (visible refresh artifacts).
+
+---
+
+### 9. Cross-platform grace notes
+
+Readest ships on **macOS, Windows, Linux, iOS, Android, web**. Adwaita is desktop-GNOME-
+native; we adapt where the host OS has strong conventions, but never at the cost of
+identity.
+
+#### iOS
+
+- Slightly larger corner radii feel native (`rounded-xl` on dialogs, `rounded-lg` on
+  cards).
+- Safe area insets are mandatory for top + bottom anchored elements (see
+  `docs/safe-area-insets.md`).
+- Avoid Material Design ripple effects.
+- Sheet-style modals (bottom-anchored) match iOS conventions and are preferred over
+  centered dialogs on phone-sized screens.
+
+#### Android
+
+- Material 3 conventions that conflict with Adwaita (FABs, elevation shadows, ripple
+  inks): **don't** copy them. Readest's identity is Adwaita; the user is reading on
+  Android, not in Android.
+- Touch targets bumped to 48px for primary actions (Material's recommended target).
+- Back-gesture-aware UIs: ensure swipe-from-edge doesn't conflict with horizontal swipe
+  controls.
+
+#### Linux
+
+- Native Adwaita territory. Readest can match host theme for window chrome (Tauri
+  decorations) but should keep its own internal palette for the reading surface — book
+  themes (sepia, gruvbox, etc.) are user choices, not OS choices.
+
+#### macOS / Windows
+
+- Window controls (close/minimize/maximize) are platform-native via Tauri.
+- Title bar height matches platform convention; internal layout follows Readest's
+  Adwaita palette.
+
+#### Web
+
+- No safe-area insets needed.
+- Keyboard shortcuts are doubled with command-palette discoverability (Cmd/Ctrl+K).
+- Browser-native focus rings: respected, augmented with `focus-visible:ring-*`.
+
+#### E-ink readers (Android-based, custom firmware)
+
+- Detected via the eink mode toggle (Settings → Misc).
+- All rules in §8 apply.
+- This is a **first-class** target, not a fallback.
+
+---
+
+### 10. Anti-patterns
+
+Things that LOOK fine in isolation but break the system. Each one has a real source diff
+or commit reference.
+
+#### 10.1 Loud outlined CTAs for non-primary actions
+
+```tsx
+// Anti-pattern (was in CustomDictionaries.tsx, fixed Nov 2026):
+<button className='btn btn-outline btn-primary gap-2 normal-case [--animation-btn:0s]'>
+  <MdAdd className='h-5 w-5' />
+  Import Dictionary
+</button>
+
+// Correct: ListExtension archetype (see §4.6)
+```
+
+Why it broke: the buttons read as primary CTAs but are list extensions. They competed
+with the active settings tab indicator and pulled the eye from the list itself.
+
+#### 10.2 Recoloring the whole button on hover
+
+```tsx
+// Anti-pattern:
+<button className="text-base-content/70 hover:text-base-content hover:bg-primary/10">
+
+// Correct: keep the label color steady, hover via bg shift on the surface
+<button className="text-base-content hover:bg-base-200 transition-colors">
+```
+
+Why: principle 2.4 (localize the hover signal). Whole-button color shifts feel decorative.
+
+#### 10.3 Transform-based hover
+
+```tsx
+// Anti-pattern:
+<button className="hover:scale-105 transition-transform">
+
+// Correct: color/border-based hover
+<button className="hover:bg-base-200 hover:border-base-300 transition-colors">
+```
+
+Why: breaks under e-ink (§2.5), feels jumpy under Adwaita's calm rhythm.
+
+#### 10.4 Soft borders without `eink-bordered`
+
+```tsx
+// Anti-pattern:
+<div className="border border-base-200 bg-base-100 rounded-lg p-4">
+  ...
+</div>
+
+// Correct:
+<div className="eink-bordered border border-base-200 bg-base-100 rounded-lg p-4">
+  ...
+</div>
+```
+
+Why: in e-ink mode, `base-200` borders disappear into the background. `eink-bordered`
+flips the border to `base-content` so the boundary stays visible.
+
+Exception: containers that **don't** need a visible boundary in eink (e.g., a
+`bg-base-100` surface that's already against `bg-base-200`) can skip `eink-bordered`.
+The class is opt-in for "this surface needs a border to read correctly".
+
+#### 10.5 Reduced-opacity text in e-ink
+
+```tsx
+// Anti-pattern (in eink):
+<span className="text-base-content/50">Optional metadata</span>
+
+// Correct (still readable in eink):
+<span className="text-base-content text-xs">Optional metadata</span>
+// Or use semantic muting that the eink overlay handles:
+<span className="text-neutral-content">Optional metadata</span>
+```
+
+Why: e-ink's reduced color depth turns `/50` opacity into illegible mush. Use size or
+weight for hierarchy on muted secondary text.
+
+#### 10.6 Daisyui `btn` defaults without intent
+
+```tsx
+// Anti-pattern: just reaching for `btn` with no role:
+<button className="btn">Click me</button>
+
+// Correct: pick an archetype from §4.
+<button className="btn btn-ghost">Cancel</button>      // Flat
+<button className="btn btn-primary">Save</button>      // Accent CTA
+```
+
+Why: daisyui's `btn` default isn't tuned for any specific role. Pick from the action
+vocabulary so the button signals its weight in the surface hierarchy.
+
+#### 10.7 Ad-hoc surface tokens
+
+```tsx
+// Anti-pattern:
+<div className="bg-white border-gray-200">
+
+// Correct:
+<div className="bg-base-100 border-base-200">
+```
+
+Why: hard-coded colors don't theme. Readest has 11 themes plus user-defined custom themes.
+Always use the daisyui semantic tokens.
+
+#### 10.8 Mixing `btn` sizes within a surface
+
+```tsx
+// Anti-pattern:
+<header>
+  <button className="btn btn-sm">Search</button>
+  <button className="btn btn-md">Settings</button>
+  <button className="btn btn-xs">Close</button>
+</header>
+
+// Correct: one size per surface
+<header>
+  <button className="btn btn-ghost btn-circle h-8 min-h-8 w-8">Search</button>
+  <button className="btn btn-ghost btn-circle h-8 min-h-8 w-8">Settings</button>
+  <button className="btn btn-ghost btn-circle h-8 min-h-8 w-8">Close</button>
+</header>
+```
+
+Why: visual rhythm. Mixed sizes feel like the surface is unfinished.
+
+---
+
+### 11. Quick reference
+
+When designing a new surface, walk this checklist:
+
+1. **What's the surface tier?** Window / View / Card. (§3)
+2. **What's the corner radius?** Match the tier. (§3)
+3. **Is there a primary action?** If yes, ONE accent CTA. If no, all flats. (§4.1, §4.3)
+4. **Are there list extensions?** Use the ListExtension archetype, not `btn-outline btn-primary`. (§4.6)
+5. **Is it a list?** Use the BoxedList chassis with ActionRow / SwitchRow / ComboRow / ExpanderRow rows. (§5)
+6. **Does it need `eink-bordered`?** If it has a soft border that must stay visible in
+   eink mode, yes. (§8)
+7. **Is the hover signal localized?** One focal element changes, not the whole control. (§2.4)
+8. **Is motion color-only?** No transforms unless the transform IS the message. (§2.5)
+9. **Is focus visible?** `focus-visible:ring-2 focus-visible:ring-base-content/15` on
+   custom buttons. (§7)
+10. **Will it work on the smallest theme + e-ink?** Toggle Sepia + Eink, retest.
+
+---
+
+### 12. Glossary
+
+- **Adwaita / libadwaita**: GNOME's design system and widget toolkit. Source of Readest's
+  visual lineage.
+- **AdwActionRow / AdwSwitchRow / AdwComboRow / AdwExpanderRow**: libadwaita's row
+  primitives. Readest mirrors these conceptually with custom React components.
+- **AdwBoxedList**: libadwaita's named container for grouped action rows.
+- **AdwBanner**: top-of-window inline alert (persistent).
+- **AdwToast**: bottom slide-in transient alert.
+- **Window / View / Card**: surface tiers (§3).
+- **ListExtension**: Readest-named archetype for "+ add new row" buttons (§4.6).
+- **eink-bordered**: utility class in `globals.css` that gives a surface its e-ink-mode
+  contrast border. Opt-in.
+- **Pill ghost**: circular icon button, `btn-ghost btn-circle`.
+
+---
+
+### 13. Maintenance
+
+This doc is the **source of truth** for new design decisions. When the system grows:
+
+- New archetypes get a numbered subsection in §4 or §5.
+- New anti-patterns get added to §10 with a real source reference.
+- Updates to existing principles require a brief why-changed note in the relevant section.
+
+Cross-references that must stay in sync:
+
+- `CLAUDE.md` E-ink mode section → §8 of this doc.
+- `docs/safe-area-insets.md` → §9 (cross-platform).
+- `src/styles/globals.css` `[data-eink]` rules → §8.
+- `src/styles/themes.ts` Palette type → §3 token table.
+
+If you change a rule here, search for the cross-reference and update both.

apps/readest-app/biome.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.9/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": { "ignoreUnknown": true },
+  "formatter": { "enabled": false },
+  "assist": { "enabled": false },
+  "css": { "linter": { "enabled": false } },
+  "linter": {
+    "enabled": true,
+    "includes": [
+      "**",
+      "!.next/**",
+      "!.open-next/**",
+      "!.wrangler/**",
+      "!.claude/**",
+      "!dist/**",
+      "!out/**",
+      "!build/**",
+      "!public/**",
+      "!src-tauri/**",
+      "!next-env.d.ts",
+      "!i18next-scanner.config.cjs"
+    ],
+    "rules": {
+      "recommended": true,
+      "a11y": {
+        "recommended": true,
+        "useKeyWithClickEvents": "off",
+        "useKeyWithMouseEvents": "off",
+        "noSvgWithoutTitle": "off",
+        "noLabelWithoutControl": "off",
+        "useSemanticElements": "off",
+        "noAriaHiddenOnFocusable": "off",
+        "noInteractiveElementToNoninteractiveRole": "off",
+        "noNoninteractiveElementToInteractiveRole": "off",
+        "noNoninteractiveElementInteractions": "off",
+        "noStaticElementInteractions": "off",
+        "noNoninteractiveTabindex": "off",
+        "useButtonType": "off",
+        "useAriaPropsSupportedByRole": "off",
+        "useFocusableInteractive": "off",
+        "noAutofocus": "off"
+      },
+      "complexity": {
+        "noForEach": "off",
+        "noStaticOnlyClass": "off",
+        "noUselessSwitchCase": "off",
+        "noUselessFragments": "off",
+        "noUselessCatch": "off",
+        "useLiteralKeys": "off",
+        "useOptionalChain": "off",
+        "noThisInStatic": "off",
+        "useArrowFunction": "off",
+        "noUselessEscapeInRegex": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": "warn",
+        "noUnusedImports": "error",
+        "useExhaustiveDependencies": "off",
+        "useHookAtTopLevel": "error",
+        "useJsxKeyInIterable": "error",
+        "noChildrenProp": "error",
+        "noNextAsyncClientComponent": "warn",
+        "noSwitchDeclarations": "off",
+        "noUndeclaredVariables": "off",
+        "noEmptyCharacterClassInRegex": "off",
+        "useParseIntRadix": "off",
+        "noEmptyPattern": "off"
+      },
+      "nursery": {
+        "noBeforeInteractiveScriptOutsideDocument": "warn",
+        "noDuplicateEnumValues": "error",
+        "noSyncScripts": "warn",
+        "useInlineScriptId": "error"
+      },
+      "performance": {
+        "noImgElement": "off",
+        "noUnwantedPolyfillio": "warn",
+        "useGoogleFontPreconnect": "warn"
+      },
+      "security": {
+        "noBlankTarget": "off",
+        "noDangerouslySetInnerHtmlWithChildren": "off",
+        "noDangerouslySetInnerHtml": "off"
+      },
+      "style": {
+        "noNonNullAssertion": "off",
+        "useImportType": "off",
+        "noParameterAssign": "off",
+        "useDefaultParameterLast": "off",
+        "noUselessElse": "off",
+        "noHeadElement": "warn",
+        "noCommonJs": "off",
+        "useFilenamingConvention": "off",
+        "useNamingConvention": "off",
+        "noUnusedTemplateLiteral": "off",
+        "useTemplate": "off",
+        "useExponentiationOperator": "off",
+        "useNodejsImportProtocol": "off"
+      },
+      "suspicious": {
+        "noExplicitAny": "error",
+        "noArrayIndexKey": "off",
+        "noAssignInExpressions": "off",
+        "noDoubleEquals": "off",
+        "noDocumentImportInPage": "error",
+        "noHeadImportInDocument": "error",
+        "useGoogleFontDisplay": "warn",
+        "noCommentText": "error",
+        "noDuplicateJsxProps": "error",
+        "noAsyncPromiseExecutor": "off",
+        "noImplicitAnyLet": "off",
+        "noControlCharactersInRegex": "off",
+        "noEmptyBlockStatements": "off",
+        "useIterableCallbackReturn": "off",
+        "noGlobalIsNan": "off",
+        "noConfusingVoidType": "off",
+        "noConstEnum": "off"
+      }
+    }
+  },
+  "javascript": {
+    "globals": ["React"]
+  }
+}

apps/readest-app/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/utils",
+    "ui": "@/components/ui",
+    "lib": "@/libs",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

apps/readest-app/docs/i18n.md

@@ -0,0 +1,72 @@
+## i18n Guide
+
+Readest uses a **key-as-content** approach — English strings are the translation keys. The English locale (`en/translation.json`) is empty because keys serve as content. Other locales contain actual translations.
+
+### In React Components
+
+```tsx
+import { useTranslation } from '@/hooks/useTranslation';
+
+const _ = useTranslation();
+_('Progress synced');
+```
+
+### In Non-React Modules
+
+Two-step process:
+
+**1. Declaration** — Use `stubTranslation` to mark strings for scanner extraction (returns key as-is, does NOT translate):
+
+```ts
+import { stubTranslation as _ } from '@/utils/misc';
+
+// These calls only register keys for extraction
+_('Reveal in Finder');
+_('Reveal in Explorer');
+```
+
+**2. Usage** — In the React component that consumes the value, apply the real `_()` from `useTranslation`:
+
+```tsx
+const _ = useTranslation();
+const label = _(getRevealLabel()); // translates at runtime
+```
+
+### Extraction & Translation
+
+```bash
+pnpm i18n:extract    # Scans codebase, adds new keys with __STRING_NOT_TRANSLATED__
+```
+
+- Translation files: `public/locales/<locale>/translation.json`
+- Only `_('KEY')` and `_('KEY', options)` patterns are recognized by i18next-scanner
+
+### Adding a New Translation Language
+
+The supported language set has a single ground truth: [`i18n-langs.json`](../i18n-langs.json). Both the i18next runtime (`src/i18n/i18n.ts`) and the extractor (`i18next-scanner.config.cjs`) read from it, so adding a locale is a two-file change plus a translation pass.
+
+1. **Add the locale code** to [`i18n-langs.json`](../i18n-langs.json). Use the exact code i18next will emit (e.g. `hu`, `zh-CN`). Do not add `en` — it's the source language and lives outside this list.
+
+2. **Add a display label** to `TRANSLATED_LANGS` in [`src/services/constants.ts`](../src/services/constants.ts). The key is the locale code, the value is the language's native name (e.g. `hu: 'Magyar'`). This is what users see in the language picker.
+
+3. **Generate the translation file**:
+
+   ```bash
+   pnpm i18n:extract
+   ```
+
+   This creates `public/locales/<code>/translation.json` with every key set to `__STRING_NOT_TRANSLATED__`.
+
+4. **Translate** every `__STRING_NOT_TRANSLATED__` placeholder in the new file. The `/i18n` skill automates this; the singular `en/translation.json` only holds plural variants and proper nouns, so use the JSON keys themselves as the English source.
+
+5. **Verify** with `grep -r "__STRING_NOT_TRANSLATED__" public/locales/<code>/` — the result should be empty.
+
+6. **Translate the KOReader companion plugin** (`apps/readest.koplugin`). It pulls the locale set from the same `i18n-langs.json` via the scanner config, but the catalog format is gettext `.po`, not JSON. Steps:
+   - Add a `LANG_META` entry (label + Plural-Forms) for the new code in [`apps/readest.koplugin/scripts/extract-i18n.js`](../../readest.koplugin/scripts/extract-i18n.js). Without it the extractor prints `<code> skipped (no metadata in extract-i18n.js)` and the catalog is never created.
+   - Trigger the `/i18n-koplugin` skill to run extraction and fill every empty `msgstr ""` in `apps/readest.koplugin/locales/<code>/translation.po`.
+
+### Rules
+
+- `stubTranslation` is for extraction only — always apply `_()` from `useTranslation` in the component for runtime translation.
+- Fallback: when no translation exists, the English key itself is displayed.
+- Error messages: register keys with `stubTranslation` in utility modules (e.g. `src/services/errors.ts`), return the English key from helpers, wrap with `_()` in the component.

apps/readest-app/docs/safe-area-insets.md

@@ -0,0 +1,52 @@
+## Safe Area Insets
+
+The app runs on devices with notches, status bars, and rounded corners (iOS, Android). UI elements near screen edges must account for safe area insets to avoid being obscured.
+
+### Key Concepts
+
+- **`gridInsets: Insets`** — Per-view insets derived from view settings (header/footer visibility, margins). Calculated by `getViewInsets()` in `src/utils/insets.ts`. Passed as a prop from `BooksGrid` → child components.
+- **`statusBarHeight: number`** — OS status bar height (default 24px). Stored in `themeStore`.
+- **`systemUIVisible: boolean`** — Whether the system UI (status bar, navigation bar) is currently shown. Stored in `themeStore`.
+- **`appService?.hasSafeAreaInset`** — Whether the platform requires safe area handling (mobile devices).
+
+### Top Inset Rules
+
+For UI elements anchored to the **top** of the screen (headers, close buttons, overlays):
+
+```tsx
+// When system UI is visible, use the larger of gridInsets.top and statusBarHeight
+// When system UI is hidden, use gridInsets.top alone
+style={{
+  marginTop: systemUIVisible
+    ? `${Math.max(gridInsets.top, statusBarHeight)}px`
+    : `${gridInsets.top}px`,
+}}
+```
+
+For containers that need safe area padding at the top:
+
+```tsx
+style={{
+  paddingTop: appService?.hasSafeAreaInset ? `${gridInsets.top}px` : '0px',
+}}
+```
+
+### Bottom Inset Rules
+
+For UI elements anchored to the **bottom** of the screen (footer bars, controls, progress indicators), use `gridInsets.bottom * 0.33` as padding — a fraction of the full inset since bottom bars don't need as much clearance as the home indicator area:
+
+```tsx
+style={{
+  paddingBottom: appService?.hasSafeAreaInset ? `${gridInsets.bottom * 0.33}px` : 0,
+}}
+```
+
+### Passing `gridInsets`
+
+When creating overlay components (image viewers, table viewers, zoom controls, etc.), always pass `gridInsets` as a prop so they can position their controls correctly:
+
+```tsx
+<ImageViewer gridInsets={gridInsets} ... />
+<TableViewer gridInsets={gridInsets} ... />
+<ZoomControls gridInsets={gridInsets} ... />
+```

apps/readest-app/docs/testing.md

@@ -0,0 +1,110 @@
+# Testing
+
+Readest uses three test tiers, all powered by [Vitest](https://vitest.dev/).
+
+## Unit Tests (`pnpm test`)
+
+Runs tests in a **jsdom** environment. No browser or Tauri runtime required.
+
+```bash
+pnpm test                                       # Run all unit tests
+pnpm test -- src/__tests__/utils/misc.test.ts   # Run a single file
+pnpm test -- --watch                            # Watch mode
+```
+
+- **Config:** `vitest.config.mts`
+- **Pattern:** `src/**/*.test.ts` (excludes `*.browser.test.ts` and `*.tauri.test.ts`)
+- **Environment:** jsdom
+- **Use for:** Pure logic, utilities, services that don't need real browser APIs or Tauri IPC.
+
+## Browser Tests (`pnpm test:browser`)
+
+Runs tests in a **real Chromium** browser via Playwright. Required for code that depends on Web Workers, SharedArrayBuffer, OPFS, or other browser-only APIs.
+
+```bash
+pnpm test:browser
+```
+
+- **Config:** `vitest.browser.config.mts`
+- **Pattern:** `src/**/*.browser.test.ts`
+- **Browser:** Chromium (headless, via `@vitest/browser-playwright`)
+- **Use for:** WASM modules (e.g. `@tursodatabase/database-wasm`), Web Worker integration, browser-specific storage APIs.
+
+## Tauri Integration Tests (`pnpm test:tauri`)
+
+Runs Vitest tests **inside the Tauri WebView**, with access to Tauri IPC and native plugin commands. Tests execute in the actual app environment.
+
+### Step 1: Start the Tauri App
+
+In one terminal, start the app with the `webdriver` feature enabled:
+
+```bash
+pnpm tauri:dev:test     # Dev mode (uses tauri dev server, faster iteration)
+pnpm tauri:build:test   # Debug release build (closer to production)
+```
+
+These commands compile the Rust backend with `--features webdriver`, which:
+
+- Includes `tauri-plugin-webdriver` (embeds a W3C WebDriver server on port 4445)
+- Adds a runtime capability granting plugin permissions to remote URLs (`http://127.0.0.1:*`), so Vitest's browser-mode iframe can call Tauri IPC
+
+Keep this running while you run tests.
+
+### Step 2: Run Tests
+
+In another terminal:
+
+```bash
+pnpm test:tauri
+```
+
+Vitest connects directly to the embedded WebDriver server (port 4445) in the running Tauri app and executes tests inside its WebView.
+
+- **Config:** `vitest.tauri.config.mts`
+- **Pattern:** `src/**/*.tauri.test.ts`
+- **Browser provider:** `@vitest/browser-webdriverio` (connects to port 4445)
+- **Use for:** Tauri plugin commands (turso, native-tts, etc.), native filesystem, Tauri IPC.
+
+### Writing Tauri Tests
+
+Tests access Tauri IPC via a shared helper:
+
+```typescript
+import { invoke } from '../tauri/tauri-invoke';
+
+it('calls a plugin command', async () => {
+  const result = await invoke('plugin:turso|load', { options: { path: 'sqlite::memory:' } });
+  expect(result).toBeDefined();
+});
+```
+
+The `invoke()` helper accesses `window.top.__TAURI_INTERNALS__` (Vitest runs in an iframe, Tauri injects IPC into the main frame).
+
+**Limitations:** Only custom invoke commands and plugin commands listed in the webdriver capability work. Standard Tauri JS APIs (e.g. `@tauri-apps/api`) that rely on `URL: local` may not work from the Vitest iframe.
+
+## E2E Tests (WDIO)
+
+Full end-to-end tests using WebDriverIO, for UI-level testing against the running Tauri app. Same two-step workflow as Tauri integration tests.
+
+```bash
+# Terminal 1: start the app (same as for Tauri integration tests)
+pnpm tauri:dev:test
+
+# Terminal 2: run E2E tests
+pnpm test:e2e
+```
+
+- **Config:** `wdio.conf.ts`
+- **Pattern:** `e2e/**/*.e2e.ts`
+- **Framework:** Mocha (via `@wdio/mocha-framework`)
+- **Connects to:** port 4445 (embedded WebDriver server)
+- **Use for:** UI interaction tests, window management, navigation flows.
+
+## Test File Naming
+
+| Suffix              | Runner              | Environment           |
+| ------------------- | ------------------- | --------------------- |
+| `*.test.ts`         | `pnpm test`         | jsdom                 |
+| `*.browser.test.ts` | `pnpm test:browser` | Chromium (Playwright) |
+| `*.tauri.test.ts`   | `pnpm test:tauri`   | Tauri WebView         |
+| `*.e2e.ts`          | `pnpm test:e2e`     | Tauri app (WDIO)      |

apps/readest-app/docs/view-settings.md

@@ -0,0 +1,209 @@
+## Adding a Config to `ViewSettings`
+
+`ViewSettings` is the per-book view state (layout, fonts, colors, TTS, etc.) composed from several sub-interfaces defined in `src/types/book.ts`. A matching `globalViewSettings` lives on `SystemSettings` and acts as the default for every book. The per-book value is derived by merging the global defaults with any overrides stored on the book's `BookConfig`.
+
+This doc covers how to plumb a new config through the three layers:
+
+1. **Types** — `src/types/book.ts`
+2. **Defaults** — `src/services/constants.ts` and `src/services/settingsService.ts`
+3. **Read/write** — components via `saveViewSettings` from `src/helpers/settings.ts`
+
+### Pick a Pattern
+
+**Pattern A — add a field to an existing sub-interface.** Use when the new option belongs to an existing bundle (`BookLayout`, `BookStyle`, `BookFont`, `ViewConfig`, `TTSConfig`, etc.).
+
+**Pattern B — introduce a new sub-interface.** Use when several related fields cluster together, or when a single field is semantically its own concept (e.g. `ParagraphModeConfig`, `ViewSettingsConfig`). Then extend `ViewSettings` with it.
+
+Both patterns follow the same three-layer flow. The only difference is whether you reuse an existing `DEFAULT_*` constant or add a new one.
+
+### Step 1 — Declare the Type
+
+**Pattern A** — add a required field to the sub-interface that owns this concern:
+
+```ts
+// src/types/book.ts
+export interface ViewConfig {
+  // ...existing fields
+  myNewToggle: boolean;
+}
+```
+
+**Pattern B** — define a new interface and extend `ViewSettings`:
+
+```ts
+// src/types/book.ts
+export interface ViewSettingsConfig {
+  isGlobal: boolean;
+}
+
+export interface ViewSettings
+  extends
+    BookLayout,
+    BookStyle,
+    // ...other bundles
+    ViewSettingsConfig {}
+```
+
+Fields should be **required**, not optional. Optional fields make downstream code defensive. Provide a sensible default in Step 2 instead.
+
+### Step 2 — Provide a Default
+
+Every field in `ViewSettings` must have a default, otherwise `getDefaultViewSettings()` produces an incomplete object.
+
+**Pattern A** — add the value to the existing `DEFAULT_*` constant:
+
+```ts
+// src/services/constants.ts
+export const DEFAULT_VIEW_CONFIG: ViewConfig = {
+  // ...existing defaults
+  myNewToggle: false,
+};
+```
+
+**Pattern B** — add a `DEFAULT_*_CONFIG` constant for your new bundle, then register it in `getDefaultViewSettings`:
+
+```ts
+// src/services/constants.ts
+export const DEFAULT_VIEW_SETTINGS_CONFIG: ViewSettingsConfig = {
+  isGlobal: true,
+};
+```
+
+```ts
+// src/services/settingsService.ts
+export function getDefaultViewSettings(ctx: Context): ViewSettings {
+  return {
+    ...DEFAULT_BOOK_LAYOUT,
+    ...DEFAULT_BOOK_STYLE,
+    // ...other bundles
+    ...DEFAULT_VIEW_SETTINGS_CONFIG,
+    // platform overrides go last so they win
+    ...(ctx.isMobile ? DEFAULT_MOBILE_VIEW_SETTINGS : {}),
+    ...(ctx.isEink ? DEFAULT_EINK_VIEW_SETTINGS : {}),
+    ...(isCJKEnv() ? DEFAULT_CJK_VIEW_SETTINGS : {}),
+  };
+}
+```
+
+#### Platform Overrides
+
+To tweak the default on mobile, e-ink, or CJK locales, add the field to the matching `Partial<ViewSettings>` constant (`DEFAULT_MOBILE_VIEW_SETTINGS`, `DEFAULT_EINK_VIEW_SETTINGS`, `DEFAULT_CJK_VIEW_SETTINGS`). These are spread after the base defaults in `getDefaultViewSettings`, so they override them.
+
+#### Migration
+
+Old `settings.json` files on disk won't have your new field. `loadSettings` merges the stored blob over fresh defaults:
+
+```ts
+settings.globalViewSettings = {
+  ...getDefaultViewSettings(ctx),
+  ...settings.globalViewSettings,
+};
+```
+
+So existing users pick up your default automatically — no explicit migration is needed for adding a field. Only bump `SYSTEM_SETTINGS_VERSION` if you are reshaping existing data.
+
+### Step 3 — Read and Write from Components
+
+Read the current value by preferring the per-book settings, falling back to the global:
+
+```tsx
+const { settings } = useSettingsStore();
+const { getViewSettings } = useReaderStore();
+const viewSettings = getViewSettings(bookKey) || settings.globalViewSettings;
+```
+
+Write via `saveViewSettings` — never mutate the store directly. The helper handles the global-vs-per-book routing, persists to disk, and re-applies styles when needed.
+
+```tsx
+import { saveViewSettings } from '@/helpers/settings';
+
+const [myNewToggle, setMyNewToggle] = useState(viewSettings.myNewToggle);
+
+useEffect(() => {
+  saveViewSettings(envConfig, bookKey, 'myNewToggle', myNewToggle);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+}, [myNewToggle]);
+```
+
+The `useEffect`-on-local-state pattern is the established convention in `LayoutPanel`, `ControlPanel`, `ColorPanel`, etc. It keeps the UI responsive and batches store updates until the user stops interacting.
+
+#### Signature
+
+```ts
+saveViewSettings<K extends keyof ViewSettings>(
+  envConfig,
+  bookKey,
+  key: K,
+  value: ViewSettings[K],
+  skipGlobal = false,     // true → only update this book's settings
+  applyStyles = true,     // false → don't re-run style recomputation
+)
+```
+
+**Global vs. per-book routing.** `saveViewSettings` inspects `viewSettings.isGlobal` on the target book. When `true` (the default), it writes to `globalViewSettings`, loops through every open book, and saves to disk. When `false`, it writes only to the one book's config.
+
+**Skip global.** Pass `skipGlobal=true` when the setting is meta — i.e. it describes the settings system itself, not book content. The canonical case is toggling `isGlobal` from `DialogMenu`: you want the scope flag to live on the specific book without propagating it to every other book.
+
+```tsx
+saveViewSettings(envConfig, bookKey, 'isGlobal', !isSettingsGlobal, true, false);
+```
+
+**Skip styles.** Pass `applyStyles=false` for options that don't affect CSS rendering (toggles, flags, metadata). This avoids an unnecessary `renderer.setStyles` call.
+
+### Step 4 — Support Reset
+
+If your field should be resettable from the panel menu, register a setter in the panel's `handleReset` via `useResetViewSettings`:
+
+```tsx
+const resetToDefaults = useResetViewSettings();
+
+const handleReset = () => {
+  resetToDefaults({
+    myNewToggle: setMyNewToggle,
+    // ...other setters
+  });
+};
+```
+
+The hook resolves the default by reading from `getDefaultViewSettings(ctx)` and calls each provided setter with that value, which then fires your `useEffect` and persists the change.
+
+### Step 5 — Register in the Command Palette
+
+If your setting has a visible row in a panel, register it in the matching `*PanelItems` array in `src/services/commandRegistry.ts`. This wires it into the command-palette fuzzy search so users can jump straight to it.
+
+```ts
+// src/services/commandRegistry.ts
+const layoutPanelItems = [
+  // ...existing entries
+  {
+    id: 'settings.layout.myNewToggle',
+    labelKey: _('My New Toggle'),
+    keywords: ['search', 'terms', 'for', 'discoverability'],
+    section: 'Paragraph',
+  },
+];
+```
+
+- `id` must match the `data-setting-id` attribute on the panel row. The palette uses it to scroll/highlight the target control.
+- `labelKey` uses `stubTranslation` (imported as `_`) so the extractor picks it up — the same string that appears in the panel.
+- `keywords` broadens fuzzy-search hits beyond the label; include synonyms, related jargon, and the panel section name.
+- `section` groups the entry in the palette results (matches the panel's sub-header: `Layout`, `Paragraph`, `Page`, `Header & Footer`, etc.).
+
+Skip this step only for settings that don't surface as a user-visible row (hidden toggles, flags used by other settings).
+
+### Don'ts
+
+- **Don't make the field optional** just to skip providing a default. Add a default in Step 2 instead.
+- **Don't mutate `settings.globalViewSettings` directly** in a component — `saveViewSettings` already handles global propagation when `isGlobal` is true.
+- **Don't bump `SYSTEM_SETTINGS_VERSION`** for a plain additive field. The load-time merge handles it.
+
+### Minimal Checklist
+
+- [ ] Field or new interface added in `src/types/book.ts`
+- [ ] Default value in `src/services/constants.ts`
+- [ ] New `DEFAULT_*_CONFIG` spread into `getDefaultViewSettings` (Pattern B only)
+- [ ] Optional mobile/eink/CJK override in the matching `Partial<ViewSettings>` constant
+- [ ] Read via `getViewSettings(bookKey) || settings.globalViewSettings`
+- [ ] Write via `saveViewSettings(envConfig, bookKey, 'key', value)`
+- [ ] Reset setter wired into `useResetViewSettings` if the panel has a reset menu
+- [ ] Command-palette entry added to the matching `*PanelItems` array in `src/services/commandRegistry.ts`, with an `id` that matches the panel row's `data-setting-id`

apps/readest-app/e2e/app.e2e.ts

@@ -0,0 +1,123 @@
+describe('Readest App Launch', () => {
+  it('should have a visible body element', async () => {
+    const body = await $('body');
+    await body.waitForDisplayed({ timeout: 10000 });
+    expect(await body.isDisplayed()).toBe(true);
+  });
+
+  it('should have the correct window handle', async () => {
+    const handle = await browser.getWindowHandle();
+    expect(handle).toBeTruthy();
+  });
+
+  it('should return the page source', async () => {
+    const source = await browser.getPageSource();
+    expect(source).toContain('html');
+  });
+});
+
+describe('Library Page', () => {
+  it('should navigate to the library page', async () => {
+    const url = await browser.getUrl();
+    expect(url).toMatch(/library|localhost/);
+  });
+
+  it('should display the library container', async () => {
+    const library = await $('[aria-label="Your Library"]');
+    await library.waitForExist({ timeout: 15000 });
+    expect(await library.isExisting()).toBe(true);
+  });
+
+  it('should display the library header', async () => {
+    const header = await $('[aria-label="Library Header"]');
+    await header.waitForExist({ timeout: 10000 });
+    expect(await header.isExisting()).toBe(true);
+  });
+
+  it('should display the bookshelf area', async () => {
+    const bookshelf = await $('[aria-label="Bookshelf"]');
+    await bookshelf.waitForExist({ timeout: 10000 });
+    expect(await bookshelf.isExisting()).toBe(true);
+  });
+
+  it('should have a search input', async () => {
+    const searchInput = await $('.search-input');
+    await searchInput.waitForExist({ timeout: 10000 });
+    expect(await searchInput.isExisting()).toBe(true);
+  });
+
+  it('should allow typing in the search input', async () => {
+    const searchInput = await $('.search-input');
+    await searchInput.waitForDisplayed({ timeout: 10000 });
+    await searchInput.setValue('test search');
+    const value = await searchInput.getValue();
+    expect(value).toBe('test search');
+  });
+
+  it('should show the clear search button after typing', async () => {
+    const clearBtn = await $('[aria-label="Clear Search"]');
+    await clearBtn.waitForExist({ timeout: 5000 });
+    expect(await clearBtn.isExisting()).toBe(true);
+  });
+
+  it('should clear the search input when clear button is clicked', async () => {
+    const clearBtn = await $('[aria-label="Clear Search"]');
+    await clearBtn.click();
+    const searchInput = await $('.search-input');
+    const value = await searchInput.getValue();
+    expect(value).toBe('');
+  });
+
+  it('should have a select books button', async () => {
+    const selectBtn = await $('[aria-label="Select Books"]');
+    await selectBtn.waitForExist({ timeout: 10000 });
+    expect(await selectBtn.isExisting()).toBe(true);
+  });
+
+  it('should have an import books button', async () => {
+    const importBtn = await $('[aria-label="Import Books"]');
+    await importBtn.waitForExist({ timeout: 10000 });
+    expect(await importBtn.isExisting()).toBe(true);
+  });
+});
+
+describe('Window Management', () => {
+  it('should return the window size', async () => {
+    const size = await browser.getWindowSize();
+    expect(size.width).toBeGreaterThan(0);
+    expect(size.height).toBeGreaterThan(0);
+  });
+});
+
+describe('JavaScript Execution', () => {
+  it('should execute JavaScript in the app context', async () => {
+    const result = await browser.execute(() => {
+      return document.readyState;
+    });
+    expect(result).toBe('complete');
+  });
+
+  it('should access the document title via JS', async () => {
+    const title = await browser.execute(() => {
+      return document.title;
+    });
+    expect(title).toContain('Readest');
+  });
+
+  it('should detect the app platform globals', async () => {
+    const hasCLIAccess = await browser.execute(() => {
+      return (window as unknown as Record<string, unknown>).__READEST_CLI_ACCESS === true;
+    });
+    expect(hasCLIAccess).toBe(true);
+  });
+});
+
+describe('Navigation', () => {
+  it('should navigate back to library after visiting another route', async () => {
+    const currentUrl = await browser.getUrl();
+    await browser.url(currentUrl.replace(/\/[^/]*$/, '/library'));
+    const library = await $('[aria-label="Your Library"]');
+    await library.waitForExist({ timeout: 15000 });
+    expect(await library.isExisting()).toBe(true);
+  });
+});

apps/readest-app/e2e/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["mocha", "@wdio/globals/types"]
+  },
+  "include": ["./**/*.ts"]
+}

apps/readest-app/eslint.config.mjs

@@ -1,13 +0,0 @@
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import js from "@eslint/js";
-import { FlatCompat } from "@eslint/eslintrc";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const compat = new FlatCompat({
-    baseDirectory: __dirname,
-    recommendedConfig: js.configs.recommended,
-    allConfig: js.configs.all
-});
-export default [...compat.extends("next/core-web-vitals", "next/typescript")];

apps/readest-app/extensions/windows-thumbnail/Cargo.lock

@@ -0,0 +1,588 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "anyhow"
+version = "1.0.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
+
+[[package]]
+name = "arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+dependencies = [
+ "derive_arbitrary",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+
+[[package]]
+name = "bumpalo"
+version = "3.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46c5e41b57b8bba42a04676d81cb89e9ee8e859a1a66f80a5a72e1cb76b34d43"
+
+[[package]]
+name = "bytemuck"
+version = "1.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbdf580320f38b612e485521afda1ee26d10cc9884efaaa750d383e13e3c5f4"
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "crc32fast"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "derive_arbitrary"
+version = "1.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "directories-next"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "339ee130d97a610ea5a5872d2bbb130fdf68884ff09d3028b81bec8a1ac23bbc"
+dependencies = [
+ "cfg-if",
+ "dirs-sys-next",
+]
+
+[[package]]
+name = "dirs-sys-next"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ebda144c4fe02d1f7ea1a7d9641b6fc6b580adcfa024ae48797ecdeb6825b4d"
+dependencies = [
+ "libc",
+ "redox_users",
+ "winapi",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "flate2"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfe33edd8e85a12a67454e37f8c75e730830d83e313556ab9ebf9ee7fbeb3bfb"
+dependencies = [
+ "crc32fast",
+ "libz-rs-sys",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "gif"
+version = "0.14.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f954a9e9159ec994f73a30a12b96a702dde78f5547bcb561174597924f7d4162"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+
+[[package]]
+name = "image"
+version = "0.25.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6506c6c10786659413faa717ceebcb8f70731c0a60cbae39795fdf114519c1a"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ad4bb2b565bca0645f4d68c5c9af97fba094e9791da685bf83cb5f3ce74acf2"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.177"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2874a2af47a2325c2001a6e6fad9b16a53b802102b528163885171cf92b15976"
+
+[[package]]
+name = "libredox"
+version = "0.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "416f7e718bdb06000964960ffa43b4335ad4012ae8b99060261aa4a8088d5ccb"
+dependencies = [
+ "bitflags",
+ "libc",
+]
+
+[[package]]
+name = "libz-rs-sys"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "840db8cf39d9ec4dd794376f38acc40d0fc65eec2a8f484f7fd375b84602becd"
+dependencies = [
+ "zlib-rs",
+]
+
+[[package]]
+name = "log"
+version = "0.4.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34080505efa8e45a4b816c349525ebe327ceaa8559756f0356cba97ef3bf7432"
+
+[[package]]
+name = "md5"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae960838283323069879657ca3de837e9f7bbb4c7bf6ea7f1b290d5e9476d2e0"
+
+[[package]]
+name = "memchr"
+version = "2.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "moxcms"
+version = "0.7.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80986bbbcf925ebd3be54c26613d861255284584501595cf418320c078945608"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "png"
+version = "0.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97baced388464909d42d89643fe4361939af9b7ce7a31ee32a168f832a70f2a0"
+dependencies = [
+ "bitflags",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pxfm"
+version = "0.1.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3502d6155304a4173a5f2c34b52b7ed0dd085890326cb50fd625fdf39e86b3b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
+[[package]]
+name = "quote"
+version = "1.0.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
+dependencies = [
+ "getrandom",
+ "libredox",
+ "thiserror",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d66dc143e6b11c1eddc06d5c423cfc97062865baf299914ab64caa38182078fe"
+
+[[package]]
+name = "syn"
+version = "2.0.111"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "390cc9a294ab71bdb1aa2e99d13be9c753cd2d7bd6560c77118597410c4d2e87"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
+dependencies = [
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
+dependencies = [
+ "windows-core",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
+dependencies = [
+ "windows-core",
+ "windows-link",
+ "windows-threading",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-numerics"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
+dependencies = [
+ "windows-core",
+ "windows-link",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows_thumbnail"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "base64",
+ "directories-next",
+ "image",
+ "md5",
+ "once_cell",
+ "windows",
+ "windows-core",
+ "zip",
+]
+
+[[package]]
+name = "zip"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb2a05c7c36fde6c09b08576c9f7fb4cda705990f73b58fe011abf7dfb24168b"
+dependencies = [
+ "arbitrary",
+ "crc32fast",
+ "flate2",
+ "indexmap",
+ "memchr",
+ "zopfli",
+]
+
+[[package]]
+name = "zlib-rs"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f06ae92f42f5e5c42443fd094f245eb656abf56dd7cce9b8b263236565e00f2"
+
+[[package]]
+name = "zopfli"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f05cd8797d63865425ff89b5c4a48804f35ba0ce8d125800027ad6017d2b5249"
+dependencies = [
+ "bumpalo",
+ "crc32fast",
+ "log",
+ "simd-adler32",
+]
+
+[[package]]
+name = "zune-core"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "111f7d9820f05fd715df3144e254d6fc02ee4088b0644c0ffd0efc9e6d9d2773"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fb7703e32e9a07fb3f757360338b3a567a5054f21b5f52a666752e333d58e"
+dependencies = [
+ "zune-core",
+]

apps/readest-app/extensions/windows-thumbnail/Cargo.toml

@@ -0,0 +1,31 @@
+[package]
+name = "windows_thumbnail"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[workspace]
+
+[lib]
+name = "windows_thumbnail"
+path = "src/mod.rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+anyhow = "1"
+base64 = "0.22"
+directories-next = "2.0"
+image = { version = "0.25", default-features = false, features = ["png", "jpeg", "gif", "webp"] }
+md5 = "0.8"
+once_cell = "1.19"
+zip = { version = "6.0", default-features = false, features = ["deflate"] }
+windows = { version = "0.62", features = [
+  "Win32_Foundation",
+  "Win32_Graphics_Gdi",
+  "Win32_Security",
+  "Win32_System_Com",
+  "Win32_System_LibraryLoader",
+  "Win32_System_Registry",
+  "Win32_UI_Shell",
+] }
+windows-core = "0.62"

apps/readest-app/extensions/windows-thumbnail/README.md

@@ -0,0 +1,134 @@
+# Windows Thumbnail Provider for Readest
+
+This crate provides Windows Explorer thumbnail support for eBook files when Readest is set as the default application.
+
+## Features
+
+- **Automatic Cover Extraction**: Extracts cover images from EPUB, MOBI, AZW, AZW3, FB2, CBZ, CBR files
+- **Readest Branding**: Adds a small Readest icon overlay at the bottom-right corner
+- **Smart Caching**: Caches generated thumbnails for faster subsequent loads
+- **File Association Aware**: Only shows thumbnails when Readest is the default app for the file type
+- **COM Integration**: Full Windows Shell extension implementation via `IThumbnailProvider`
+
+## Supported Formats
+
+| Format     | Extension               | Cover Source                 |
+| ---------- | ----------------------- | ---------------------------- |
+| EPUB       | `.epub`                 | OPF manifest cover reference |
+| MOBI/AZW   | `.mobi`, `.azw`, `.prc` | EXTH cover offset            |
+| AZW3/KF8   | `.azw3`, `.kf8`         | KF8 format cover             |
+| FB2        | `.fb2`                  | `<binary>` coverpage element |
+| Comic Book | `.cbz`, `.cbr`          | First image in archive       |
+| Plain Text | `.txt`                  | Generated placeholder        |
+
+## Building
+
+### Library Only
+
+```bash
+cargo build --release
+```
+
+### COM DLL (for Windows Explorer integration)
+
+```bash
+cargo build --release --features com
+```
+
+### CLI Tool
+
+```bash
+cargo build --release --features cli
+```
+
+## Installation
+
+The thumbnail provider DLL is automatically registered when Readest is installed via the NSIS installer.
+
+### Manual Registration (for development)
+
+```powershell
+# Register the DLL
+regsvr32 /s target\release\windows_thumbnail.dll
+
+# Unregister the DLL
+regsvr32 /s /u target\release\windows_thumbnail.dll
+
+# Refresh Explorer to see changes
+ie4uinit.exe -show
+```
+
+After registration, you may need to restart Windows Explorer or log out/in for changes to take effect.
+
+## Usage (Development / Manual testing)
+
+For local development and testing, build the Windows DLL (or the library) from the Readest Tauri app folder and register it manually. The legacy CLI test harness used to live in the separate `packages/tauri` workspace, but the thumbnail handler implementation now lives inside Readest's Tauri app.
+
+Build the DLL (for Windows explorer integration):
+
+```powershell
+cd apps/readest-app/src-tauri
+cargo build --release --manifest-path Cargo.toml --features com
+```
+
+The standalone CLI test harness is no longer distributed with the app. To test the thumbnail provider locally, build and register the DLL as shown above and use a small test harness that imports `readestlib`'s thumbnail code or use Explorer after registering the handler.
+
+Manual registration for development (register the generated DLL):
+
+```powershell
+# Register the DLL
+regsvr32 /s target\release\windows_thumbnail.dll
+
+# Unregister the DLL
+regsvr32 /s /u target\release\windows_thumbnail.dll
+
+# Refresh Explorer to see changes
+ie4uinit.exe -show
+```
+
+This generates a thumbnail with the Readest overlay at the specified size.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Windows Explorer                              │
+├─────────────────────────────────────────────────────────────────┤
+│                          │                                       │
+│    IThumbnailProvider ───┼──► ThumbnailProvider                  │
+│                          │         │                             │
+│                          │         ▼                             │
+│                          │    Check File Association             │
+│                          │    (is Readest the default?)          │
+│                          │         │                             │
+│                          │         ▼ (if yes)                    │
+│                          │    Extract Cover Image                │
+│                          │         │                             │
+│                          │         ▼                             │
+│                          │    Add Readest Overlay                │
+│                          │         │                             │
+│                          │         ▼                             │
+│                          │    Return HBITMAP                     │
+│                          │                                       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## COM Details
+
+- **CLSID**: `{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}`
+- **Shell Thumbnail Handler GUID**: `{e357fccd-a995-4576-b01f-234630154e96}`
+- **Threading Model**: Apartment
+
+## How It Works
+
+1. When Windows Explorer needs a thumbnail, it queries the registered shell extension
+2. The COM DLL implements `IInitializeWithItem` to receive the file path
+3. It checks if Readest.exe is the default application for that file type using `AssocQueryStringW`
+4. If Readest is the default, it extracts the cover and generates the thumbnail
+5. If Readest is NOT the default, it returns `S_FALSE` to let Windows use other handlers
+
+This ensures thumbnails only appear for files the user has associated with Readest.
+
+## License
+
+MIT License - See LICENSE file for details.

apps/readest-app/extensions/windows-thumbnail/src/com_provider.rs

@@ -0,0 +1,506 @@
+/// Windows COM Thumbnail Provider for Readest
+///
+/// Implements IThumbnailProvider and IInitializeWithItem for Windows Shell integration.
+/// This allows Windows Explorer to show book covers as thumbnails for eBook files.
+///
+/// **Important**: Thumbnails are only shown when Readest.exe is the default application
+/// for the file type.
+///
+/// ## CLSID: {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}
+use std::cell::UnsafeCell;
+use std::ffi::c_void;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicIsize, AtomicU32, Ordering};
+
+use windows::core::{IUnknown, Interface, GUID, HRESULT, PCWSTR, PWSTR};
+use windows::Win32::Foundation::{
+    CLASS_E_NOAGGREGATION, E_FAIL, E_INVALIDARG, E_NOINTERFACE, HMODULE, S_FALSE, S_OK,
+};
+use windows::Win32::Graphics::Gdi::{
+    CreateDIBSection, BITMAPINFO, BITMAPINFOHEADER, BI_RGB, DIB_RGB_COLORS, HBITMAP,
+};
+use windows::Win32::System::Com::{CoTaskMemFree, IClassFactory, IClassFactory_Impl};
+use windows::Win32::System::LibraryLoader::GetModuleFileNameW;
+use windows::Win32::System::Registry::{
+    RegCloseKey, RegCreateKeyExW, RegDeleteTreeW, RegSetValueExW, HKEY, HKEY_CLASSES_ROOT,
+    KEY_WRITE, REG_OPTION_NON_VOLATILE, REG_SZ,
+};
+use windows::Win32::UI::Shell::{
+    AssocQueryStringW, IInitializeWithItem, IInitializeWithItem_Impl, IShellItem,
+    IThumbnailProvider, IThumbnailProvider_Impl, ASSOCF_NONE, ASSOCSTR_EXECUTABLE,
+    SIGDN_FILESYSPATH, WTSAT_ARGB, WTS_ALPHATYPE,
+};
+use windows_core::BOOL;
+use windows_core::{implement, Ref};
+
+use super::cached_thumbnail_for_path;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLSID for Readest Thumbnail Provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// CLSID: {A1B2C3D4-E5F6-7890-ABCD-EF1234567890}
+pub const CLSID_READEST_THUMBNAIL: GUID = GUID::from_u128(0xA1B2C3D4_E5F6_7890_ABCD_EF1234567890);
+
+/// Supported file extensions
+pub const SUPPORTED_EXTENSIONS: &[&str] = &[
+    ".epub", ".mobi", ".azw", ".azw3", ".kf8", ".prc", ".fb2", ".cbz", ".cbr", ".txt",
+];
+
+// DLL reference counting
+static DLL_REF_COUNT: AtomicU32 = AtomicU32::new(0);
+static DLL_MODULE_PTR: AtomicIsize = AtomicIsize::new(0);
+
+fn dll_add_ref() {
+    DLL_REF_COUNT.fetch_add(1, Ordering::SeqCst);
+}
+fn dll_release() {
+    DLL_REF_COUNT.fetch_sub(1, Ordering::SeqCst);
+}
+
+fn set_dll_module(h: HMODULE) {
+    DLL_MODULE_PTR.store(h.0 as isize, Ordering::SeqCst);
+}
+
+fn get_dll_module() -> Option<HMODULE> {
+    let ptr = DLL_MODULE_PTR.load(Ordering::SeqCst);
+    if ptr == 0 {
+        None
+    } else {
+        Some(HMODULE(ptr as *mut c_void))
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File Association Check
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Check if Readest.exe is the default application for a given file extension.
+fn is_readest_default_for_extension(ext: &str) -> bool {
+    let ext_wide: Vec<u16> = ext.encode_utf16().chain(std::iter::once(0)).collect();
+    let mut buffer = [0u16; 260];
+    let mut buffer_size = buffer.len() as u32;
+
+    unsafe {
+        let result = AssocQueryStringW(
+            ASSOCF_NONE,
+            ASSOCSTR_EXECUTABLE,
+            PCWSTR(ext_wide.as_ptr()),
+            None,
+            Some(PWSTR(buffer.as_mut_ptr())),
+            &mut buffer_size,
+        );
+
+        if result.is_ok() {
+            let len = buffer.iter().position(|&c| c == 0).unwrap_or(buffer.len());
+            let path = String::from_utf16_lossy(&buffer[..len]).to_lowercase();
+            return path.contains("readest");
+        }
+    }
+
+    false
+}
+
+/// Check if Readest is the default app for a specific file path.
+fn is_readest_default_for_file(path: &PathBuf) -> bool {
+    if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
+        let ext_with_dot = format!(".{}", ext.to_lowercase());
+        return is_readest_default_for_extension(&ext_with_dot);
+    }
+    false
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ThumbnailProvider
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Interior mutability wrapper for COM single-threaded apartment
+struct ComCell<T>(UnsafeCell<T>);
+
+impl<T> ComCell<T> {
+    fn new(value: T) -> Self {
+        Self(UnsafeCell::new(value))
+    }
+    fn get(&self) -> &T {
+        unsafe { &*self.0.get() }
+    }
+    fn set(&self, value: T) {
+        unsafe {
+            *self.0.get() = value;
+        }
+    }
+}
+
+// SAFETY: COM thumbnail providers run in single-threaded apartment (STA)
+unsafe impl<T> Sync for ComCell<T> {}
+unsafe impl<T> Send for ComCell<T> {}
+
+#[implement(IThumbnailProvider, IInitializeWithItem)]
+pub struct ThumbnailProvider {
+    file_path: ComCell<Option<PathBuf>>,
+    file_ext: ComCell<Option<String>>,
+    should_provide: ComCell<bool>,
+}
+
+impl ThumbnailProvider {
+    pub fn new() -> Self {
+        dll_add_ref();
+        Self {
+            file_path: ComCell::new(None),
+            file_ext: ComCell::new(None),
+            should_provide: ComCell::new(false),
+        }
+    }
+}
+
+impl Default for ThumbnailProvider {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Drop for ThumbnailProvider {
+    fn drop(&mut self) {
+        dll_release();
+    }
+}
+
+impl IInitializeWithItem_Impl for ThumbnailProvider_Impl {
+    fn Initialize(&self, psi: Ref<'_, IShellItem>, _grfmode: u32) -> windows::core::Result<()> {
+        let item = psi.ok()?;
+
+        unsafe {
+            let path_pwstr = item.GetDisplayName(SIGDN_FILESYSPATH)?;
+
+            let mut len = 0usize;
+            let mut ptr = path_pwstr.0;
+            while *ptr != 0 {
+                len += 1;
+                ptr = ptr.add(1);
+            }
+
+            let slice = std::slice::from_raw_parts(path_pwstr.0, len);
+            let path_str = String::from_utf16_lossy(slice);
+            let path = PathBuf::from(&path_str);
+
+            CoTaskMemFree(Some(path_pwstr.0 as *const c_void));
+
+            let is_default = is_readest_default_for_file(&path);
+            self.should_provide.set(is_default);
+
+            if !is_default {
+                return Ok(());
+            }
+
+            let ext = path
+                .extension()
+                .and_then(|e| e.to_str())
+                .map(|s| s.to_lowercase())
+                .unwrap_or_default();
+
+            self.file_path.set(Some(path));
+            self.file_ext.set(Some(ext));
+        }
+        Ok(())
+    }
+}
+
+impl IThumbnailProvider_Impl for ThumbnailProvider_Impl {
+    fn GetThumbnail(
+        &self,
+        cx: u32,
+        phbmp: *mut HBITMAP,
+        pdwalpha: *mut WTS_ALPHATYPE,
+    ) -> windows::core::Result<()> {
+        if !*self.should_provide.get() {
+            return Err(E_FAIL.into());
+        }
+
+        let path = self.file_path.get().as_ref().ok_or(E_FAIL)?;
+        let ext = self.file_ext.get().as_ref().ok_or(E_FAIL)?;
+
+        let png_bytes = cached_thumbnail_for_path(path, ext, cx).map_err(|_| E_FAIL)?;
+        let img = image::load_from_memory(&png_bytes).map_err(|_| E_FAIL)?;
+        let rgba = img.to_rgba8();
+        let (width, height) = (rgba.width(), rgba.height());
+
+        let bmi = BITMAPINFO {
+            bmiHeader: BITMAPINFOHEADER {
+                biSize: std::mem::size_of::<BITMAPINFOHEADER>() as u32,
+                biWidth: width as i32,
+                biHeight: -(height as i32),
+                biPlanes: 1,
+                biBitCount: 32,
+                biCompression: BI_RGB.0,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+
+        let mut bits: *mut c_void = std::ptr::null_mut();
+
+        unsafe {
+            let hbmp = CreateDIBSection(None, &bmi, DIB_RGB_COLORS, &mut bits, None, 0)
+                .map_err(|_| E_FAIL)?;
+            if bits.is_null() {
+                return Err(E_FAIL.into());
+            }
+
+            // RGBA -> BGRA
+            let dst =
+                std::slice::from_raw_parts_mut(bits as *mut u8, (width * height * 4) as usize);
+            let src = rgba.as_raw();
+            for i in 0..(width * height) as usize {
+                let si = i * 4;
+                dst[si] = src[si + 2]; // B
+                dst[si + 1] = src[si + 1]; // G
+                dst[si + 2] = src[si]; // R
+                dst[si + 3] = src[si + 3]; // A
+            }
+
+            *phbmp = hbmp;
+            *pdwalpha = WTSAT_ARGB;
+        }
+        Ok(())
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ClassFactory
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[implement(IClassFactory)]
+pub struct ThumbnailProviderFactory;
+
+impl ThumbnailProviderFactory {
+    pub fn new() -> Self {
+        dll_add_ref();
+        Self
+    }
+}
+
+impl Default for ThumbnailProviderFactory {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Drop for ThumbnailProviderFactory {
+    fn drop(&mut self) {
+        dll_release();
+    }
+}
+
+impl IClassFactory_Impl for ThumbnailProviderFactory_Impl {
+    fn CreateInstance(
+        &self,
+        punkouter: Ref<'_, IUnknown>,
+        riid: *const GUID,
+        ppvobject: *mut *mut c_void,
+    ) -> windows::core::Result<()> {
+        unsafe {
+            if ppvobject.is_null() {
+                return Err(E_INVALIDARG.into());
+            }
+            *ppvobject = std::ptr::null_mut();
+            if !punkouter.is_null() {
+                return Err(CLASS_E_NOAGGREGATION.into());
+            }
+
+            let provider: IThumbnailProvider = ThumbnailProvider::new().into();
+            provider.query(&*riid, ppvobject).ok()
+        }
+    }
+
+    fn LockServer(&self, flock: BOOL) -> windows::core::Result<()> {
+        if flock.as_bool() {
+            dll_add_ref();
+        } else {
+            dll_release();
+        }
+        Ok(())
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DLL Exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[no_mangle]
+pub extern "system" fn DllMain(hinstance: HMODULE, reason: u32, _reserved: *mut c_void) -> BOOL {
+    const DLL_PROCESS_ATTACH: u32 = 1;
+    if reason == DLL_PROCESS_ATTACH {
+        set_dll_module(hinstance);
+    }
+    BOOL::from(true)
+}
+
+#[no_mangle]
+pub extern "system" fn DllCanUnloadNow() -> HRESULT {
+    if DLL_REF_COUNT.load(Ordering::SeqCst) == 0 {
+        S_OK
+    } else {
+        S_FALSE
+    }
+}
+
+#[no_mangle]
+pub unsafe extern "system" fn DllGetClassObject(
+    rclsid: *const GUID,
+    riid: *const GUID,
+    ppv: *mut *mut c_void,
+) -> HRESULT {
+    if ppv.is_null() || rclsid.is_null() || riid.is_null() {
+        return E_INVALIDARG;
+    }
+    *ppv = std::ptr::null_mut();
+
+    if *rclsid != CLSID_READEST_THUMBNAIL {
+        return E_NOINTERFACE;
+    }
+    if *riid != IClassFactory::IID && *riid != IUnknown::IID {
+        return E_NOINTERFACE;
+    }
+
+    let factory: IClassFactory = ThumbnailProviderFactory::new().into();
+    factory.query(&*riid, ppv)
+}
+
+#[no_mangle]
+pub unsafe extern "system" fn DllRegisterServer() -> HRESULT {
+    match register_server_impl() {
+        Ok(()) => S_OK,
+        Err(e) => e,
+    }
+}
+
+#[no_mangle]
+pub unsafe extern "system" fn DllUnregisterServer() -> HRESULT {
+    let _ = unregister_server_impl();
+    S_OK
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Registry helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn get_dll_path() -> Option<String> {
+    let module = get_dll_module()?;
+    let mut buffer = [0u16; 260];
+    unsafe {
+        let len = GetModuleFileNameW(Some(module), &mut buffer);
+        if len == 0 {
+            None
+        } else {
+            Some(String::from_utf16_lossy(&buffer[..len as usize]))
+        }
+    }
+}
+
+fn clsid_string() -> String {
+    format!(
+        "{{{:08X}-{:04X}-{:04X}-{:02X}{:02X}-{:02X}{:02X}{:02X}{:02X}{:02X}{:02X}}}",
+        CLSID_READEST_THUMBNAIL.data1,
+        CLSID_READEST_THUMBNAIL.data2,
+        CLSID_READEST_THUMBNAIL.data3,
+        CLSID_READEST_THUMBNAIL.data4[0],
+        CLSID_READEST_THUMBNAIL.data4[1],
+        CLSID_READEST_THUMBNAIL.data4[2],
+        CLSID_READEST_THUMBNAIL.data4[3],
+        CLSID_READEST_THUMBNAIL.data4[4],
+        CLSID_READEST_THUMBNAIL.data4[5],
+        CLSID_READEST_THUMBNAIL.data4[6],
+        CLSID_READEST_THUMBNAIL.data4[7]
+    )
+}
+
+fn to_wide(s: &str) -> Vec<u16> {
+    s.encode_utf16().chain(std::iter::once(0)).collect()
+}
+
+unsafe fn set_reg_value(key: HKEY, name: &str, value: &str) -> Result<(), HRESULT> {
+    let name_w = to_wide(name);
+    let value_w = to_wide(value);
+    let bytes: &[u8] = std::slice::from_raw_parts(value_w.as_ptr() as *const u8, value_w.len() * 2);
+    if RegSetValueExW(key, PCWSTR(name_w.as_ptr()), Some(0), REG_SZ, Some(bytes)).is_err() {
+        Err(E_FAIL)
+    } else {
+        Ok(())
+    }
+}
+
+unsafe fn create_reg_key(parent: HKEY, subkey: &str) -> Result<HKEY, HRESULT> {
+    let subkey_w = to_wide(subkey);
+    let mut hkey = HKEY::default();
+    let result = RegCreateKeyExW(
+        parent,
+        PCWSTR(subkey_w.as_ptr()),
+        Some(0),
+        None,
+        REG_OPTION_NON_VOLATILE,
+        KEY_WRITE,
+        None,
+        &mut hkey,
+        None,
+    );
+    if result.is_err() {
+        Err(E_FAIL)
+    } else {
+        Ok(hkey)
+    }
+}
+
+unsafe fn register_server_impl() -> Result<(), HRESULT> {
+    let dll_path = get_dll_path().ok_or(E_FAIL)?;
+    let clsid = clsid_string();
+
+    // CLSID key
+    let clsid_key = create_reg_key(HKEY_CLASSES_ROOT, &format!("CLSID\\{}", clsid))?;
+    set_reg_value(clsid_key, "", "Readest Thumbnail Provider")?;
+
+    // CRITICAL: DisableProcessIsolation = 1
+    let disable_isolation_name = to_wide("DisableProcessIsolation");
+    let value: u32 = 1;
+    let _ = windows::Win32::System::Registry::RegSetValueExW(
+        clsid_key,
+        PCWSTR(disable_isolation_name.as_ptr()),
+        Some(0),
+        windows::Win32::System::Registry::REG_DWORD,
+        Some(std::slice::from_raw_parts(
+            &value as *const u32 as *const u8,
+            4,
+        )),
+    );
+
+    let inproc_key = create_reg_key(clsid_key, "InprocServer32")?;
+    set_reg_value(inproc_key, "", &dll_path)?;
+    set_reg_value(inproc_key, "ThreadingModel", "Apartment")?;
+    let _ = RegCloseKey(inproc_key);
+    let _ = RegCloseKey(clsid_key);
+
+    // Register ShellEx thumbnail handler for each extension
+    for ext in SUPPORTED_EXTENSIONS {
+        let ext_shellex_path =
+            format!("{}\\ShellEx\\{{e357fccd-a995-4576-b01f-234630154e96}}", ext);
+        if let Ok(ext_shellex_key) = create_reg_key(HKEY_CLASSES_ROOT, &ext_shellex_path) {
+            let _ = set_reg_value(ext_shellex_key, "", &clsid);
+            let _ = RegCloseKey(ext_shellex_key);
+        }
+    }
+    Ok(())
+}
+
+unsafe fn unregister_server_impl() -> Result<(), HRESULT> {
+    let clsid = clsid_string();
+    let clsid_path = to_wide(&format!("CLSID\\{}", clsid));
+    let _ = RegDeleteTreeW(HKEY_CLASSES_ROOT, PCWSTR(clsid_path.as_ptr()));
+
+    for ext in SUPPORTED_EXTENSIONS {
+        let ext_path = to_wide(&format!(
+            "{}\\ShellEx\\{{e357fccd-a995-4576-b01f-234630154e96}}",
+            ext
+        ));
+        let _ = RegDeleteTreeW(HKEY_CLASSES_ROOT, PCWSTR(ext_path.as_ptr()));
+    }
+    Ok(())
+}

apps/readest-app/extensions/windows-thumbnail/src/extraction.rs

@@ -0,0 +1,648 @@
+/// Cover image extraction for various eBook formats
+///
+/// Supports: EPUB, MOBI/AZW3/KF8, FB2, CBZ/CBR, TXT
+use anyhow::{anyhow, Result};
+use base64::engine::general_purpose;
+use base64::Engine as _;
+use directories_next::ProjectDirs;
+use image::{imageops, DynamicImage, Rgba};
+use md5::Context;
+use once_cell::sync::Lazy;
+use std::io::{Cursor, Read, Seek, SeekFrom};
+use std::path::Path;
+use zip::ZipArchive;
+
+/// Thumbnail cache directory (per-user)
+static CACHE_DIR: Lazy<Option<std::path::PathBuf>> = Lazy::new(|| {
+    ProjectDirs::from("app", "Readest", "").map(|pd| {
+        let dir = pd.cache_dir().join("thumbnails");
+        let _ = std::fs::create_dir_all(&dir);
+        dir
+    })
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EPUB extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Extract cover image bytes from an EPUB file.
+pub fn extract_epub_cover_bytes<R: Read + Seek>(reader: R) -> Result<Vec<u8>> {
+    let mut archive = ZipArchive::new(reader)?;
+
+    // Pass 1: Look for files with "cover" in the name
+    let mut candidates: Vec<(usize, String, u64)> = Vec::new();
+    for i in 0..archive.len() {
+        let file = archive.by_index(i)?;
+        let name = file.name().to_lowercase();
+        let size = file.size();
+        drop(file);
+
+        if is_image_extension(&name) && (name.contains("cover") || name.contains("front")) {
+            candidates.push((i, name, size));
+        }
+    }
+
+    // Sort by priority: exact "cover" match first, then by size
+    if !candidates.is_empty() {
+        candidates.sort_by(|a, b| {
+            let a_exact = a.1.contains("cover.") || a.1.ends_with("cover");
+            let b_exact = b.1.contains("cover.") || b.1.ends_with("cover");
+            match (a_exact, b_exact) {
+                (true, false) => std::cmp::Ordering::Less,
+                (false, true) => std::cmp::Ordering::Greater,
+                _ => b.2.cmp(&a.2),
+            }
+        });
+
+        let idx = candidates[0].0;
+        let mut file = archive.by_index(idx)?;
+        let mut buf = Vec::new();
+        file.read_to_end(&mut buf)?;
+        return Ok(buf);
+    }
+
+    // Pass 2: Parse container.xml to find OPF, then parse OPF for cover
+    let container_xml = read_zip_file_to_string(&mut archive, "META-INF/container.xml");
+    if let Ok(xml) = container_xml {
+        if let Some(rootfile) = extract_attribute(&xml, "rootfile", "full-path") {
+            let opf_content = read_zip_file_to_string(&mut archive, &rootfile);
+            if let Ok(opf) = opf_content {
+                if let Some(cover_id) = find_cover_id_in_opf(&opf) {
+                    if let Some(href) = find_href_by_id_in_opf(&opf, &cover_id) {
+                        let base = Path::new(&rootfile).parent().unwrap_or(Path::new(""));
+                        let cover_path = base.join(&href).to_string_lossy().replace('\\', "/");
+                        if let Ok(bytes) = read_zip_file_to_bytes(&mut archive, &cover_path) {
+                            return Ok(bytes);
+                        }
+                    }
+                }
+                if let Some(href) = find_first_image_in_manifest(&opf) {
+                    let base = Path::new(&rootfile).parent().unwrap_or(Path::new(""));
+                    let cover_path = base.join(&href).to_string_lossy().replace('\\', "/");
+                    if let Ok(bytes) = read_zip_file_to_bytes(&mut archive, &cover_path) {
+                        return Ok(bytes);
+                    }
+                }
+            }
+        }
+    }
+
+    // Pass 3: Just grab the largest image file
+    let mut largest: Option<(usize, u64)> = None;
+    for i in 0..archive.len() {
+        let file = archive.by_index(i)?;
+        let name = file.name().to_lowercase();
+        let size = file.size();
+        drop(file);
+
+        if is_image_extension(&name) && (largest.is_none() || size > largest.unwrap().1) {
+            largest = Some((i, size));
+        }
+    }
+
+    if let Some((idx, _)) = largest {
+        let mut file = archive.by_index(idx)?;
+        let mut buf = Vec::new();
+        file.read_to_end(&mut buf)?;
+        return Ok(buf);
+    }
+
+    Err(anyhow!("No cover image found in EPUB"))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MOBI/AZW3/KF8 extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Extract cover image from MOBI/AZW3/KF8 files.
+pub fn extract_mobi_cover_bytes<R: Read + Seek>(mut reader: R) -> Result<Vec<u8>> {
+    let mut header = [0u8; 78];
+    reader.read_exact(&mut header)?;
+
+    if &header[60..68] != b"BOOKMOBI" {
+        return Err(anyhow!("Not a valid MOBI file"));
+    }
+
+    let num_records = u16::from_be_bytes([header[76], header[77]]) as usize;
+
+    let mut record_offsets: Vec<u32> = Vec::with_capacity(num_records);
+    for _ in 0..num_records {
+        let mut rec = [0u8; 8];
+        reader.read_exact(&mut rec)?;
+        record_offsets.push(u32::from_be_bytes([rec[0], rec[1], rec[2], rec[3]]));
+    }
+
+    if record_offsets.is_empty() {
+        return Err(anyhow!("No records in MOBI file"));
+    }
+
+    reader.seek(SeekFrom::Start(record_offsets[0] as u64))?;
+    let mut mobi_header = [0u8; 256];
+    reader.read_exact(&mut mobi_header)?;
+
+    if &mobi_header[16..20] != b"MOBI" {
+        return Err(anyhow!("Invalid MOBI header"));
+    }
+
+    let header_length = u32::from_be_bytes([
+        mobi_header[20],
+        mobi_header[21],
+        mobi_header[22],
+        mobi_header[23],
+    ]) as usize;
+
+    let exth_flags = u32::from_be_bytes([
+        mobi_header[128],
+        mobi_header[129],
+        mobi_header[130],
+        mobi_header[131],
+    ]);
+    if exth_flags & 0x40 == 0 {
+        return Err(anyhow!("No EXTH header in MOBI file"));
+    }
+
+    let exth_offset = record_offsets[0] as u64 + 16 + header_length as u64;
+    reader.seek(SeekFrom::Start(exth_offset))?;
+
+    let mut exth_magic = [0u8; 4];
+    reader.read_exact(&mut exth_magic)?;
+    if &exth_magic != b"EXTH" {
+        return Err(anyhow!("EXTH header not found"));
+    }
+
+    let mut exth_len_bytes = [0u8; 4];
+    reader.read_exact(&mut exth_len_bytes)?;
+
+    let mut exth_count_bytes = [0u8; 4];
+    reader.read_exact(&mut exth_count_bytes)?;
+    let exth_count = u32::from_be_bytes(exth_count_bytes) as usize;
+
+    let mut cover_offset: Option<u32> = None;
+    let first_img_idx = u32::from_be_bytes([
+        mobi_header[108],
+        mobi_header[109],
+        mobi_header[110],
+        mobi_header[111],
+    ]);
+
+    for _ in 0..exth_count {
+        let mut rec_header = [0u8; 8];
+        if reader.read_exact(&mut rec_header).is_err() {
+            break;
+        }
+        let rec_type =
+            u32::from_be_bytes([rec_header[0], rec_header[1], rec_header[2], rec_header[3]]);
+        let rec_len =
+            u32::from_be_bytes([rec_header[4], rec_header[5], rec_header[6], rec_header[7]])
+                as usize;
+
+        let data_len = rec_len.saturating_sub(8);
+        let mut data = vec![0u8; data_len];
+        if reader.read_exact(&mut data).is_err() {
+            break;
+        }
+
+        if rec_type == 201 && data_len >= 4 {
+            cover_offset = Some(u32::from_be_bytes([data[0], data[1], data[2], data[3]]));
+        }
+    }
+
+    let cover_record_idx = if let Some(offset) = cover_offset {
+        first_img_idx + offset
+    } else {
+        first_img_idx
+    };
+
+    if cover_record_idx as usize >= record_offsets.len() {
+        return Err(anyhow!("Cover record index out of bounds"));
+    }
+
+    let start = record_offsets[cover_record_idx as usize] as u64;
+    let end = if (cover_record_idx as usize + 1) < record_offsets.len() {
+        record_offsets[cover_record_idx as usize + 1] as u64
+    } else {
+        reader.seek(SeekFrom::End(0))?;
+        reader.stream_position()?
+    };
+
+    let len = (end - start) as usize;
+    reader.seek(SeekFrom::Start(start))?;
+    let mut cover_data = vec![0u8; len];
+    reader.read_exact(&mut cover_data)?;
+
+    if cover_data.starts_with(&[0xFF, 0xD8, 0xFF])
+        || cover_data.starts_with(&[0x89, 0x50, 0x4E, 0x47])
+        || cover_data.starts_with(b"GIF")
+    {
+        return Ok(cover_data);
+    }
+
+    Err(anyhow!("No valid cover image found in MOBI"))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CBZ extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Extract cover image from CBZ (comic book ZIP) file.
+pub fn extract_cbz_cover_bytes<R: Read + Seek>(reader: R) -> Result<Vec<u8>> {
+    let mut archive = ZipArchive::new(reader)?;
+
+    let mut images: Vec<(usize, String)> = Vec::new();
+    for i in 0..archive.len() {
+        let file = archive.by_index(i)?;
+        let name = file.name().to_string();
+        drop(file);
+
+        if is_image_extension(&name.to_lowercase()) {
+            images.push((i, name));
+        }
+    }
+
+    images.sort_by(|a, b| a.1.cmp(&b.1));
+
+    if let Some((idx, _)) = images.first() {
+        let mut file = archive.by_index(*idx)?;
+        let mut buf = Vec::new();
+        file.read_to_end(&mut buf)?;
+        return Ok(buf);
+    }
+
+    Err(anyhow!("No images found in CBZ"))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FB2 extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Extract cover image from FB2 (FictionBook) file.
+pub fn extract_fb2_cover_bytes<R: Read>(mut reader: R) -> Result<Vec<u8>> {
+    let mut content = String::new();
+    reader.read_to_string(&mut content)?;
+
+    let cover_id = if let Some(start) = content.find("<coverpage>") {
+        let end = content[start..].find("</coverpage>").unwrap_or(500);
+        let coverpage = &content[start..start + end];
+        if let Some(href_pos) = coverpage.find("href=\"#") {
+            let id_start = href_pos + 7;
+            let id_end = coverpage[id_start..].find('"').unwrap_or(50);
+            Some(coverpage[id_start..id_start + id_end].to_string())
+        } else if let Some(href_pos) = coverpage.find("l:href=\"#") {
+            let id_start = href_pos + 9;
+            let id_end = coverpage[id_start..].find('"').unwrap_or(50);
+            Some(coverpage[id_start..id_start + id_end].to_string())
+        } else {
+            None
+        }
+    } else {
+        None
+    };
+
+    let search_pattern = if let Some(ref id) = cover_id {
+        format!("<binary id=\"{}\"", id)
+    } else {
+        "<binary".to_string()
+    };
+
+    if let Some(pos) = content.find(&search_pattern) {
+        if let Some(tag_end) = content[pos..].find('>') {
+            let data_start = pos + tag_end + 1;
+            if let Some(data_end) = content[data_start..].find("</binary>") {
+                let b64_data = content[data_start..data_start + data_end].trim();
+                let b64_clean: String = b64_data.chars().filter(|c| !c.is_whitespace()).collect();
+                let bytes = general_purpose::STANDARD.decode(&b64_clean)?;
+                return Ok(bytes);
+            }
+        }
+    }
+
+    if cover_id.is_some() {
+        if let Some(pos) = content.find("<binary") {
+            if let Some(tag_end) = content[pos..].find('>') {
+                let data_start = pos + tag_end + 1;
+                if let Some(data_end) = content[data_start..].find("</binary>") {
+                    let b64_data = content[data_start..data_start + data_end].trim();
+                    let b64_clean: String =
+                        b64_data.chars().filter(|c| !c.is_whitespace()).collect();
+                    let bytes = general_purpose::STANDARD.decode(&b64_clean)?;
+                    return Ok(bytes);
+                }
+            }
+        }
+    }
+
+    Err(anyhow!("No cover image found in FB2"))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TXT "cover" (placeholder)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Generate a placeholder thumbnail for TXT files.
+pub fn extract_txt_cover_bytes<R: Read>(mut reader: R, size: u32) -> Result<Vec<u8>> {
+    let mut buf = vec![0u8; 4096];
+    let _n = reader.read(&mut buf)?;
+
+    let mut img = image::RgbaImage::from_pixel(size, size, Rgba([245, 245, 245, 255]));
+
+    for x in 0..size {
+        img.put_pixel(x, 0, Rgba([200, 200, 200, 255]));
+        img.put_pixel(x, size - 1, Rgba([200, 200, 200, 255]));
+    }
+    for y in 0..size {
+        img.put_pixel(0, y, Rgba([200, 200, 200, 255]));
+        img.put_pixel(size - 1, y, Rgba([200, 200, 200, 255]));
+    }
+
+    let mut out = Vec::new();
+    DynamicImage::ImageRgba8(img).write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)?;
+    Ok(out)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Unified extraction by extension
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Extract cover image bytes based on file extension.
+pub fn extract_cover_bytes_by_ext(path: &Path, ext: &str) -> Result<Vec<u8>> {
+    let file = std::fs::File::open(path)?;
+    match ext.to_lowercase().as_str() {
+        "epub" => extract_epub_cover_bytes(file),
+        "mobi" | "azw" | "azw3" | "kf8" | "prc" => extract_mobi_cover_bytes(file),
+        "cbz" | "cbr" => extract_cbz_cover_bytes(file),
+        "fb2" => extract_fb2_cover_bytes(file),
+        "txt" => extract_txt_cover_bytes(file, 256),
+        _ => Err(anyhow!("Unsupported format: {}", ext)),
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Thumbnail creation with overlay
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Create a thumbnail from cover image bytes with Readest icon overlay.
+pub fn create_thumbnail_with_overlay(cover_bytes: &[u8], requested_size: u32) -> Result<Vec<u8>> {
+    let img = image::load_from_memory(cover_bytes)?;
+    let thumbnail = img.thumbnail(requested_size, requested_size);
+
+    let overlay_img = load_overlay_icon();
+
+    let mut base = thumbnail.to_rgba8();
+    let (base_w, base_h) = (base.width(), base.height());
+
+    if let Some(ov) = overlay_img {
+        let overlay_size = (requested_size / 5).clamp(24, 48);
+        let ov_resized = ov.resize(overlay_size, overlay_size, imageops::FilterType::Lanczos3);
+        let ovb = ov_resized.to_rgba8();
+        let (ov_w, ov_h) = (ovb.width(), ovb.height());
+
+        let x = base_w.saturating_sub(ov_w + 4);
+        let y = base_h.saturating_sub(ov_h + 4);
+
+        for oy in 0..ov_h {
+            for ox in 0..ov_w {
+                let dst_x = x + ox;
+                let dst_y = y + oy;
+
+                if dst_x < base_w && dst_y < base_h {
+                    let src_pixel = ovb.get_pixel(ox, oy);
+                    let alpha = src_pixel.0[3] as f32 / 255.0;
+
+                    if alpha > 0.0 {
+                        let dst_pixel = base.get_pixel(dst_x, dst_y);
+                        let mut result = dst_pixel.0;
+
+                        for c in 0..3 {
+                            let fg = src_pixel.0[c] as f32;
+                            let bg = result[c] as f32;
+                            result[c] = (fg * alpha + bg * (1.0 - alpha)) as u8;
+                        }
+                        result[3] = 255;
+
+                        base.put_pixel(dst_x, dst_y, Rgba(result));
+                    }
+                }
+            }
+        }
+    }
+
+    let mut out = Vec::new();
+    DynamicImage::ImageRgba8(base).write_to(&mut Cursor::new(&mut out), image::ImageFormat::Png)?;
+    Ok(out)
+}
+
+/// Load the Readest overlay icon.
+fn load_overlay_icon() -> Option<DynamicImage> {
+    // Try embedded icon
+    let icon_bytes = include_bytes!("../../../public/icon.png");
+    if let Ok(img) = image::load_from_memory(icon_bytes) {
+        return Some(img);
+    }
+
+    // Fallback: try loading from filesystem
+    if let Ok(exe) = std::env::current_exe() {
+        let candidates = [
+            exe.parent().map(|p| p.join("icon.png")),
+            exe.parent().map(|p| p.join("resources").join("icon.png")),
+            exe.parent()
+                .and_then(|p| p.parent())
+                .map(|p| p.join("resources").join("icon.png")),
+        ];
+
+        for candidate in candidates.into_iter().flatten() {
+            if candidate.exists() {
+                if let Ok(bytes) = std::fs::read(&candidate) {
+                    if let Ok(img) = image::load_from_memory(&bytes) {
+                        return Some(img);
+                    }
+                }
+            }
+        }
+    }
+
+    None
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Caching
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// Generate a thumbnail with disk caching.
+pub fn cached_thumbnail_for_path(path: &Path, ext: &str, size: u32) -> Result<Vec<u8>> {
+    // Compute cache key by hashing file parts for stability without loading entire file
+    let mut hasher = Context::new();
+    hasher.consume(ext.as_bytes());
+    hasher.consume(&size.to_le_bytes());
+
+    let file = std::fs::File::open(path)?;
+    let metadata = file.metadata()?;
+    let file_len = metadata.len();
+
+    // Read partial chunks like the TypeScript partialMD5 implementation
+    const STEP: u64 = 1024;
+    const SIZE: u64 = 1024;
+    let mut file = file;
+
+    for i in -1i32..=10 {
+        let pos = if i == -1 {
+            256u64
+        } else {
+            STEP << (2 * i as u32)
+        };
+        let start = pos.min(file_len);
+        let end = (start + SIZE).min(file_len);
+
+        if start >= file_len {
+            break;
+        }
+
+        file.seek(SeekFrom::Start(start))?;
+        let mut buf = vec![0u8; (end - start) as usize];
+        file.read_exact(&mut buf)?;
+        hasher.consume(&buf);
+    }
+
+    let digest = hasher.finalize();
+    let key = format!("{:x}.png", digest);
+
+    if let Some(ref dir) = *CACHE_DIR {
+        let cache_path = dir.join(&key);
+        if cache_path.exists() {
+            if let Ok(cached) = std::fs::read(&cache_path) {
+                return Ok(cached);
+            }
+        }
+    }
+
+    let cover = extract_cover_bytes_by_ext(path, ext)?;
+    let thumbnail = create_thumbnail_with_overlay(&cover, size)?;
+
+    if let Some(ref dir) = *CACHE_DIR {
+        let cache_path = dir.join(&key);
+        let _ = std::fs::write(&cache_path, &thumbnail);
+    }
+
+    Ok(thumbnail)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn is_image_extension(name: &str) -> bool {
+    name.ends_with(".jpg")
+        || name.ends_with(".jpeg")
+        || name.ends_with(".png")
+        || name.ends_with(".gif")
+        || name.ends_with(".webp")
+        || name.ends_with(".bmp")
+}
+
+fn read_zip_file_to_string<R: Read + Seek>(
+    archive: &mut ZipArchive<R>,
+    name: &str,
+) -> Result<String> {
+    let mut file = archive.by_name(name)?;
+    let mut content = String::new();
+    file.read_to_string(&mut content)?;
+    Ok(content)
+}
+
+fn read_zip_file_to_bytes<R: Read + Seek>(
+    archive: &mut ZipArchive<R>,
+    name: &str,
+) -> Result<Vec<u8>> {
+    let mut file = archive.by_name(name)?;
+    let mut buf = Vec::new();
+    file.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+
+fn extract_attribute(xml: &str, tag: &str, attr: &str) -> Option<String> {
+    let pattern = format!("<{}", tag);
+    if let Some(tag_pos) = xml.find(&pattern) {
+        let tag_end = xml[tag_pos..].find('>').unwrap_or(500) + tag_pos;
+        let tag_content = &xml[tag_pos..tag_end];
+
+        let attr_pattern = format!("{}=\"", attr);
+        if let Some(attr_pos) = tag_content.find(&attr_pattern) {
+            let value_start = attr_pos + attr_pattern.len();
+            if let Some(value_end) = tag_content[value_start..].find('"') {
+                return Some(tag_content[value_start..value_start + value_end].to_string());
+            }
+        }
+    }
+    None
+}
+
+fn find_cover_id_in_opf(opf: &str) -> Option<String> {
+    if let Some(pos) = opf.find("name=\"cover\"") {
+        let window_start = pos.saturating_sub(50);
+        let window_end = (pos + 100).min(opf.len());
+        let window = &opf[window_start..window_end];
+
+        if let Some(content_pos) = window.find("content=\"") {
+            let start = content_pos + 9;
+            if let Some(end) = window[start..].find('"') {
+                return Some(window[start..start + end].to_string());
+            }
+        }
+    }
+
+    if let Some(pos) = opf.find("properties=\"cover-image\"") {
+        let window_start = pos.saturating_sub(200);
+        let window_end = pos;
+        let window = &opf[window_start..window_end];
+
+        if let Some(id_pos) = window.rfind("id=\"") {
+            let start = id_pos + 4;
+            if let Some(end) = window[start..].find('"') {
+                return Some(window[start..start + end].to_string());
+            }
+        }
+    }
+
+    None
+}
+
+fn find_href_by_id_in_opf(opf: &str, id: &str) -> Option<String> {
+    let pattern = format!("id=\"{}\"", id);
+    if let Some(pos) = opf.find(&pattern) {
+        let window_start = pos.saturating_sub(10);
+        let window_end = (pos + 200).min(opf.len());
+        let window = &opf[window_start..window_end];
+
+        if let Some(href_pos) = window.find("href=\"") {
+            let start = href_pos + 6;
+            if let Some(end) = window[start..].find('"') {
+                return Some(window[start..start + end].to_string());
+            }
+        }
+    }
+    None
+}
+
+fn find_first_image_in_manifest(opf: &str) -> Option<String> {
+    let manifest_start = opf.find("<manifest")?;
+    let manifest_end = opf[manifest_start..]
+        .find("</manifest>")
+        .map(|e| manifest_start + e)?;
+    let manifest = &opf[manifest_start..manifest_end];
+
+    for media_type in ["image/jpeg", "image/png", "image/gif", "image/webp"] {
+        let pattern = format!("media-type=\"{}\"", media_type);
+        if let Some(pos) = manifest.find(&pattern) {
+            let window_start = pos.saturating_sub(200);
+            let window = &manifest[window_start..pos];
+
+            if let Some(href_pos) = window.rfind("href=\"") {
+                let start = href_pos + 6;
+                if let Some(end) = window[start..].find('"') {
+                    return Some(window[start..start + end].to_string());
+                }
+            }
+        }
+    }
+
+    None
+}

apps/readest-app/extensions/windows-thumbnail/src/mod.rs

@@ -0,0 +1,13 @@
+//! Windows Thumbnail Provider for Readest
+//!
+//! This module provides Windows Explorer thumbnail support for eBook files.
+//! Thumbnails are only shown when Readest is set as the default application.
+//!
+//! Supported formats: EPUB, MOBI, AZW, AZW3, KF8, FB2, CBZ, CBR
+
+#![allow(non_snake_case)]
+
+mod com_provider;
+mod extraction;
+
+pub use extraction::*;

apps/readest-app/i18n-langs.json

@@ -0,0 +1,35 @@
+[
+  "de",
+  "ja",
+  "es",
+  "fa",
+  "fr",
+  "it",
+  "el",
+  "ko",
+  "uk",
+  "nl",
+  "sl",
+  "sv",
+  "pl",
+  "pt",
+  "ru",
+  "tr",
+  "hi",
+  "id",
+  "vi",
+  "ms",
+  "he",
+  "ar",
+  "th",
+  "bo",
+  "bn",
+  "ta",
+  "si",
+  "ro",
+  "hu",
+  "uz",
+  "pt-BR",
+  "zh-CN",
+  "zh-TW"
+]

apps/readest-app/i18next-scanner.config.cjs

@@ -0,0 +1,35 @@
+const lngs = require('./i18n-langs.json');
+
+const options = {
+  debug: false,
+  sort: false,
+  func: {
+    list: ['_'],
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  lngs,
+  ns: ['translation'],
+  defaultNs: 'translation',
+  defaultValue: '__STRING_NOT_TRANSLATED__',
+  resource: {
+    loadPath: './public/locales/{{lng}}/{{ns}}.json',
+    savePath: './public/locales/{{lng}}/{{ns}}.json',
+    jsonIndent: 2,
+    lineEnding: '\n',
+  },
+  keySeparator: false,
+  nsSeparator: false,
+  interpolation: {
+    prefix: '{{',
+    suffix: '}}',
+  },
+  metadata: {},
+  allowDynamicKeys: true,
+  removeUnusedKeys: true,
+};
+
+module.exports = {
+  input: ['src/**/*.{js,jsx,ts,tsx}', '!src/**/*.test.{js,jsx,ts,tsx}'],
+  output: '.',
+  options,
+};

apps/readest-app/i18next-scanner.config.js

@@ -1,53 +0,0 @@
-module.exports = {
-  input: ['src/**/*.{js,jsx,ts,tsx}', '!src/**/*.test.{js,jsx,ts,tsx}'],
-  output: '.',
-  options: {
-    debug: false,
-    sort: false,
-    func: {
-      list: ['_'],
-      extensions: ['.js', '.jsx', '.ts', '.tsx'],
-    },
-    lngs: [
-      'de',
-      'ja',
-      'es',
-      'fr',
-      'it',
-      'el',
-      'ko',
-      'uk',
-      'nl',
-      'pl',
-      'pt',
-      'ru',
-      'tr',
-      'hi',
-      'id',
-      'vi',
-      'ar',
-      'th',
-      'bo',
-      'zh-CN',
-      'zh-TW',
-    ],
-    ns: ['translation'],
-    defaultNs: 'translation',
-    defaultValue: '__STRING_NOT_TRANSLATED__',
-    resource: {
-      loadPath: './public/locales/{{lng}}/{{ns}}.json',
-      savePath: './public/locales/{{lng}}/{{ns}}.json',
-      jsonIndent: 2,
-      lineEnding: '\n',
-    },
-    keySeparator: false,
-    nsSeparator: false,
-    interpolation: {
-      prefix: '{{',
-      suffix: '}}',
-    },
-    metadata: {},
-    allowDynamicKeys: true,
-    removeUnusedKeys: true,
-  },
-};

apps/readest-app/next.config.mjs

@@ -1,5 +1,9 @@
-import withPWAInit from '@ducanh2912/next-pwa';
+import withSerwistInit from '@serwist/next';
 import withBundleAnalyzer from '@next/bundle-analyzer';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const isDev = process.env['NODE_ENV'] === 'development';
 const appPlatform = process.env['NEXT_PUBLIC_APP_PLATFORM'];
@@ -27,18 +31,65 @@ const nextConfig = {
   assetPrefix: '',
   reactStrictMode: true,
   serverExternalPackages: ['isows'],
-  transpilePackages: !isDev
-    ? [
-        'i18next-browser-languagedetector',
-        'react-i18next',
-        'i18next',
-        '@ducanh2912/next-pwa',
-        '@tauri-apps',
-        'highlight.js',
-        'foliate-js',
-        'marked',
-      ]
-    : [],
+  allowedDevOrigins: ['192.168.2.120'],
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      nunjucks: 'nunjucks/browser/nunjucks.js',
+      // `js-mdict` is consumed as TS source via tsconfig paths from
+      // `packages/js-mdict/src/`; its sources `import 'fflate'` directly.
+      // Without an alias, webpack walks up from that source location and
+      // can't find fflate (only installed in this app's node_modules).
+      fflate: path.resolve(__dirname, 'node_modules/fflate'),
+      ...(appPlatform !== 'web' ? { '@tursodatabase/database-wasm': false } : {}),
+    };
+    return config;
+  },
+  turbopack: {
+    resolveAlias: {
+      nunjucks: 'nunjucks/browser/nunjucks.js',
+      // Turbopack rejects absolute paths in resolveAlias ("server relative
+      // imports not implemented") — use a project-relative path.
+      fflate: './node_modules/fflate',
+      ...(appPlatform !== 'web' ? { '@tursodatabase/database-wasm': './src/utils/stub.ts' } : {}),
+    },
+  },
+  transpilePackages: [
+    'ai',
+    'ai-sdk-ollama',
+    '@ai-sdk/react',
+    '@assistant-ui/react',
+    '@assistant-ui/react-ai-sdk',
+    '@assistant-ui/react-markdown',
+    'streamdown',
+    ...(isDev
+      ? []
+      : [
+          'i18next-browser-languagedetector',
+          'react-i18next',
+          'i18next',
+          '@tauri-apps',
+          'highlight.js',
+          'foliate-js',
+          'marked',
+        ]),
+  ],
+  async rewrites() {
+    return [
+      {
+        source: '/reader/:ids',
+        destination: '/reader?ids=:ids',
+      },
+      {
+        source: '/o/book/:hash/annotation/:id',
+        destination: '/o?book=:hash&note=:id',
+      },
+      {
+        source: '/s/:token',
+        destination: '/s?token=:token',
+      },
+    ];
+  },
   async headers() {
     return [
       {
@@ -50,24 +101,34 @@ const nextConfig = {
           },
         ],
       },
+      {
+        source: '/_next/static/:path*',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: isDev
+              ? 'public, max-age=0, must-revalidate'
+              : 'public, max-age=31536000, immutable',
+          },
+        ],
+      },
     ];
   },
 };
 
-const withPWA = withPWAInit({
-  dest: 'public',
-  disable: isDev || appPlatform !== 'web',
-  cacheOnFrontEndNav: true,
-  aggressiveFrontEndNavCaching: true,
-  reloadOnOnline: true,
-  swcMinify: true,
-  fallbacks: {
-    document: '/offline',
-  },
-  workboxOptions: {
-    disableDevLogs: true,
-  },
-});
+const pwaDisabled = isDev || appPlatform !== 'web';
+
+const withPWA = pwaDisabled
+  ? (config) => config
+  : withSerwistInit({
+      swSrc: 'src/sw.ts',
+      swDest: 'public/sw.js',
+      cacheOnNavigation: true,
+      reloadOnOnline: true,
+      disable: false,
+      register: true,
+      scope: '/',
+    });
 
 const withAnalyzer = withBundleAnalyzer({
   enabled: process.env.ANALYZE === 'true',

apps/readest-app/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@readest/readest-app",
-  "version": "0.9.75",
+  "version": "0.11.1",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "dotenv -e .env.tauri -- next dev",
     "build": "dotenv -e .env.tauri -- next build",
@@ -9,18 +10,45 @@
     "dev-web": "dotenv -e .env.web -- next dev",
     "build-web": "dotenv -e .env.web -- next build",
     "start-web": "dotenv -e .env.web -- next start",
-    "i18n:extract": "i18next-scanner",
-    "lint": "next lint",
-    "test": "dotenv -e .env -e .env.test.local vitest",
+    "dev-web:vinext": "dotenv -e .env.web -- vinext dev",
+    "build-web:vinext": "dotenv -e .env.web -- vinext build",
+    "start-web:vinext": "dotenv -e .env.web -- vinext start",
+    "build-tauri": "dotenv -e .env.tauri -- next build",
+    "dev-android": "tauri android build -t aarch64 -- --features devtools && adb install -r src-tauri/gen/android/app/build/outputs/apk/universal/release/app-universal-release.apk",
+    "dev-ios": "tauri ios build -- --features devtools && ideviceinstaller -i src-tauri/gen/apple/build/arm64/Readest.ipa",
+    "i18n:extract": "i18next-scanner --config i18next-scanner.config.cjs",
+    "lint": "tsgo --noEmit && biome check . && pnpm lint:lua",
+    "lint:lua": "node ../readest.koplugin/scripts/lint-koplugin.mjs",
+    "test:lua": "node ../readest.koplugin/scripts/test-koplugin.mjs",
+    "test": "dotenv -e .env -e .env.test.local -- vitest",
+    "test:coverage": "dotenv -e .env -e .env.test.local -- vitest run --coverage",
+    "test:browser": "dotenv -e .env -e .env.test.local -- vitest run --config vitest.browser.config.mts",
+    "test:tauri": "bash scripts/test-tauri.sh",
+    "test:pr:web": "pnpm test -- --watch=false && pnpm test:browser",
+    "test:pr:tauri": "bash scripts/test-tauri.sh",
+    "test:all": "pnpm test -- --watch=false && pnpm test:browser && bash scripts/test-tauri.sh",
+    "test:e2e": "wdio run wdio.conf.ts",
+    "tauri:dev:test": "dotenv -e .env.tauri -- tauri dev --features webdriver",
+    "tauri:build:test": "dotenv -e .env.tauri -- tauri build --debug --features webdriver",
     "tauri": "tauri",
-    "prepare-public-vendor": "mkdirp ./public/vendor/pdfjs",
-    "copy-pdfjs-js": "cpx \"../../packages/foliate-js/node_modules/pdfjs-dist/legacy/build/{pdf.worker.min.mjs,pdf.mjs,pdf.d.mts}\" ./public/vendor/pdfjs",
+    "fmt:check": "cargo fmt -p Readest --check",
+    "clippy:check": "cargo clippy -p Readest --no-deps -- -D warnings",
+    "format": "pnpm -w format",
+    "format:check": "pnpm -w format:check",
+    "prepare-public-vendor": "mkdirp ./public/vendor/pdfjs ./public/vendor/simplecc ./public/vendor/jieba",
+    "copy-pdfjs-js": "cpx \"../../packages/foliate-js/node_modules/pdfjs-dist/legacy/build/{pdf.worker.min.mjs,pdf.min.mjs,pdf.d.mts}\" ./public/vendor/pdfjs",
+    "copy-pdfjs-wasm": "cpx \"../../packages/foliate-js/node_modules/pdfjs-dist/wasm/{openjpeg.wasm,qcms_bg.wasm}\" ./public/vendor/pdfjs",
     "copy-pdfjs-fonts": "cpx \"../../packages/foliate-js/node_modules/pdfjs-dist/{cmaps,standard_fonts}/*\" ./public/vendor/pdfjs",
     "copy-flatten-pdfjs-annotation-layer-css": "npx postcss \"../../packages/foliate-js/vendor/pdfjs/annotation_layer_builder.css\" --no-map -u postcss-nested > ./public/vendor/pdfjs/annotation_layer_builder.css",
     "copy-flatten-pdfjs-text-layer-css": "npx postcss \"../../packages/foliate-js/vendor/pdfjs/text_layer_builder.css\" --no-map -u postcss-nested > ./public/vendor/pdfjs/text_layer_builder.css",
     "copy-flatten-pdfjs-css": "pnpm copy-flatten-pdfjs-annotation-layer-css && pnpm copy-flatten-pdfjs-text-layer-css",
-    "copy-pdfjs": "pnpm copy-pdfjs-js && pnpm copy-pdfjs-fonts && pnpm copy-flatten-pdfjs-css",
+    "copy-pdfjs": "pnpm copy-pdfjs-js && pnpm copy-pdfjs-wasm && pnpm copy-pdfjs-fonts && pnpm copy-flatten-pdfjs-css",
+    "copy-simplecc": "cpx \"../../packages/simplecc-wasm/dist/web/*\" ./public/vendor/simplecc",
+    "copy-jieba": "cpx \"./node_modules/jieba-wasm/pkg/web/*\" ./public/vendor/jieba",
     "setup-pdfjs": "pnpm prepare-public-vendor && pnpm copy-pdfjs",
+    "setup-simplecc": "pnpm prepare-public-vendor && pnpm copy-simplecc",
+    "setup-jieba": "pnpm prepare-public-vendor && pnpm copy-jieba",
+    "setup-vendors": "pnpm setup-pdfjs && pnpm setup-simplecc && pnpm setup-jieba",
     "build-win-x64": "dotenv -e .env.tauri.local -- tauri build --target i686-pc-windows-msvc --bundles nsis",
     "build-win-arm64": "dotenv -e .env.tauri.local -- tauri build --target aarch64-pc-windows-msvc --bundles nsis",
     "build-linux-x64": "dotenv -e .env.tauri.local -- tauri build --target x86_64-unknown-linux-gnu --bundles appimage",
@@ -33,110 +61,193 @@
     "release-ios-appstore": "dotenv -e .env.ios-appstore.local -- bash scripts/release-ios-appstore.sh",
     "release-google-play": "dotenv -e .env.google-play.local -- bash scripts/release-google-play.sh",
     "config-wrangler": "sed -i \"s/\\${TRANSLATIONS_KV_ID}/$TRANSLATIONS_KV_ID/g\" wrangler.toml",
-    "preview": "NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && opennextjs-cloudflare preview --ip 0.0.0.0",
-    "deploy": "NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && opennextjs-cloudflare deploy",
-    "upload": "NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && opennextjs-cloudflare upload",
+    "preview": "pnpm patch-build-webpack && NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && pnpm restore-build-original && opennextjs-cloudflare preview --ip 0.0.0.0 --port 3001",
+    "deploy": "pnpm patch-build-webpack && NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && pnpm restore-build-original && opennextjs-cloudflare deploy",
+    "upload": "pnpm patch-build-webpack && NEXT_PUBLIC_APP_PLATFORM=web opennextjs-cloudflare build && pnpm restore-build-original && opennextjs-cloudflare upload",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts",
+    "patch-build-webpack": "if [ \"$(uname)\" = \"Darwin\" ]; then sed -i '' 's/next build\"/next build --webpack\"/' package.json; else sed -i 's/next build\"/next build --webpack\"/' package.json; fi",
+    "restore-build-original": "if [ \"$(uname)\" = \"Darwin\" ]; then sed -i '' 's/next build --webpack\"/next build\"/' package.json; else sed -i 's/next build --webpack\"/next build\"/' package.json; fi",
+    "update-metadata": "bash ./scripts/sync-release-notes.sh release-notes.json ../../data/metainfo/appdata.xml",
     "check:optional-chaining": "count=$(grep -rno '\\?\\.[a-zA-Z_$]' .next/static/chunks/* out/_next/static/chunks/* | wc -l); if [ \"$count\" -gt 0 ]; then echo '❌ Optional chaining found in output!'; exit 1; else echo '✅ No optional chaining found.'; fi",
     "check:translations": "count=$(grep -rno '__STRING_NOT_TRANSLATED__' public/locales/* | wc -l); if [ \"$count\" -gt 0 ]; then echo '❌ Untranslated strings found!'; exit 1; else echo '✅ All strings translated.'; fi",
-    "check:all": "pnpm check:optional-chaining && pnpm check:translations",
-    "build-check": "pnpm build && pnpm build-web && pnpm check:all"
+    "check:lookbehind-regex": "count=$(grep -rnoE '\\(\\?<[!=]' .next/static/chunks/* out/_next/static/chunks/* | wc -l); if [ \"$count\" -gt 0 ]; then echo '❌ Lookbehind regex found in output!'; exit 1; else echo '✅ No lookbehind regex found.'; fi",
+    "check:all": "pnpm check:translations && pnpm check:lookbehind-regex",
+    "build-check": "pnpm build && pnpm build-web && pnpm check:all",
+    "worktree:new": "pnpm exec tsx scripts/worktree-new.ts",
+    "worktree:rm": "pnpm exec tsx scripts/worktree-rm.ts"
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.735.0",
-    "@aws-sdk/s3-request-presigner": "^3.735.0",
-    "@ducanh2912/next-pwa": "^10.2.9",
+    "@ai-sdk/react": "^3.0.49",
+    "@assistant-ui/react": "0.11.56",
+    "@assistant-ui/react-ai-sdk": "1.1.21",
+    "@assistant-ui/react-markdown": "0.11.9",
+    "@aws-sdk/client-s3": "^3.1000.0",
+    "@aws-sdk/s3-request-presigner": "^3.1000.0",
+    "@choochmeque/tauri-plugin-sharekit-api": "^0.3.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@emnapi/core": "^1.7.1",
+    "@emnapi/runtime": "^1.7.1",
     "@fabianlars/tauri-plugin-oauth": "2",
-    "@opennextjs/cloudflare": "^1.6.5",
-    "@stripe/react-stripe-js": "^3.7.0",
-    "@stripe/stripe-js": "^7.4.0",
+    "@napi-rs/wasm-runtime": "^1.1.1",
+    "@opennextjs/cloudflare": "^1.19.4",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@serwist/next": "^9.5.6",
+    "@serwist/webpack-plugin": "^9.5.6",
+    "@stripe/react-stripe-js": "^6.2.0",
+    "@stripe/stripe-js": "^9.3.1",
     "@supabase/auth-ui-react": "^0.4.7",
     "@supabase/auth-ui-shared": "^0.1.8",
-    "@supabase/supabase-js": "^2.55.0",
-    "@tauri-apps/api": "2.8.0",
-    "@tauri-apps/plugin-cli": "^2.4.0",
-    "@tauri-apps/plugin-deep-link": "^2.4.1",
-    "@tauri-apps/plugin-dialog": "^2.3.2",
-    "@tauri-apps/plugin-fs": "^2.4.1",
-    "@tauri-apps/plugin-haptics": "^2.3.0",
-    "@tauri-apps/plugin-http": "^2.5.1",
-    "@tauri-apps/plugin-log": "^2.6.0",
-    "@tauri-apps/plugin-opener": "^2.4.0",
-    "@tauri-apps/plugin-os": "^2.3.0",
-    "@tauri-apps/plugin-process": "^2.3.0",
-    "@tauri-apps/plugin-shell": "~2.3.0",
-    "@tauri-apps/plugin-updater": "^2.9.0",
-    "@zip.js/zip.js": "^2.7.53",
+    "@supabase/supabase-js": "^2.76.1",
+    "@tauri-apps/api": "2.10.1",
+    "@tauri-apps/plugin-cli": "^2.4.1",
+    "@tauri-apps/plugin-deep-link": "^2.4.7",
+    "@tauri-apps/plugin-dialog": "^2.6.0",
+    "@tauri-apps/plugin-fs": "^2.4.5",
+    "@tauri-apps/plugin-haptics": "^2.3.2",
+    "@tauri-apps/plugin-http": "^2.5.7",
+    "@tauri-apps/plugin-log": "^2.8.0",
+    "@tauri-apps/plugin-opener": "^2.5.3",
+    "@tauri-apps/plugin-os": "^2.3.2",
+    "@tauri-apps/plugin-process": "^2.3.1",
+    "@tauri-apps/plugin-shell": "~2.3.5",
+    "@tauri-apps/plugin-updater": "^2.10.0",
+    "@tauri-apps/plugin-websocket": "~2.4.2",
+    "@readest/turso-database-common": "0.6.0-pre.28-readest.0",
+    "@readest/turso-database-wasm-common": "0.6.0-pre.28-readest.0",
+    "@readest/turso-database-wasm": "0.6.0-pre.28-readest.0",
+    "@tybys/wasm-util": "^0.10.1",
+    "@zip.js/zip.js": "^2.8.16",
+    "abortcontroller-polyfill": "^1.7.8",
+    "ai": "^6.0.47",
+    "ai-sdk-ollama": "^3.2.0",
     "app-store-server-api": "^0.17.1",
     "aws4fetch": "^1.0.20",
+    "buffer": "^6.0.3",
+    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
     "cors": "^2.8.5",
-    "cssbeautify": "^0.3.1",
     "dayjs": "^1.11.13",
+    "dompurify": "^3.4.0",
+    "fflate": "^0.8.2",
     "foliate-js": "workspace:*",
     "franc-min": "^6.2.0",
+    "fzf": "^0.5.2",
+    "google-auth-library": "^10.5.0",
+    "googleapis": "^164.1.0",
     "highlight.js": "^11.11.1",
     "i18next": "^24.2.0",
     "i18next-browser-languagedetector": "^8.0.2",
-    "i18next-http-backend": "^3.0.1",
+    "i18next-http-backend": "^3.0.5",
     "iso-639-2": "^3.0.2",
     "iso-639-3": "^3.0.1",
+    "isomorphic-ws": "^5.0.0",
+    "jieba-wasm": "^2.4.0",
     "js-md5": "^0.8.3",
     "jwt-decode": "^4.0.0",
+    "lucide-react": "^0.562.0",
+    "lunr": "^2.3.9",
     "marked": "^15.0.12",
-    "next": "15.5.0",
+    "nanoid": "^5.1.6",
+    "next": "16.2.3",
+    "next-view-transitions": "^0.3.5",
+    "nunjucks": "^3.2.4",
     "overlayscrollbars": "^2.11.4",
     "overlayscrollbars-react": "^0.5.6",
     "posthog-js": "^1.246.0",
-    "react": "19.0.0",
+    "react": "19.2.5",
     "react-color": "^2.19.3",
-    "react-dom": "19.0.0",
+    "react-dom": "19.2.5",
     "react-i18next": "^15.2.0",
     "react-icons": "^5.4.0",
     "react-responsive": "^10.0.0",
+    "react-virtuoso": "^4.17.0",
     "react-window": "^1.8.11",
+    "remark-gfm": "^4.0.1",
     "semver": "^7.7.1",
-    "stripe": "^18.2.1",
+    "streamdown": "^1.6.10",
+    "stripe": "^22.0.2",
+    "styled-jsx": "^5.1.7",
+    "tailwind-merge": "^3.4.0",
+    "tauri-plugin-device-info-api": "^1.0.1",
     "tinycolor2": "^1.6.0",
-    "uuid": "^11.1.0",
+    "uuid": "^14.0.0",
+    "ws": "^8.18.3",
     "zod": "^4.0.8",
-    "zustand": "5.0.6"
+    "zustand": "5.0.10"
   },
   "devDependencies": {
     "@next/bundle-analyzer": "^15.4.2",
     "@tailwindcss/typography": "^0.5.16",
-    "@tauri-apps/cli": "2.8.1",
+    "@tauri-apps/cli": "2.10.1",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.0",
+    "@tursodatabase/database": "0.6.0-pre.28",
     "@types/cors": "^2.8.17",
     "@types/cssbeautify": "^0.3.5",
+    "@types/lunr": "^2.3.7",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^22.15.31",
-    "@types/react": "18.3.12",
+    "@types/nunjucks": "^3.2.6",
+    "@types/react": "^19.0.0",
     "@types/react-color": "^3.0.13",
-    "@types/react-dom": "18.3.1",
+    "@types/react-dom": "^19.0.0",
     "@types/react-window": "^1.8.8",
     "@types/semver": "^7.7.0",
     "@types/tinycolor2": "^1.4.6",
     "@types/uuid": "^10.0.0",
-    "@vitejs/plugin-react": "^4.7.0",
+    "@types/ws": "^8.18.1",
+    "@typescript/native-preview": "7.0.0-dev.20260312.1",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitejs/plugin-rsc": "^0.5.23",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/browser-webdriverio": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@wdio/cli": "^9.25.0",
+    "@wdio/globals": "^9.23.0",
+    "@wdio/local-runner": "^9.24.0",
+    "@wdio/mocha-framework": "^9.24.0",
+    "@wdio/spec-reporter": "^9.24.0",
+    "@wdio/types": "^9.24.0",
     "autoprefixer": "^10.4.20",
+    "caniuse-lite": "^1.0.30001746",
     "cpx2": "^8.0.0",
     "daisyui": "^4.12.24",
     "dotenv-cli": "^7.4.4",
-    "eslint": "^9.16.0",
-    "eslint-config-next": "15.0.3",
     "i18next-scanner": "^4.6.0",
-    "jsdom": "^26.1.0",
+    "jsdom": "^28.1.0",
     "mkdirp": "^3.0.1",
     "node-env-run": "^4.0.2",
+    "playwright": "^1.58.2",
     "postcss": "^8.4.49",
     "postcss-cli": "^11.0.0",
     "postcss-nested": "^7.0.2",
     "raw-loader": "^4.0.2",
-    "tailwindcss": "^3.4.17",
+    "react-server-dom-webpack": "^19.2.5",
+    "serwist": "^9.3.0",
+    "tailwindcss": "^3.4.18",
     "typescript": "^5.7.2",
+    "vinext": "^0.0.21",
+    "vite": "^7.3.3",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.4",
-    "wrangler": "^4.31.0"
-  }
+    "vitest": "^4.0.18",
+    "wrangler": "^4.85.0"
+  },
+  "browserslist": [
+    "chrome 92",
+    "edge 92",
+    "firefox 92",
+    "safari 15.2"
+  ]
 }

apps/readest-app/public/.well-known/apple-app-site-association

@@ -8,7 +8,15 @@
         "components": [
           {
             "/": "/auth/*",
-            "comment": "Matches any URL whose path starts with /auth/"
+            "comment": "Matches OAuth callback paths"
+          },
+          {
+            "/": "/o/*",
+            "comment": "Matches annotation deeplinks"
+          },
+          {
+            "/": "/s/*",
+            "comment": "Matches book share links"
           }
         ]
       }

apps/readest-app/public/.well-known/org.flathub.VerifiedApps.txt

@@ -0,0 +1 @@
+ed533042-5626-4704-b5f2-fa3bbd1136ed

apps/readest-app/public/_headers

@@ -1,2 +0,0 @@
-/_next/static/*
-  Cache-Control: public,max-age=31536000,immutable