release: version 0.10.2 (#3750)

preloadNextSSML() called tts.next() interleaved with await, creating async
gaps where the concurrent #speak() could dispatch marks against corrupted
#ranges state (replaced by next() for a different block). Since mark names
restart at "0" per block, marks resolved to the wrong text position, causing
accidental page turns and highlights far from the current sentence.

Fix: gather all tts.next() and tts.prev() calls synchronously (no await
between them) so no async code can see the intermediate #ranges state.

Co-authored-by: Claude Opus 4.6 (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*
+

.editorconfig

@@ -0,0 +1,3 @@
+[*.{ts,tsx}]
+indent_style = space
+indent_size = 2

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: ['readest']
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Share an idea or suggestion
+title: 'FR: describing your feature request'
+labels: enhancement
+assignees: ''
+---
+
+**Does your feature request involve difficulty for you to complete a task? Please describe.**
+
+> A clear and concise description of what the problem is. Ex. I think it takes too many steps to [...]
+
+**Describe the solution you'd like**
+
+> A clear and concise description of what you'd like to happen.
+
+**Describe alternatives you've considered**
+
+> A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+
+> Add any additional context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/report-bug.md

@@ -1,7 +1,7 @@
 ---
 name: Report a bug
 about: Report a bug or a functional regression
-title: 'Ex: In DarkMode, a blank square appears in bottom right corner while scrolling'
+title: 'Example: In DarkMode, a blank square appears in bottom right corner while scrolling'
 labels: ['type: bug']
 assignees: ''
 ---
@@ -11,28 +11,25 @@ assignees: ''
 A clear and concise description of what the current behavior is.
 Please also add **screenshots** of the existing application.
 
-**Example:**
-
-```
-In DarkMode, when scrollbar are displayed (for example on Companies page, with enough companies in the list), we see a blank square in the bottom right corner
-[screenshot]
-```
+> **Example:**
+> In DarkMode, when scrollbar are displayed (for example on Companies page, with enough companies in the list), we see a blank square in the bottom right corner
+> [screenshot]
 
 ## Expected behavior
 
 A clear and concise description of what the expected behavior is.
 
-**Example:**
-
-```
-The blank square should be transparent (invisible)
-```
+> **Example:**
+> The blank square should be transparent (invisible)
 
 ## Technical inputs
 
-**Example:**
+Operating System:
 
-```
-- We are displaying custom scrollbars that disappear when the user is not scrolling. See ScrollWrapper.
-- Probably fixable with CSS
-```
+Readest Version:
+
+> **Example:**
+> Operating System: Android 14 (WebView 135.0)
+> Readest Version: 0.9.0
+> We are displaying custom scrollbars that disappear when the user is not scrolling. See ScrollWrapper.
+> Probably fixable with CSS

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - '*' # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/pull-request.yml

@@ -0,0 +1,155 @@
+name: PR checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  rust_lint:
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: '-C target-cpu=skylake'
+      SCCACHE_GHA_ENABLED: 'true'
+      RUSTC_WRAPPER: sccache
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'true'
+      - name: setup sccache
+        uses: mozilla-actions/sccache-action@v0.0.9
+      - 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 check
+        working-directory: apps/readest-app/src-tauri
+        run: cargo fmt --check
+      - name: Clippy Check
+        working-directory: apps/readest-app/src-tauri
+        run: cargo clippy -p Readest --no-deps -- -D warnings
+
+  build_web_app:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'true'
+
+      - name: setup pnpm
+        uses: pnpm/action-setup@v5
+
+      - 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-web-${{ github.sha }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: |
+            nextjs-web-${{ github.sha }}-
+            nextjs-web-
+
+      - name: install Dependencies
+        working-directory: apps/readest-app
+        run: |
+          pnpm install && pnpm setup-vendors
+
+      - name: run format check
+        run: |
+          pnpm format:check || (pnpm format && git diff && exit 1)
+
+      - 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 lint
+        working-directory: apps/readest-app
+        run: |
+          pnpm lint
+
+      - name: build the web app
+        working-directory: apps/readest-app
+        run: |
+          pnpm build-web && pnpm check:all
+
+  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@v5
+
+      - 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.9
+
+      - 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

@@ -6,32 +6,107 @@ on:
     types: [published]
 
 jobs:
-  create-release:
+  get-release:
     permissions:
       contents: write
     runs-on: ubuntu-latest
     outputs:
-      release_id: ${{ steps.create-release.outputs.result }}
+      release_id: ${{ steps.get-release.outputs.release_id }}
+      release_tag: ${{ steps.get-release.outputs.release_tag }}
+      release_note: ${{ steps.get-release-notes.outputs.release_note }}
+      release_version: ${{ steps.get-release-notes.outputs.release_version }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
       - name: setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
       - name: get version
         run: echo "PACKAGE_VERSION=$(node -p "require('./apps/readest-app/package.json').version")" >> $GITHUB_ENV
-      - name: create release
-        id: create-release
-        uses: actions/github-script@v6
+      - name: get release
+        id: get-release
+        uses: actions/github-script@v8
         with:
           script: |
             const { data } = await github.rest.repos.getLatestRelease({
               owner: context.repo.owner,
               repo: context.repo.repo,
             })
-            return data.id
+            core.setOutput('release_id', data.id);
+            core.setOutput('release_tag', data.tag_name);
+      - name: get release notes
+        id: get-release-notes
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const fs = require('fs');
+            const version = require('./apps/readest-app/package.json').version;
+            const releaseNotesFileContent = fs.readFileSync('./apps/readest-app/release-notes.json', 'utf8');
+            const releaseNotes = JSON.parse(releaseNotesFileContent).releases[version] || {};
+            const notes = releaseNotes.notes || [];
+            const releaseNote = notes.map((note, index) => `${index + 1}. ${note}`).join(' ');
+            console.log('Formatted release note:', releaseNote);
+            core.setOutput('release_version', version);
+            core.setOutput('release_note', releaseNote);
+
+  update-release:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    needs: get-release
+
+    steps:
+      - name: update release
+        id: update-release
+        uses: actions/github-script@v8
+        env:
+          release_id: ${{ needs.get-release.outputs.release_id }}
+          release_tag: ${{ needs.get-release.outputs.release_tag }}
+          release_note: ${{ needs.get-release.outputs.release_note }}
+        with:
+          script: |
+            const { data } = await github.rest.repos.generateReleaseNotes({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: process.env.release_tag,
+            })
+            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({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              release_id: process.env.release_id,
+              body: body,
+              draft: false,
+              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}"
+
+          cd apps
+          zip -r ../${plugin_zip} readest.koplugin
+          cd ..
+
+          echo "Uploading ${plugin_zip} to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} ${plugin_zip} --clobber
 
   build-tauri:
-    needs: create-release
+    needs: get-release
     permissions:
       contents: write
     strategy:
@@ -39,42 +114,69 @@ jobs:
       matrix:
         config:
           - os: ubuntu-latest
+            release: android
+            rust_target: aarch64-linux-android,armv7-linux-androideabi,i686-linux-android,x86_64-linux-android
+          - os: ubuntu-22.04
+            release: linux
             arch: x86_64
             rust_target: x86_64-unknown-linux-gnu
+          - os: ubuntu-22.04-arm
+            release: linux
+            arch: aarch64
+            rust_target: aarch64-unknown-linux-gnu
           - os: macos-latest
+            release: macos
             arch: aarch64
             rust_target: x86_64-apple-darwin,aarch64-apple-darwin
+            args: '--target universal-apple-darwin'
           - os: windows-latest
+            release: windows
             arch: x86_64
             rust_target: x86_64-pc-windows-msvc
+            args: '--target x86_64-pc-windows-msvc --bundles nsis'
+          - os: windows-latest
+            release: windows
+            arch: aarch64
+            rust_target: aarch64-pc-windows-msvc
+            args: '--target aarch64-pc-windows-msvc --bundles nsis'
 
     runs-on: ${{ matrix.config.os }}
-    timeout-minutes: 30
+    timeout-minutes: 60
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
       - name: initialize git submodules
         run: git submodule update --init --recursive
 
       - name: setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9.14.4
+        uses: pnpm/action-setup@v5
 
       - name: setup node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
 
-      - name: install rimraf
-        run: npm install -g rimraf
+      - name: setup Java (for Android build only)
+        if: matrix.config.release == 'android'
+        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@v4
+
+      - name: install NDK (for Android build only)
+        if: matrix.config.release == 'android'
+        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
@@ -83,31 +185,110 @@ jobs:
 
       - uses: Swatinem/rust-cache@v2
         with:
-          key: ${{ matrix.config.os }}-cargo-${{ hashFiles('apps/readest-app/src-tauri/Cargo.lock') }}
-          workspaces: apps/readest-app/src-tauri -> target
+          key: ${{ matrix.config.os }}-${{ matrix.config.release }}-${{ matrix.config.arch }}-cargo
+
+      - name: install dependencies (ubuntu only)
+        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
+
+      - name: install dependencies (ubuntu only - armhf specific)
+        if: contains(matrix.config.os, 'ubuntu') && matrix.config.arch == 'armhf'
+        run: |
+          sudo dpkg --add-architecture armhf
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libfontconfig-dev:armhf libgtk-3-dev:armhf libwebkit2gtk-4.1-dev:armhf libappindicator3-dev:armhf librsvg2-dev:armhf gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
+          echo 'PKG_CONFIG_ALLOW_CROSS=1' >> $GITHUB_ENV
+          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: |
           echo "NEXT_PUBLIC_POSTHOG_KEY=${{ secrets.NEXT_PUBLIC_POSTHOG_KEY }}" >> .env.local
           echo "NEXT_PUBLIC_POSTHOG_HOST=${{ secrets.NEXT_PUBLIC_POSTHOG_HOST }}" >> .env.local
-          echo "NEXT_PUBLIC_DEEPL_API_KEY=${{ secrets.NEXT_PUBLIC_DEEPL_API_KEY }}" >> .env.local
+          echo "NEXT_PUBLIC_SUPABASE_URL=${{ secrets.NEXT_PUBLIC_SUPABASE_URL }}" >> .env.local
+          echo "NEXT_PUBLIC_SUPABASE_ANON_KEY=${{ secrets.NEXT_PUBLIC_SUPABASE_ANON_KEY }}" >> .env.local
           echo "NEXT_PUBLIC_APP_PLATFORM=tauri" >> .env.local
+          cp .env.local apps/readest-app/.env.local
 
-      - name: copy .env.local to apps/readest-app
-        run: cp .env.local apps/readest-app/.env.local
-
-      - name: fix dynamic route for Next.js, see https://github.com/vercel/next.js/discussions/55393
-        run: rimraf "apps/readest-app/src/app/reader/[ids]"
-
-      - name: install dependencies (ubuntu only)
-        if: matrix.config.os == 'ubuntu-latest'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
-
-      - uses: tauri-apps/tauri-action@v0
+      - name: build and upload Android apks
+        if: matrix.config.release == 'android'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          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: |
+          cd apps/readest-app/
+          rm -rf src-tauri/gen/android
+          pnpm tauri android init
+          pnpm tauri icon ../../data/icons/readest-book.png
+          git checkout .
+
+          pushd src-tauri/gen/android
+          echo "keyAlias=${{ secrets.ANDROID_KEY_ALIAS }}" > keystore.properties
+          echo "password=${{ secrets.ANDROID_KEY_PASSWORD }}" >> keystore.properties
+          base64 -d <<< "${{ secrets.ANDROID_KEY_BASE64 }}" > $RUNNER_TEMP/keystore.jks
+          echo "storeFile=$RUNNER_TEMP/keystore.jks" >> keystore.properties
+
+          popd
+          version=${{ needs.get-release.outputs.release_version }}
+          apk_path=src-tauri/gen/android/app/build/outputs/apk/universal/release
+          universial_apk=Readest_${version}_universal.apk
+          arm64_apk=Readest_${version}_arm64.apk
+          pnpm tauri android build
+          cp ${apk_path}/app-universal-release.apk $universial_apk
+          pnpm tauri android build -t aarch64
+          cp ${apk_path}/app-universal-release.apk $arm64_apk
+
+          echo "Uploading $universial_apk to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} $universial_apk --clobber
+          echo "Uploading $arm64_apk to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} $arm64_apk --clobber
+          echo "Uploading signatures to GitHub release"
+          pnpm tauri signer sign $universial_apk
+          pnpm tauri signer sign $arm64_apk
+          gh release upload ${{ needs.get-release.outputs.release_tag }} $universial_apk.sig --clobber
+          gh release upload ${{ needs.get-release.outputs.release_tag }} $arm64_apk.sig --clobber
+
+      - name: download and update latest.json for Android release
+        if: matrix.config.release == 'android'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cd apps/readest-app/
+          curl -sL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json
+
+          version=${{ needs.get-release.outputs.release_version }}
+          universial_apk_url="https://github.com/readest/readest/releases/download/${{ needs.get-release.outputs.release_tag }}/Readest_${version}_universal.apk"
+          arm64_apk_url="https://github.com/readest/readest/releases/download/${{ needs.get-release.outputs.release_tag }}/Readest_${version}_arm64.apk"
+
+          universial_sig=$(cat Readest_${version}_universal.apk.sig)
+          arm64_sig=$(cat Readest_${version}_arm64.apk.sig)
+
+          jq --arg url "$universial_apk_url" \
+              --arg sig "$universial_sig" \
+              '.platforms["android-universal"] = {signature: $sig, url: $url}' latest.json > tmp.$$.json && mv tmp.$$.json latest.json
+
+          jq --arg url "$arm64_apk_url" \
+              --arg sig "$arm64_sig" \
+              '.platforms["android-arm64"] = {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
+
+      - 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 }}
@@ -116,29 +297,101 @@ jobs:
           APPLE_ID: ${{ secrets.APPLE_ID }}
           APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
           APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+          NODE_OPTIONS: '--max-old-space-size=8192'
         with:
           projectPath: apps/readest-app
-          releaseId: ${{ needs.create-release.outputs.release_id }}
-          args: ${{ matrix.config.os == 'macos-latest' && '--target universal-apple-darwin' || '' }}
+          releaseId: ${{ needs.get-release.outputs.release_id }}
+          releaseBody: ${{ needs.get-release.outputs.release_note }}
+          args: ${{ matrix.config.args || '' }}
 
-  publish-release:
-    permissions:
-      contents: write
-    runs-on: ubuntu-latest
-    needs: [create-release, build-tauri]
-
-    steps:
-      - name: publish release
-        id: publish-release
-        uses: actions/github-script@v6
+      - name: upload release notes to GitHub release
         env:
-          release_id: ${{ needs.create-release.outputs.release_id }}
-        with:
-          script: |
-            github.rest.repos.updateRelease({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              release_id: process.env.release_id,
-              draft: false,
-              prerelease: false
-            })
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          echo "Uploading release notes to GitHub release"
+          gh release upload ${{ needs.get-release.outputs.release_tag }} apps/readest-app/release-notes.json --clobber
+
+      - 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 }}
+
+          if [ "$arch" = "x86_64" ]; then
+            bin_file="Readest_${version}_x64-portable.exe"
+          elif [ "$arch" = "aarch64" ]; then
+            bin_file="Readest_${version}_arm64-portable.exe"
+          else
+            echo "Unknown architecture: $arch"
+            exit 1
+          fi
+
+          exe_file="target/${{ matrix.config.rust_target }}/release/readest.exe"
+          # Browsers on Windows won't download zip files that contain exe files
+          # so upload the exe files instead. This is totally stupid.
+          # powershell.exe -Command "Compress-Archive -Path $exe_file -DestinationPath $bin_file -Force"
+          cp $exe_file $bin_file
+
+          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, build-tauri]
+    uses: ./.github/workflows/upload-to-r2.yml
+    with:
+      tag: ${{ needs.get-release.outputs.release_tag }}
+    secrets: inherit

.github/workflows/retry-workflow.yml

@@ -0,0 +1,18 @@
+name: Retry workflow
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_id:
+        required: true
+jobs:
+  rerun:
+    runs-on: ubuntu-latest
+    steps:
+      - name: rerun ${{ inputs.run_id }}
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run watch ${{ inputs.run_id }} > /dev/null 2>&1
+          gh run rerun ${{ inputs.run_id }} --failed

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

@@ -0,0 +1,77 @@
+name: Upload Release Assets to R2
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        required: true
+        type: string
+
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag name (e.g., v1.2.3)'
+        required: true
+        type: string
+
+jobs:
+  upload-to-r2:
+    runs-on: ubuntu-latest
+    timeout-minutes: 3
+    strategy:
+      fail-fast: false
+    env:
+      RELEASE_R2_BUCKET: readest-releases
+      RELEASE_R2_ACCOUNT_ID: ${{ secrets.RELEASE_R2_ACCOUNT_ID }}
+      RELEASE_R2_ACCESS_KEY_ID: ${{ secrets.RELEASE_R2_ACCESS_KEY_ID }}
+      RELEASE_R2_SECRET_ACCESS_KEY: ${{ secrets.RELEASE_R2_SECRET_ACCESS_KEY }}
+
+    steps:
+      - name: Download release assets
+        run: |
+          gh release download "${{ inputs.tag }}" --repo readest/readest --dir ./release-assets
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install rclone
+        run: curl https://rclone.org/install.sh | sudo bash
+
+      - name: Configure rclone
+        run: |
+          mkdir -p ~/.config/rclone
+          cat > ~/.config/rclone/rclone.conf <<EOF
+          [r2]
+          type = s3
+          provider = Cloudflare
+          access_key_id = $RELEASE_R2_ACCESS_KEY_ID
+          secret_access_key = $RELEASE_R2_SECRET_ACCESS_KEY
+          endpoint = https://${RELEASE_R2_ACCOUNT_ID}.r2.cloudflarestorage.com
+          EOF
+
+      - name: Modify latest.json download URLs
+        run: |
+          GITHUB_BASE_URL="https://github.com/readest/readest/releases/download"
+          READEST_BASE_URL="https://download.readest.com/releases"
+          sed -i "s#${GITHUB_BASE_URL}#${READEST_BASE_URL}#g" ./release-assets/latest.json
+
+      - name: Upload to R2
+        run: |
+          mkdir releases
+          mv ./release-assets/latest.json releases
+          mv ./release-assets/release-notes.json releases
+          rclone copy ./release-assets r2:${RELEASE_R2_BUCKET}/releases/${{ inputs.tag }}/
+          rclone copy ./releases r2:${RELEASE_R2_BUCKET}/releases/
+
+      - name: Upload successful
+        if: success()
+        run: echo "Upload completed successfully"
+
+  retry-on-failure:
+    if: failure() && fromJSON(github.run_attempt) < 3
+    needs: [upload-to-r2]
+    runs-on: ubuntu-latest
+    steps:
+      - env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run retry-workflow.yml -F run_id=${{ github.run_id }}

.github/workflows/vercel-merge.yml

@@ -0,0 +1,23 @@
+name: Deploy to vercel on merge
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+  deployments: write
+  pull-requests: write
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: 'true'
+      - uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          vercel-args: '--prod'
+          vercel-org-id: ${{ secrets.ORG_ID}}
+          vercel-project-id: ${{ secrets.PROJECT_ID}}

.gitignore

@@ -1,4 +1,5 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+docker/.env
 
 # dependencies
 /node_modules
@@ -35,3 +36,20 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# Rust build
+target
+
+fastlane/report.xml
+fastlane/metadata/android/en-US/changelogs
+
+*.koplugin.zip
+
+# nix
+result*
+
+.playwright-mcp/
+
+.claude/worktrees
+.claude/settings.local.json
+

.gitmodules

@@ -1,6 +1,21 @@
 [submodule "packages/foliate-js"]
 	path = packages/foliate-js
-	url = https://github.com/chrox/foliate-js.git
+	url = https://github.com/readest/foliate-js.git
 [submodule "packages/tauri"]
 	path = packages/tauri
-	url = https://github.com/chrox/tauri.git
+	url = https://github.com/readest/tauri.git
+[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

.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

.prettierrc.json

@@ -5,5 +5,6 @@
   "tabWidth": 2,
   "singleQuote": true,
   "jsxSingleQuote": true,
+  "endOfLine": "lf",
   "plugins": ["prettier-plugin-tailwindcss"]
 }

.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

@@ -4,4 +4,28 @@
     "packages/tauri/Cargo.toml",
     "apps/readest-app/src-tauri/Cargo.toml"
   ],
-}
+  // "editor.formatOnSave": true, // uncomment to add format on save
+  "typescript.inlayHints.parameterNames.enabled": "all",
+  "typescript.inlayHints.variableTypes.enabled": true,
+  "typescript.inlayHints.propertyDeclarationTypes.enabled": true,
+  "typescript.inlayHints.functionLikeReturnTypes.enabled": true,
+  "typescript.inlayHints.enumMemberValues.enabled": true,
+  "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

@@ -3,14 +3,14 @@
 When contributing to `Readest`, whether on GitHub or in other community spaces:
 
 - Be respectful, civil, and open-minded.
-- Before opening a new pull request, try searching through the [issue tracker](https://github.com/chrox/readest/issues) for known issues or fixes.
+- Before opening a new pull request, try searching through the [issue tracker](https://github.com/readest/readest/issues) for known issues or fixes.
 - If you want to make code changes based on your personal opinion(s), make sure you open an issue first describing the changes you want to make, and open a pull request only when your suggestions get approved by maintainers.
 
 ## How to Contribute
 
 ### Prerequisites
 
-In order to not waste your time implementing a change that has already been declined, or is generally not needed, start by [opening an issue](https://github.com/chrox/readest/issues/new/choose) describing the problem you would like to solve.
+In order to not waste your time implementing a change that has already been declined, or is generally not needed, start by [opening an issue](https://github.com/readest/readest/issues/new/choose) describing the problem you would like to solve.
 
 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.
 
@@ -33,7 +33,7 @@ To get started with Readest, follow these steps to clone and build the project.
 #### 1. Clone the Repository
 
 ```bash
-git clone https://github.com/chrox/readest.git
+git clone https://github.com/readest/readest.git
 cd readest
 git submodule update --init --recursive
 ```
@@ -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
@@ -75,13 +75,20 @@ Now you're all setup and can start implementing your changes.
 
 ### Implement your changes
 
-This project is a monorepo. The code for the `readest-app` is in the `app/readest-app` directory. Here are some useful scripts for developing the frontend only without compiling Tauri:
+This project is a monorepo. The code for the `readest-app` is in the `apps/readest-app` directory. Here are some useful scripts for developing the frontend only without compiling Tauri:
 
 | Command          | Description                                        |
 | ---------------- | -------------------------------------------------- |
 | `pnpm dev-web`   | Starts the development server for the web app only |
 | `pnpm build-web` | Builds the web app                                 |
 
+Recommended Visual Studio Code plugins for development:
+
+- JavaScript and TypeScript Nightly (ms-vscode.vscode-typescript-next)
+- VS Code ESLint extension (dbaeumer.vscode-eslint)
+- Prettier - Code formatter (esbenp.prettier-vscode)
+- rust-analyzer (rust-lang.rust-analyzer) (for Tauri development only)
+
 ### When you're done
 
 Check that your code follows the project's style guidelines by running:

Cargo.toml

@@ -0,0 +1,42 @@
+[workspace]
+members = [
+  "apps/readest-app/src-tauri",
+  "packages/tauri/crates/tauri",
+  "packages/tauri-plugins/plugins/fs"
+]
+exclude = [
+  "packages/qcms"
+]
+resolver = "2"
+
+[workspace.dependencies]
+serde = { version = "1", features = ["derive"] }
+tracing = "0.1"
+log = "0.4"
+tauri = { version = "2", default-features = false }
+tauri-build = "2"
+tauri-plugin = "2"
+tauri-utils = "2"
+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"]
+homepage = "https://readest.com"
+license = "AGPL-3.0"
+repository = "https://github.com/readest/readest"
+categories = []
+edition = "2021"
+rust-version = "1.77.2"
+
+[patch.crates-io]
+tauri = { path = "packages/tauri/crates/tauri" }
+tauri-plugin-fs = { path = "packages/tauri-plugins/plugins/fs" }

Dockerfile

@@ -0,0 +1,40 @@
+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/
+
+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
+
+FROM build as production-stage
+ENTRYPOINT ["pnpm", "start-web", "-H", "0.0.0.0"]
+EXPOSE 3000

README.md

@@ -1,21 +1,26 @@
 <div align="center">
   <a href="https://readest.com?utm_source=github&utm_medium=referral&utm_campaign=readme" target="_blank">
-    <img src="https://github.com/chrox/readest/blob/main/apps/readest-app/src-tauri/icons/icon.png?raw=true" alt="Readest Logo" width="20%" />
+    <img src="https://github.com/readest/readest/blob/main/apps/readest-app/src-tauri/icons/icon.png?raw=true" alt="Readest Logo" width="20%" />
   </a>
   <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 offer a seamless cross-platform experience on macOS, Windows, Linux and Web, with support for mobile platforms coming soon.
+[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]
-[![][badge-discord]][link-discord]
 <br>
+[![Discord][badge-discord]][link-discord]
+[![Reddit][badge-reddit]][link-reddit]
 [![AGPL Licence][badge-license]](LICENSE)
+[![Language Coverage][badge-language-coverage]][link-locales]
+[![Donate][badge-donate]][link-donate]
 [![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>
 
@@ -25,13 +30,14 @@
   <a href="#screenshots">Screenshots</a> •
   <a href="#downloads">Downloads</a> •
   <a href="#getting-started">Getting Started</a> •
-  <a href="#contributors">Contributors</a> •
+  <a href="#troubleshooting">Troubleshooting</a> •
+  <a href="#support">Support</a> •
   <a href="#license">License</a>
 </p>
 
 <div align="center">
   <a href="https://readest.com" target="_blank">
-    <img src="./data/screenshots/landing_preview.png" alt="Readest Banner" width="100%" />
+    <img src="./data/screenshots/landing_all_platforms.png" alt="Readest Banner" width="100%" />
   </a>
 </div>
 
@@ -39,38 +45,38 @@
 
 <div align="left">✅ Implemented</div>
 
-| **Feature**                             | **Description**                                                                  | **Status** |
-| --------------------------------------- | -------------------------------------------------------------------------------- | ---------- |
-| **Multi-Format Support**                | Support EPUB, MOBI, KF8 (AZW3), FB2, CBZ, 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.                                  | ✅         |
-| **Translate with DeepL**                | Translate selected text instantly using DeepL for accurate translations.         | ✅         |
-| **[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.               | ✅         |
+| **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** |
-| -------------------------------- | ------------------------------------------------------------------------------------------ | ------------ |
-| **Support iOS and Android**      | Expand the APP to work on iOS and Android devices.                                         | 🛠           |
-| **Sync Across Platforms**        | Synchronize reading progress, notes, and bookmarks across all supported platforms.         | 🛠           |
-| **Sync with Koreader**           | Synchronize reading progress, notes, and bookmarks with [Koreader][link-koreader] devices. | 🔄           |
-| **Keyboard Navigation**          | Implement vimium-style keybindings for book navigation.                                    | 🔄           |
-| **Library Management**           | Organize, sort, and manage your entire ebook library.                                      | 🔄           |
-| **Support OPDS/Calibre**         | Integrate OPDS/Calibre to access online libraries and catalogs.                            | 🔄           |
-| **Text-to-Speech (TTS) Support** | Enable text-to-speech functionality for a more accessible reading experience.              | 🔄           |
-| **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.                         | 🔄           |
-| **AI-Powered Summarization**     | Generate summaries of books or chapters using AI for quick insights.                       | 🔄           |
+| **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. 😊
 
@@ -78,24 +84,35 @@ Stay tuned for continuous improvements and updates! Contributions and suggestion
 
 ![Annotations](./data/screenshots/annotations.png)
 
+![TTS](./data/screenshots/tts_speak_aloud.png)
+
 ![DeepL](./data/screenshots/deepl.png)
 
 ![Footnote](./data/screenshots/footnote_popover.png)
 
 ![Wikipedia](./data/screenshots/wikipedia_vertical.png)
 
-![Dark Mode](./data/screenshots/dark_mode.png)
+![Theming Dark Mode](./data/screenshots/theming_dark_mode.png)
 
 ---
 
 ## Downloads
 
-The Readest app is available for download! 🥳 🚀
+### Mobile Apps
 
-- macOS : Search for "Readest" on the [macOS App Store][link-macos-appstore].
-- Windows / Linux: Visit [https://readest.com][link-website] or the [Releases on GitHub][link-gh-releases].
-- Web: Visit [https://web.readest.com][link-web-readest].
-- iOS / Android: coming soon 👀
+<div align="center">
+  <a href="https://apps.apple.com/app/id6738622779">
+    <img alt="Download on the App Store" src="https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg" style="height: 50px;" /></a>&nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://play.google.com/store/apps/details?id=com.bilingify.readest">
+    <img alt="Get it on Google Play" src="https://upload.wikimedia.org/wikipedia/commons/7/78/Google_Play_Store_badge_EN.svg" style="height: 50px;" /></a>
+</div>
+
+### Platform-Specific Downloads
+
+- 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
 
@@ -105,8 +122,8 @@ The Readest app is available for download! 🥳 🚀
 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
 ```
@@ -118,18 +135,18 @@ To get started with Readest, follow these steps to clone and build the project.
 ### 1. Clone the Repository
 
 ```bash
-git clone https://github.com/chrox/readest.git
+git clone https://github.com/readest/readest.git
 cd readest
-git submodule update --init --recursive
 ```
 
 ### 2. Install Dependencies
 
 ```bash
 # 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
@@ -147,35 +164,167 @@ For Windows targets, “Build Tools for Visual Studio 2022” (or a higher editi
 ### 4. Build for Development
 
 ```bash
+# Start development for the Tauri app
 pnpm tauri dev
+# or start development for the Web app
+pnpm dev-web
+# preview with OpenNext build for the Web app
+pnpm preview
+```
+
+For Android:
+
+```bash
+# Initialize the Android environment (run once)
+rm apps/readest-app/src-tauri/gen/android
+pnpm tauri android init
+git checkout apps/readest-app/src-tauri/gen/android
+
+pnpm tauri android dev
+# or if you want to dev on a real device
+pnpm tauri android dev --host
+```
+
+For iOS:
+
+```bash
+# Set up the iOS environment (run once)
+pnpm tauri ios init
+
+pnpm tauri ios dev
+# or if you want to dev on a real device
+pnpm tauri ios dev --host
 ```
 
 ### 5. Build for Production
 
 ```bash
 pnpm tauri build
+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
+with all the necessary dependencies:
+
+```bash
+nix develop ./ops  # enter a dev shell for the web app
+nix develop ./ops#ios # enter a dev shell for the ios app
+nix develop ./ops#android # enter a dev shell for the android app
+```
+
+### 7. More information
+
+Please check the [wiki][link-gh-wiki] of this project for more information on development.
+
+## Troubleshooting
+
+### 1. Readest Won’t Launch on Windows (Missing Edge WebView2 Runtime)
+
+**Symptom**
+
+- When you double-click readest.exe, nothing happens. No window appears, and Task Manager does not show the process.
+- This can affect both the standard installer and the portable version.
+
+**Cause**
+
+- Microsoft Edge WebView2 Runtime is either missing, outdated, or improperly installed on your system. Readest depends on WebView2 to render the interface on Windows.
+
+**How to Fix**
+
+1. Check if WebView2 is installed
+   - Open “Add or Remove Programs” (a.k.a. Apps & features) on Windows. Look for “Microsoft Edge WebView2 Runtime.”
+2. Install or Update WebView2
+   - Download the WebView2 Runtime directly from Microsoft: [link](https://developer.microsoft.com/en-us/microsoft-edge/webview2?form=MA13LH).
+   - If you prefer an offline installer, download the offline package and run it as an Administrator.
+3. Re-run Readest
+   - After installing/updating WebView2, launch readest.exe again.
+   - If you still encounter problems, reboot your PC and try again.
+
+**Additional Tips**
+
+- If reinstalling once doesn’t work, uninstall Edge WebView2 completely, then reinstall it with Administrator privileges.
+- Verify your Windows installation has the latest updates from Microsoft.
+
+**Still Stuck?**
+
+- 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.
 
-<a href="https://github.com/chrox/readest/graphs/contributors">
+<a href="https://github.com/readest/readest/graphs/contributors">
   <p align="left">
-    <img width="50" src="https://contrib.rocks/image?repo=chrox/readest" alt="A table of avatars from the project's contributors" />
+    <img width="500" src="https://contrib.rocks/image?repo=readest/readest" alt="A table of avatars from the project's contributors" />
   </p>
 </a>
 
+## Support
+
+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.
+
+### Sponsors
+
+<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
 
 Readest is free software: you can redistribute it and/or modify it under the terms of the [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.html) as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the [LICENSE](LICENSE) file for details.
 
-The following JavaScript libraries are bundled in this software:
+The following libraries and frameworks are used in this software:
 
 - [foliate-js](https://github.com/johnfactotum/foliate-js), which is MIT licensed.
 - [zip.js](https://github.com/gildas-lormeau/zip.js), which is licensed under the BSD-3-Clause license.
 - [fflate](https://github.com/101arrowz/fflate), which is MIT licensed.
 - [PDF.js](https://github.com/mozilla/pdf.js), which is licensed under Apache License 2.0.
+- [daisyUI](https://github.com/saadeghi/daisyui), which is MIT licensed.
+- [marked](https://github.com/markedjs/marked), which is MIT licensed.
+- [next.js](https://github.com/vercel/next.js), which is MIT licensed.
+- [react-icons](https://github.com/react-icons/react-icons), which has various open-source licenses.
+- [react](https://github.com/facebook/react), which is MIT licensed.
+- [tauri](https://github.com/tauri-apps/tauri), which is MIT licensed.
+
+The following fonts are utilized in this software, either bundled within the application or provided through web fonts:
+
+[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.
 
 ---
 
@@ -183,18 +332,31 @@ The following JavaScript libraries are bundled in this software:
 
 [badge-website]: https://img.shields.io/badge/website-readest.com-orange
 [badge-web-app]: https://img.shields.io/badge/read%20online-web.readest.com-orange
-[badge-license]: https://img.shields.io/github/license/chrox/readest?color=teal
-[badge-release]: https://img.shields.io/github/release/chrox/readest?color=green
-[badge-platforms]: https://img.shields.io/badge/OS-macOS%2C%20Windows%2C%20Linux%2C%20Web-green
-[badge-last-commit]: https://img.shields.io/github/last-commit/chrox/readest?color=green
-[badge-commit-activity]: https://img.shields.io/github/commit-activity/m/chrox/readest
+[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=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
-[link-macos-appstore]: https://apps.apple.com/app/apple-store/id6738622779?pt=127463130&ct=github&mt=8
+[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/chrox/readest/releases
-[link-gh-commits]: https://github.com/chrox/readest/commits/main
-[link-gh-pulse]: https://github.com/chrox/readest/pulse
-[link-discord]: https://discord.gg/jb2nzDts
+[link-gh-releases]: https://github.com/readest/readest/releases
+[link-gh-commits]: https://github.com/readest/readest/commits/main
+[link-gh-pulse]: https://github.com/readest/readest/pulse
+[link-gh-wiki]: https://github.com/readest/readest/wiki
+[link-discord]: https://discord.gg/gntyVNk3BJ
 [link-parallel-read]: https://readest.com/#parallel-read
 [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,37 @@
+# Security Policy
+
+## 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.

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

@@ -0,0 +1,34 @@
+# 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
+
+## 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
+- [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

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,119 @@
+# 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. 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/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_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_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/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/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/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,8 @@
+## Verification (done-conditions)
+
+Before marking work complete, all applicable checks must pass:
+
+1. `pnpm test` — unit tests
+2. `pnpm lint` — ESLint
+3. `pnpm fmt:check` — Rust format check (only when `src-tauri/` files changed)
+4. `pnpm clippy:check` — Rust lint (only when `src-tauri/` files changed)

apps/readest-app/.env

@@ -1,3 +1,12 @@
 PDFJS_BUILD_PATH=../../packages/foliate-js/node_modules/pdfjs-dist/legacy/build
 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="cGhjX0x3ekhZRWtsZUVub3ZSc05ZQlRpTVRTV2MyS1NUOFdZMzBIWWFhN0ZPa1IK"
+
+NEXT_PUBLIC_DEFAULT_SUPABASE_URL_BASE64="aHR0cHM6Ly9yZWFkZXN0LnN1cGFiYXNlLmNv"
+NEXT_PUBLIC_DEFAULT_SUPABASE_KEY_BASE64="ZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKemRYQmhZbUZ6WlNJc0luSmxaaUk2SW5aaWMzbDRablZ6YW1weFpIaHJhbkZzZVhOaklpd2ljbTlzWlNJNkltRnViMjRpTENKcFlYUWlPakUzTXpReE1qTTJOekVzSW1WNGNDSTZNakEwT1RZNU9UWTNNWDAuM1U1VXFhb3VfMVNnclZlMWVvOXJBcGMwdUtqcWhwUWRVWGh2d1VIbVVmZw=="
+
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY_DEV_BASE64="cGtfdGVzdF81MVJmQmdLRTdSWW5pTWsxc0tDV2RUd2hMZzcySzk4eDRWcjlIdDdsRFBONngzcnpZYmhydGtNQnpDdzZKbHFaRVVITVp5eVNjVXhCZXVkcGppWTk0WXNHcDAweFlRRnRRaUU="
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY_BASE64="cGtfbGl2ZV81MVFYN3dRRU5ndjJFOUxQRHpZUlE5TlJJeTNjd09EZ1AzSkNFRHRPWlFtdFJWc3Brd053ZE1NNUpIVnVPTmJWcjZ3VGFCMUNZR1pJMmRPVWppTkY0bHJvVjAwalE4TkpkdWk="

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

@@ -0,0 +1,32 @@
+NEXT_PUBLIC_POSTHOG_KEY=YOUR_POSTHOG_KEY
+NEXT_PUBLIC_POSTHOG_HOST=YOUR_POSTHOG_HOST
+
+NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL
+NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
+
+NEXT_PUBLIC_STORAGE_FIXED_QUOTA=1073741824
+
+NEXT_PUBLIC_API_BASE_URL=https://your-api-base-url.com
+
+SUPABASE_ADMIN_KEY=YOUR_SUPABASE_ADMIN_KEY
+
+DEEPL_PRO_API_KEYS=YOUR_DEEPL_PRO_API_KEYS
+DEEPL_FREE_API_KEYS=YOUR_DEEPL_FREE_API_KEYS
+
+# r2, s3
+NEXT_PUBLIC_OBJECT_STORAGE_TYPE=r2
+
+R2_TOKEN_VALUE=YOUR_R2_TOKEN_VALUE
+R2_ACCESS_KEY_ID=YOUR_R2_ACCESS_KEY_ID
+R2_SECRET_ACCESS_KEY=YOUR_R2_SECRET_ACCESS_KEY
+R2_BUCKET_NAME=YOUR_R2_BUCKET_NAME
+R2_ACCOUNT_ID=YOUR_R2_ACCOUNT_ID
+R2_REGION=YOUR_R2_REGION
+
+S3_ENDPOINT=PLACE_HOLDER
+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,7 @@
 
 # testing
 /coverage
+.test-sandbox-node/
 
 # next.js
 /.next/
@@ -32,7 +33,7 @@ yarn-error.log*
 /private_keys
 
 # plists
-*.plist
+Entitlements*.plist
 
 # local confs
 tauri.*.conf.json
@@ -40,12 +41,31 @@ tauri.*.conf.json
 # vercel
 .vercel
 
+# open-next
+.open-next
+.wrangler
+
 # typescript
 *.tsbuildinfo
 next-env.d.ts
 
+# eslint
+.eslintcache
+
 #generated
 src-tauri/gen
 
 # vendor
 /public/vendor
+
+# Auto Generated PWA files
+/public/sw.js
+/public/workbox-*.js
+/public/fallback-*.js
+/public/swe-worker-*.js
+
+/dist/
+
+.claude/settings.local.json
+.claude/skills
+

apps/readest-app/AGENTS.md

@@ -0,0 +1,91 @@
+## 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/`.
+
+## 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.
+
+## Web Browsing & QA (gstack)
+
+For all web browsing, QA testing, and site interaction, use the `/browse` skill from gstack. **Never use `mcp__claude-in-chrome__*` tools directly.**
+
+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/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,48 @@
+## 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
+
+### 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/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/i18next-scanner.config.cjs

@@ -0,0 +1,64 @@
+const options = {
+  debug: false,
+  sort: false,
+  func: {
+    list: ['_'],
+    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+  },
+  lngs: [
+    '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',
+    'zh-CN',
+    'zh-TW',
+    'ro',
+  ],
+  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/next.config.mjs

@@ -1,32 +1,116 @@
-/** @type {import('next').NextConfig} */
-const isProd = process.env.NODE_ENV === 'production';
+import withSerwistInit from '@serwist/next';
+import withBundleAnalyzer from '@next/bundle-analyzer';
 
-const internalHost = process.env.TAURI_DEV_HOST || 'localhost';
+const isDev = process.env['NODE_ENV'] === 'development';
+const appPlatform = process.env['NEXT_PUBLIC_APP_PLATFORM'];
+
+if (isDev) {
+  const { initOpenNextCloudflareForDev } = await import('@opennextjs/cloudflare');
+  initOpenNextCloudflareForDev();
+}
+
+const exportOutput = appPlatform !== 'web' && !isDev;
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   // Ensure Next.js uses SSG instead of SSR
   // https://nextjs.org/docs/pages/building-your-application/deploying/static-exports
-  output: process.env['NEXT_PUBLIC_APP_PLATFORM'] === 'web' ? undefined : 'export',
+  output: exportOutput ? 'export' : undefined,
+  pageExtensions: exportOutput ? ['jsx', 'tsx'] : ['js', 'jsx', 'ts', 'tsx'],
   // Note: This feature is required to use the Next.js Image component in SSG mode.
   // See https://nextjs.org/docs/messages/export-image-api for different workarounds.
   images: {
     unoptimized: true,
   },
-  devIndicators: {
-    appIsrStatus: false,
-  },
+  devIndicators: false,
   // Configure assetPrefix or else the server won't properly resolve your assets.
-  assetPrefix: isProd ? '' : `http://${internalHost}:3000`,
+  assetPrefix: '',
   reactStrictMode: true,
+  serverExternalPackages: ['isows'],
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      nunjucks: 'nunjucks/browser/nunjucks.js',
+      ...(appPlatform !== 'web' ? { '@tursodatabase/database-wasm': false } : {}),
+    };
+    return config;
+  },
+  turbopack: {
+    resolveAlias: {
+      nunjucks: 'nunjucks/browser/nunjucks.js',
+      ...(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: '/api/deepl/:path*',
-        destination: 'https://api-free.deepl.com/v2/:path*',
+        source: '/reader/:ids',
+        destination: '/reader?ids=:ids',
+      },
+    ];
+  },
+  async headers() {
+    return [
+      {
+        source: '/.well-known/apple-app-site-association',
+        headers: [
+          {
+            key: 'Content-Type',
+            value: 'application/json',
+          },
+        ],
+      },
+      {
+        source: '/_next/static/:path*',
+        headers: [
+          {
+            key: 'Cache-Control',
+            value: isDev
+              ? 'public, max-age=0, must-revalidate'
+              : 'public, max-age=31536000, immutable',
+          },
+        ],
       },
     ];
   },
 };
 
-export default nextConfig;
+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',
+});
+
+export default withPWA(withAnalyzer(nextConfig));

apps/readest-app/open-next.config.ts

@@ -0,0 +1,6 @@
+import { defineCloudflareConfig } from '@opennextjs/cloudflare';
+import r2IncrementalCache from '@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache';
+
+export default defineCloudflareConfig({
+  incrementalCache: r2IncrementalCache,
+});

apps/readest-app/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@readest/readest-app",
-  "version": "0.8.3",
+  "version": "0.10.2",
   "private": true,
+  "type": "module",
   "scripts": {
     "dev": "dotenv -e .env.tauri -- next dev",
     "build": "dotenv -e .env.tauri -- next build",
@@ -9,69 +10,224 @@
     "dev-web": "dotenv -e .env.web -- next dev",
     "build-web": "dotenv -e .env.web -- next build",
     "start-web": "dotenv -e .env.web -- next start",
-    "lint": "next lint",
+    "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",
+    "i18n:extract": "i18next-scanner --config i18next-scanner.config.cjs",
+    "lint": "tsgo --noEmit && biome check .",
+    "test": "dotenv -e .env -e .env.test.local vitest",
+    "test:coverage": "dotenv -e .env -e .env.test.local -- vitest run --coverage",
+    "test:browser": "vitest --config vitest.browser.config.mts --watch=false",
+    "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": "dotenv -- cross-var cpx \"%PDFJS_BUILD_PATH%/pdf*\" ./public/vendor/pdfjs",
-    "copy-pdfjs-fonts": "dotenv -- cross-var cpx \"%PDFJS_FONTS_PATH%/{cmaps,standard_fonts}/*\" ./public/vendor/pdfjs",
-    "copy-flatten-pdfjs-annotation-layer-css": "dotenv -- cross-var npx postcss \"%PDFJS_STYLE_PATH%/annotation_layer_builder.css\" --no-map -u postcss-nested > ./public/vendor/pdfjs/annotation_layer_builder.css",
-    "copy-flatten-pdfjs-text-layer-css": "dotenv -- cross-var npx postcss \"%PDFJS_STYLE_PATH%/text_layer_builder.css\" --no-map -u postcss-nested > ./public/vendor/pdfjs/text_layer_builder.css",
+    "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",
+    "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",
     "setup-pdfjs": "pnpm prepare-public-vendor && pnpm copy-pdfjs",
+    "setup-simplecc": "pnpm prepare-public-vendor && pnpm copy-simplecc",
+    "setup-vendors": "pnpm setup-pdfjs && pnpm setup-simplecc",
     "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",
     "build-macos-universial": "dotenv -e .env.tauri.local -e .env.apple-nonstore.local -- tauri build -t universal-apple-darwin --bundles dmg",
     "build-macos-universial-appstore": "dotenv -e .env.tauri.local -e .env.apple-appstore.local -- tauri build -t universal-apple-darwin --bundles app --config src-tauri/tauri.appstore.conf.json",
     "build-macos-universial-appstore-dev": "dotenv -e .env.tauri.local -e .env.apple-appstore-dev.local -- tauri build -t universal-apple-darwin --bundles app --config src-tauri/tauri.appstore-dev.conf.json",
-    "release-macos-universial-appstore": "dotenv -e .env.tauri.local -e .env.apple-appstore.local -- bash scripts/release-mac-appstore.sh"
+    "build-ios": "dotenv -e .env.ios-appstore-dev.local -- tauri ios build",
+    "build-ios-appstore": "dotenv -e .env.ios-appstore.local -- tauri ios build --export-method app-store-connect",
+    "release-macos-universial-appstore": "dotenv -e .env.tauri.local -e .env.apple-appstore.local -- bash scripts/release-mac-appstore.sh",
+    "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": "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: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"
   },
   "dependencies": {
-    "@tauri-apps/api": "2.1.1",
-    "@tauri-apps/plugin-cli": "^2.0.0",
-    "@tauri-apps/plugin-dialog": "^2.0.1",
-    "@tauri-apps/plugin-fs": "^2.0.3",
-    "@tauri-apps/plugin-http": "^2.0.1",
-    "@tauri-apps/plugin-log": "^2.0.1",
-    "@tauri-apps/plugin-os": "^2.0.0",
-    "@tauri-apps/plugin-process": "^2.0.0",
-    "@tauri-apps/plugin-shell": "~2.0.1",
-    "@tauri-apps/plugin-updater": "^2.0.0",
-    "@zip.js/zip.js": "^2.7.53",
+    "@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",
+    "@emnapi/core": "^1.7.1",
+    "@emnapi/runtime": "^1.7.1",
+    "@fabianlars/tauri-plugin-oauth": "2",
+    "@napi-rs/wasm-runtime": "^1.1.1",
+    "@opennextjs/cloudflare": "^1.17.3",
+    "@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": "^3.7.0",
+    "@stripe/stripe-js": "^7.4.0",
+    "@supabase/auth-ui-react": "^0.4.7",
+    "@supabase/auth-ui-shared": "^0.1.8",
+    "@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",
+    "@tursodatabase/database-common": "^0.5.0",
+    "@tursodatabase/database-wasm": "^0.5.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",
-    "cssbeautify": "^0.3.1",
-    "epubjs": "^0.3.93",
+    "cmdk": "^1.1.1",
+    "cors": "^2.8.5",
+    "dayjs": "^1.11.13",
+    "dompurify": "^3.3.0",
     "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",
+    "iso-639-2": "^3.0.2",
+    "iso-639-3": "^3.0.1",
+    "isomorphic-ws": "^5.0.0",
     "js-md5": "^0.8.3",
-    "next": "15.0.3",
-    "posthog-js": "^1.194.1",
-    "react": "18.3.1",
-    "react-dom": "18.3.1",
-    "react-icons": "^5.3.0",
+    "jwt-decode": "^4.0.0",
+    "lucide-react": "^0.562.0",
+    "lunr": "^2.3.9",
+    "marked": "^15.0.12",
+    "nanoid": "^5.1.6",
+    "next": "16.2.1",
+    "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.2.4",
+    "react-color": "^2.19.3",
+    "react-dom": "19.2.4",
+    "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",
+    "streamdown": "^1.6.10",
+    "stripe": "^18.2.1",
+    "styled-jsx": "^5.1.7",
+    "tailwind-merge": "^3.4.0",
+    "tauri-plugin-device-info-api": "^1.0.1",
     "tinycolor2": "^1.6.0",
-    "zustand": "5.0.1"
+    "uuid": "^11.1.0",
+    "ws": "^8.18.3",
+    "zod": "^4.0.8",
+    "zustand": "5.0.10"
   },
   "devDependencies": {
-    "@tauri-apps/cli": "2.1.0",
+    "@next/bundle-analyzer": "^15.4.2",
+    "@tailwindcss/typography": "^0.5.16",
+    "@tauri-apps/cli": "2.10.1",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@tursodatabase/database": "^0.5.0",
+    "@types/cors": "^2.8.17",
     "@types/cssbeautify": "^0.3.5",
-    "@types/node": "^22.10.1",
-    "@types/react": "18.3.12",
-    "@types/react-dom": "18.3.1",
+    "@types/lunr": "^2.3.7",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.15.31",
+    "@types/nunjucks": "^3.2.6",
+    "@types/react": "^19.0.0",
+    "@types/react-color": "^3.0.13",
+    "@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",
+    "@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.21",
+    "@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",
-    "cpx": "^1.5.0",
-    "cross-var": "^1.1.0",
-    "daisyui": "^4.12.14",
+    "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": "^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.15",
-    "typescript": "^5.7.2"
+    "react-server-dom-webpack": "^19.2.4",
+    "serwist": "^9.3.0",
+    "tailwindcss": "^3.4.18",
+    "typescript": "^5.7.2",
+    "vinext": "^0.0.21",
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^4.0.18",
+    "wrangler": "^4.77.0"
   }
 }

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

@@ -0,0 +1,17 @@
+{
+  "applinks": {
+    "details": [
+      {
+        "appIDs": [
+          "J5W48D69VR.com.bilingify.readest"
+        ],
+        "components": [
+          {
+            "/": "/auth/*",
+            "comment": "Matches any URL whose path starts with /auth/"
+          }
+        ]
+      }
+    ]
+  }
+}

apps/readest-app/public/.well-known/assetlinks.json

@@ -0,0 +1,16 @@
+[
+  {
+    "relation": [
+      "delegate_permission/common.handle_all_urls",
+      "delegate_permission/common.get_login_creds"
+    ],
+    "target": {
+      "namespace": "android_app",
+      "package_name": "com.bilingify.readest",
+      "sha256_cert_fingerprints": [
+        "65:2D:11:67:76:12:29:14:18:42:CB:3D:18:50:B6:E4:7E:46:E1:2F:4B:E4:7F:5A:6C:14:B6:D7:12:74:1E:82",
+        "E0:E7:60:55:80:8D:3A:DE:A0:D1:CF:7C:20:85:40:A3:DD:4B:E6:4D:17:5C:0F:DE:26:57:7D:9C:5B:29:5F:51"
+      ]
+    }
+  }
+]

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

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

apps/readest-app/public/locales/en/translation.json

@@ -0,0 +1,27 @@
+{
+  "LXGW WenKai GB Screen": "LXGW WenKai SC",
+  "LXGW WenKai TC": "LXGW WenKai TC",
+  "Source Han Serif CN": "Source Han Serif",
+  "Huiwen-MinchoGBK": "Huiwen Mincho",
+  "KingHwa_OldSong": "KingHwa Song",
+  "Are you sure to delete {{count}} selected book(s)?_one": "Are you sure to delete {{count}} selected book?",
+  "Are you sure to delete {{count}} selected book(s)?_other": "Are you sure to delete {{count}} selected books?",
+  "Search in {{count}} Book(s)..._one": "Search in {{count}} book...",
+  "Search in {{count}} Book(s)..._other": "Search in {{count}} books...",
+  "{{count}} pages left in chapter_one": "<0>{{count}}</0><1> page left in chapter</1>",
+  "{{count}} pages left in chapter_other": "<0>{{count}}</0><1> pages left in chapter</1>",
+  "Deleted {{count}} file(s)_one": "Deleted {{count}} file",
+  "Deleted {{count}} file(s)_other": "Deleted {{count}} files",
+  "Failed to delete {{count}} file(s)_one": "Failed to delete {{count}} file",
+  "Failed to delete {{count}} file(s)_other": "Failed to delete {{count}} files",
+  "{{count}} selected_one": "{{count}} selected",
+  "{{count}} selected_other": "{{count}} selected",
+  "Are you sure to delete {{count}} selected file(s)?_one": "Are you sure to delete {{count}} selected file?",
+  "Are you sure to delete {{count}} selected file(s)?_other": "Are you sure to delete {{count}} selected files?",
+  "Successfully imported {{count}} book(s)_one": "Successfully imported {{count}} book",
+  "Successfully imported {{count}} book(s)_other": "Successfully imported {{count}} books",
+  "Set status for {{count}} book(s)_one": "Set status for {{count}} book",
+  "Set status for {{count}} book(s)_other": "Set status for {{count}} books",
+  "{{count}} book(s) synced_one": "{{count}} book synced",
+  "{{count}} book(s) synced_other": "{{count}} books synced"
+}