release: version 0.9.8 (#283)

.devcontainer/devcontainer.json

@@ -1,6 +0,0 @@
-{
-  "name": "Readest",
-  // Initialize only the submodules required for Docker builds.
-  // tauri/tauri-plugins are skipped here since they're only needed for desktop builds.
-  "postCreateCommand": "git submodule update --init packages/foliate-js packages/simplecc-wasm"
-}

.dockerignore

@@ -1,52 +0,0 @@
-# Dependencies
-node_modules
-**/node_modules
-
-# Rust build artifacts
-target
-**/target
-
-# Git
-.git
-.gitignore
-
-# Build outputs
-.next
-**/.next
-.open-next
-**/.open-next
-out
-**/out
-.vercel
-**/.vercel
-
-# Local env files
-docker/.env
-.env*.local
-**/.env*.local
-
-# Local credentials and tooling state
-*.pem
-certs
-**/certs
-.claude/settings.local.json
-**/.claude/settings.local.json
-.claude/worktrees
-**/.claude/worktrees
-.gstack
-**/.gstack
-.playwright-mcp
-**/.playwright-mcp
-
-# IDE
-.idea
-.vscode
-*.swp
-
-# OS files
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log
-npm-debug.log*

.github/FUNDING.yml

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

@@ -1,23 +1,19 @@
 ---
 name: Feature request
 about: Share an idea or suggestion
-title: 'FR: describing your feature request'
+title: 'FR: [a handful of words describing the FR]'
 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 [...]
+**Does your feature request involve difficulty completing 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.
+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.
+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.
+Add any additional context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/report-bug.md

@@ -11,16 +11,22 @@ 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
 
@@ -28,8 +34,11 @@ Operating System:
 
 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
+**Example:**
+
+```
+Operating System: macOS 14.3.1
+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

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

.github/workflows/android-e2e.yml

@@ -1,131 +0,0 @@
-name: Android E2E (CDP)
-
-# On-device end-to-end tests: boots an x86_64 Android emulator (KVM), installs
-# a debug APK, and runs the CDP-driven selection lane (pnpm test:android).
-# Not PR-blocking: runs nightly, on demand, or when a PR is labeled
-# `e2e-android`.
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '30 19 * * *'
-  pull_request:
-    types: [labeled, synchronize]
-
-concurrency:
-  group: android-e2e-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  android-e2e:
-    if: github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'e2e-android')
-    runs-on: ubuntu-latest
-    timeout-minutes: 90
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      - name: initialize git submodules
-        run: git submodule update --init --recursive
-
-      - name: enable KVM for the emulator
-        run: |
-          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
-          sudo udevadm control --reload-rules
-          sudo udevadm trigger --name-match=kvm
-
-      - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-
-      - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: setup Java
-        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # v5
-        with:
-          distribution: 'zulu'
-          java-version: '17'
-
-      - name: setup Android SDK
-        uses: android-actions/setup-android@40fd30fb8d7440372e1316f5d1809ec01dcd3699 # v4
-
-      - name: install NDK
-        run: sdkmanager "ndk;28.2.13676358"
-
-      - name: install dependencies
-        run: pnpm install --frozen-lockfile --prefer-offline
-
-      - 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@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
-        with:
-          targets: x86_64-linux-android
-
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          workspaces: apps/readest-app/src-tauri
-
-      - name: create .env.local file for Next.js
-        run: |
-          echo "NEXT_PUBLIC_APP_PLATFORM=tauri" >> .env.local
-          cp .env.local apps/readest-app/.env.local
-
-      - name: build debug APK (x86_64)
-        env:
-          NDK_HOME: ${{ env.ANDROID_HOME }}/ndk/28.2.13676358
-        run: |
-          cd apps/readest-app
-          # Only the customized files of gen/android are tracked — regenerate
-          # the gradle scaffolding, then restore the tracked customizations
-          # (same flow as the release workflow).
-          rm -rf src-tauri/gen/android
-          pnpm tauri android init
-          pnpm tauri icon ../../data/icons/readest-book.png
-          git checkout .
-          # Debug build: signed with the debug keystore, no release secrets
-          # needed (gradle only loads keystore.properties when it exists).
-          pnpm tauri android build --debug --target x86_64
-          APK=$(find src-tauri/gen/android/app/build/outputs/apk -name '*-debug.apk' | head -n 1)
-          echo "APK=$PWD/$APK" >> "$GITHUB_ENV"
-          test -n "$APK"
-
-      - name: cache AVD snapshot
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        id: avd-cache
-        with:
-          path: |
-            ~/.android/avd/*
-            ~/.android/adb*
-          key: avd-api-34
-
-      - name: create AVD snapshot for caching
-        if: steps.avd-cache.outputs.cache-hit != 'true'
-        uses: reactivecircus/android-emulator-runner@e89f39f1abbbd05b1113a29cf4db69e7540cae5a # v2
-        with:
-          api-level: 34
-          arch: x86_64
-          target: google_apis
-          force-avd-creation: false
-          emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
-          disable-animations: false
-          script: echo "AVD snapshot created"
-
-      - name: run Android e2e lane
-        uses: reactivecircus/android-emulator-runner@e89f39f1abbbd05b1113a29cf4db69e7540cae5a # v2
-        with:
-          api-level: 34
-          arch: x86_64
-          target: google_apis
-          force-avd-creation: false
-          emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
-          disable-animations: true
-          script: |
-            adb install -r "$APK"
-            cd apps/readest-app && pnpm test:android

.github/workflows/codeql.yml

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

.github/workflows/docker-image.yml

@@ -1,191 +0,0 @@
-name: Publish Docker image
-
-on:
-  workflow_dispatch:
-  push:
-    branches:
-      - main
-  release:
-    types:
-      - published
-
-concurrency:
-  group: publish-docker-image-${{ github.event.release.tag_name || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    permissions:
-      contents: read
-      packages: write
-    runs-on: ${{ matrix.runner }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            runner: ubuntu-latest
-          - platform: linux/arm64
-            runner: ubuntu-24.04-arm
-    env:
-      BUILD_ARGS: |
-        NEXT_PUBLIC_APP_PLATFORM=web
-    steps:
-      - name: Prepare platform pair
-        run: |
-          platform=${{ matrix.platform }}
-          echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
-
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          submodules: recursive
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Log in to GHCR
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Docker meta (for labels)
-        id: meta
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/readest
-
-      - name: Build and push by digest
-        id: build
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
-        with:
-          context: .
-          file: ./Dockerfile
-          target: production-stage
-          platforms: ${{ matrix.platform }}
-          labels: ${{ steps.meta.outputs.labels }}
-          build-args: ${{ env.BUILD_ARGS }}
-          cache-from: type=registry,ref=ghcr.io/${{ github.repository_owner }}/readest:buildcache-${{ env.PLATFORM_PAIR }}
-          cache-to: type=registry,ref=ghcr.io/${{ github.repository_owner }}/readest:buildcache-${{ env.PLATFORM_PAIR }},mode=max
-          outputs: type=image,name=ghcr.io/${{ github.repository_owner }}/readest,push-by-digest=true,name-canonical=true,push=true
-
-      - name: Export digest
-        run: |
-          mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
-
-      - name: Upload digest
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: digests-${{ env.PLATFORM_PAIR }}
-          path: /tmp/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-  merge:
-    needs: build
-    permissions:
-      contents: read
-      packages: write
-    runs-on: ubuntu-latest
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          path: /tmp/digests
-          pattern: digests-*
-          merge-multiple: true
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
-
-      - name: Log in to GHCR
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Detect Docker Hub credentials
-        id: dockerhub
-        run: |
-          if [ -n "${{ secrets.DOCKERHUB_USERNAME }}" ] && [ -n "${{ secrets.DOCKERHUB_TOKEN }}" ]; then
-            echo "enabled=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "enabled=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Log in to Docker Hub
-        if: steps.dockerhub.outputs.enabled == 'true'
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Extract image metadata (GHCR only)
-        id: meta-ghcr
-        if: steps.dockerhub.outputs.enabled != 'true'
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/readest
-          tags: |
-            type=raw,value=main,enable={{is_default_branch}}
-            type=raw,value=latest,enable={{is_default_branch}}
-            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
-            type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }}
-            type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }}
-            type=sha,prefix=sha-
-
-      - name: Extract image metadata (GHCR + Docker Hub)
-        id: meta-all
-        if: steps.dockerhub.outputs.enabled == 'true'
-        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
-        with:
-          images: |
-            ghcr.io/${{ github.repository_owner }}/readest
-            docker.io/${{ secrets.DOCKERHUB_USERNAME }}/readest
-          tags: |
-            type=raw,value=main,enable={{is_default_branch}}
-            type=raw,value=latest,enable={{is_default_branch}}
-            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
-            type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }}
-            type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }}
-            type=sha,prefix=sha-
-
-      - name: Create manifest list and push (GHCR only)
-        if: steps.dockerhub.outputs.enabled != 'true'
-        working-directory: /tmp/digests
-        env:
-          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta-ghcr.outputs.json }}
-        run: |
-          docker buildx imagetools create \
-            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf 'ghcr.io/${{ github.repository_owner }}/readest@sha256:%s ' *)
-
-      - name: Create manifest list and push (GHCR + Docker Hub)
-        if: steps.dockerhub.outputs.enabled == 'true'
-        working-directory: /tmp/digests
-        env:
-          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta-all.outputs.json }}
-        run: |
-          docker buildx imagetools create \
-            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf 'ghcr.io/${{ github.repository_owner }}/readest@sha256:%s ' *)
-
-      - name: Published image summary
-        run: |
-          echo "## Published Images" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "Tags:" >> "$GITHUB_STEP_SUMMARY"
-          echo '```' >> "$GITHUB_STEP_SUMMARY"
-          if [ "${{ steps.dockerhub.outputs.enabled }}" == "true" ]; then
-            echo "${{ steps.meta-all.outputs.tags }}" >> "$GITHUB_STEP_SUMMARY"
-          else
-            echo "${{ steps.meta-ghcr.outputs.tags }}" >> "$GITHUB_STEP_SUMMARY"
-          fi
-          echo '```' >> "$GITHUB_STEP_SUMMARY"

.github/workflows/nightly.yml

@@ -1,486 +0,0 @@
-# Nightly builds. Mirrors the build matrix and build/signing steps of
-# release.yml — keep cert/NDK/toolchain bumps, secret names, and the
-# truly-portable AppImage + portable-Windows steps in sync between the two.
-#
-# Differences from release.yml: this workflow (1) stamps a nightly version
-# `<base>-<YYYYMMDDHH>` (Asia/Shanghai), (2) publishes to Cloudflare R2 only (no
-# GitHub release), and (3) assembles `nightly/latest.json` race-free from
-# per-leg manifest fragments so a single failing leg never clobbers the manifest.
-name: Nightly Readest
-
-on:
-  schedule:
-    - cron: '0 22 * * *' # 22:00 UTC = 06:00 GMT+8
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-# Serialize runs so an older run can't publish nightly/latest.json after a newer
-# one (no cancel — let an in-flight build finish rather than drop artifacts).
-concurrency:
-  group: nightly-readest
-  cancel-in-progress: false
-
-jobs:
-  compute-version:
-    runs-on: ubuntu-latest
-    outputs:
-      nightly_version: ${{ steps.v.outputs.nightly_version }}
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          ref: main
-          persist-credentials: false
-      - id: v
-        run: |
-          BASE=$(node -p "require('./apps/readest-app/package.json').version")
-          STAMP=$(TZ=Asia/Shanghai date +%Y%m%d%H)
-          echo "nightly_version=${BASE}-${STAMP}" >> "$GITHUB_OUTPUT"
-
-  build:
-    needs: compute-version
-    permissions:
-      contents: read
-      # Required by actions/attest-build-provenance: id-token mints the Sigstore
-      # OIDC identity, attestations writes the provenance to the repo's store.
-      id-token: write
-      attestations: write
-    strategy:
-      fail-fast: false
-      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: 60
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          ref: main
-          persist-credentials: false
-
-      - name: initialize git submodules
-        run: git submodule update --init --recursive
-
-      - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-
-      - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: setup Java (for Android build only)
-        if: matrix.config.release == 'android'
-        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # 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@40fd30fb8d7440372e1316f5d1809ec01dcd3699 # 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 --frozen-lockfile --prefer-offline
-
-      - 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@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
-        with:
-          targets: ${{ matrix.config.rust_target }}
-
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          key: nightly-${{ 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'
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y pkg-config libfontconfig-dev libgtk-3-dev libwebkit2gtk-4.1 libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1 libjavascriptcoregtk-4.1-dev gir1.2-javascriptcoregtk-4.1 gir1.2-webkit2-4.1 libappindicator3-dev librsvg2-dev patchelf xdg-utils
-
-      - name: 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_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: install rclone
-        shell: bash
-        run: |
-          if [ "$RUNNER_OS" = "Linux" ]; then
-            sudo apt-get update && sudo apt-get install -y rclone
-          elif [ "$RUNNER_OS" = "macOS" ]; then
-            brew install rclone
-          else
-            choco install rclone -y
-          fi
-
-      - name: configure rclone
-        shell: bash
-        run: |
-          mkdir -p ~/.config/rclone
-          cat > ~/.config/rclone/rclone.conf <<EOF
-          [r2]
-          type = s3
-          provider = Cloudflare
-          access_key_id = ${{ secrets.RELEASE_R2_ACCESS_KEY_ID }}
-          secret_access_key = ${{ secrets.RELEASE_R2_SECRET_ACCESS_KEY }}
-          endpoint = https://${{ secrets.RELEASE_R2_ACCOUNT_ID }}.r2.cloudflarestorage.com
-          EOF
-
-      # ──────────────────────────── ANDROID ────────────────────────────
-      # `pnpm tauri android init` + `git checkout .` reverts tracked files
-      # (including package.json), so the nightly version MUST be patched AFTER
-      # the checkout. Mirrors release.yml's android build/signing steps.
-      - name: build and sign Android apks
-        if: matrix.config.release == 'android'
-        shell: bash
-        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: |
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          cd apps/readest-app/
-          rm -rf src-tauri/gen/android
-          pnpm tauri android init
-          pnpm tauri icon ../../data/icons/readest-book.png
-          git checkout .
-          # Patch the nightly version AFTER checkout so the stamp survives.
-          node -e "const f='package.json';const j=require('./'+f);j.version='${version}';require('fs').writeFileSync(f, JSON.stringify(j,null,2)+'\n')"
-
-          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
-
-          apk_path=src-tauri/gen/android/app/build/outputs/apk/universal/release
-          universal_apk=Readest_${version}_universal.apk
-          arm64_apk=Readest_${version}_arm64.apk
-          pnpm tauri android build
-          cp ${apk_path}/app-universal-release.apk $universal_apk
-          pnpm tauri android build -t aarch64
-          cp ${apk_path}/app-universal-release.apk $arm64_apk
-          pnpm tauri signer sign $universal_apk
-          pnpm tauri signer sign $arm64_apk
-
-      # ──────────────────────────── DESKTOP ────────────────────────────
-      # Linux uses the truly-portable AppImage tauri CLI fork (mirrors
-      # release.yml). The nightly version is patched BEFORE `tauri build` so the
-      # bundle filenames carry the stamp.
-      - 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
-
-      - name: build desktop bundles
-        if: matrix.config.release != 'android'
-        shell: bash
-        env:
-          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 }}
-          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
-          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          NODE_OPTIONS: '--max-old-space-size=8192'
-        run: |
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          node -e "const f='apps/readest-app/package.json';const j=require('./'+f);j.version='${version}';require('fs').writeFileSync(f, JSON.stringify(j,null,2)+'\n')"
-          cd apps/readest-app
-          # On Linux use the cargo `tauri` CLI (the truly-portable AppImage fork
-          # installed above); elsewhere the npm @tauri-apps/cli.
-          if [ "${{ matrix.config.release }}" = "linux" ]; then
-            cargo tauri build ${{ matrix.config.args }}
-          else
-            pnpm tauri build ${{ matrix.config.args }}
-          fi
-
-      # Portable Windows build: rebuild with NEXT_PUBLIC_PORTABLE_APP=true and
-      # ship the raw exe (mirrors release.yml). Runs after the NSIS build above.
-      - name: build and sign portable binaries (Windows only)
-        if: matrix.config.os == 'windows-latest'
-        shell: bash
-        env:
-          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 }}
-        run: |
-          set -euo pipefail
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          arch="${{ matrix.config.arch }}"
-          rust_target="${{ matrix.config.rust_target }}"
-
-          # The clean NSIS build above produced bundle/nsis/Readest_<ver>_<x64|
-          # arm64>-setup.exe (+ .sig). The portable rebuild below runs `tauri
-          # build ... --bundles nsis` AGAIN with NEXT_PUBLIC_PORTABLE_APP=true,
-          # which OVERWRITES that installer with a portable-flavored one. Stage
-          # the clean installer + its updater .sig to a safe dir FIRST so the
-          # collect step can read the untouched copy for the windows-* keys.
-          if [ "$arch" = "x86_64" ]; then
-            nsis_name="Readest_${version}_x64-setup.exe"
-          else
-            nsis_name="Readest_${version}_arm64-setup.exe"
-          fi
-          nsis_src="target/${rust_target}/release/bundle/nsis/${nsis_name}"
-          mkdir -p nsis-staged
-          cp "$nsis_src" "nsis-staged/${nsis_name}"
-          cp "${nsis_src}.sig" "nsis-staged/${nsis_name}.sig"
-
-          pushd apps/readest-app/
-          echo "NEXT_PUBLIC_PORTABLE_APP=true" >> .env.local
-          pnpm tauri build ${{ matrix.config.args }}
-          popd
-
-          if [ "$arch" = "x86_64" ]; then
-            bin_file="Readest_${version}_x64-portable.exe"
-          else
-            bin_file="Readest_${version}_arm64-portable.exe"
-          fi
-          exe_file="target/${{ matrix.config.rust_target }}/release/readest.exe"
-          # Browsers on Windows refuse to download zips containing exe files, so
-          # ship the exe directly (matches release.yml).
-          cp "$exe_file" "$bin_file"
-          pushd apps/readest-app/
-          pnpm tauri signer sign "../../$bin_file"
-          popd
-
-      # ───────────────── COLLECT ARTIFACTS + BUILD FRAGMENT ─────────────────
-      # Each leg copies its updater artifacts (+ .sig) into ./nightly-out and
-      # emits a per-leg manifest fragment keyed by the EXACT Tauri platform keys
-      # the client expects (see src/helpers/updater.ts::getNightlyPlatformKey and
-      # src/components/UpdaterWindow.tsx::TAURI_UPDATER_KEYS). The fragment
-      # `signature` is the .sig file CONTENTS; `url` is the download.readest.com
-      # URL of the uploaded artifact under nightly/<version>/.
-      - name: collect artifacts + build manifest fragment
-        shell: bash
-        run: |
-          set -euo pipefail
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          release="${{ matrix.config.release }}"
-          arch="${{ matrix.config.arch }}"
-          rust_target="${{ matrix.config.rust_target }}"
-          base_url="https://download.readest.com/nightly/${version}"
-          out="$PWD/nightly-out"
-          frag_dir="$out/frag"
-          mkdir -p "$out" "$frag_dir"
-          # Cargo WORKSPACE: bundles land in the REPO-ROOT target/ dir, not
-          # apps/readest-app/src-tauri/target/ (matches release.yml line 371).
-          bundle="target"
-
-          # Stage one artifact + its .sig into $out, then append a
-          # platforms[<key>] = {signature, url} entry to the fragment JSON.
-          frag="$frag_dir/${release}-${arch:-all}.json"
-          echo '{"platforms":{}}' > "$frag"
-          add_entry() {
-            local src="$1"; local fname="$2"; local key="$3"
-            if [ ! -f "$src" ] || [ ! -f "${src}.sig" ]; then
-              echo "::error::missing artifact or signature for $key: $src"
-              exit 1
-            fi
-            cp "$src" "$out/$fname"
-            cp "${src}.sig" "$out/${fname}.sig"
-            local sig; sig=$(cat "${src}.sig")
-            local url="${base_url}/${fname}"
-            jq --arg k "$key" --arg sig "$sig" --arg url "$url" \
-              '.platforms[$k] = {signature: $sig, url: $url}' "$frag" > "$frag.tmp" && mv "$frag.tmp" "$frag"
-            echo "fragment += $key -> $fname"
-          }
-
-          case "$release" in
-            android)
-              # Signed in the android step; basenames already version-stamped.
-              add_entry "apps/readest-app/Readest_${version}_universal.apk" "Readest_${version}_universal.apk" "android-universal"
-              add_entry "apps/readest-app/Readest_${version}_arm64.apk"     "Readest_${version}_arm64.apk"     "android-arm64"
-              ;;
-            macos)
-              # Universal updater bundle: bundle/macos/Readest.app.tar.gz (no
-              # version/arch on disk). Upload under the stable convention name
-              # Readest_universal.app.tar.gz; both darwin keys point at it.
-              src="${bundle}/universal-apple-darwin/release/bundle/macos/Readest.app.tar.gz"
-              add_entry "$src" "Readest_universal.app.tar.gz" "darwin-aarch64"
-              # Reuse the already-staged copy for the x86_64 key (same artifact).
-              x86_sig=$(cat "$out/Readest_universal.app.tar.gz.sig")
-              jq --arg sig "$x86_sig" --arg url "${base_url}/Readest_universal.app.tar.gz" \
-                '.platforms["darwin-x86_64"] = {signature: $sig, url: $url}' "$frag" > "$frag.tmp" && mv "$frag.tmp" "$frag"
-              echo "fragment += darwin-x86_64 -> Readest_universal.app.tar.gz"
-              ;;
-            windows)
-              if [ "$arch" = "x86_64" ]; then
-                nsis_name="Readest_${version}_x64-setup.exe"
-                portable_name="Readest_${version}_x64-portable.exe"
-                nsis_key="windows-x86_64"; portable_key="windows-x86_64-portable"
-              else
-                nsis_name="Readest_${version}_arm64-setup.exe"
-                portable_name="Readest_${version}_arm64-portable.exe"
-                nsis_key="windows-aarch64"; portable_key="windows-aarch64-portable"
-              fi
-              # Read the CLEAN NSIS installer staged before the portable rebuild
-              # (the rebuild overwrites bundle/nsis/...-setup.exe). See the
-              # "build and sign portable binaries" step.
-              add_entry "nsis-staged/${nsis_name}" "$nsis_name" "$nsis_key"
-              # Portable exe was copied + signed into the repo root above.
-              add_entry "$portable_name" "$portable_name" "$portable_key"
-              ;;
-            linux)
-              # Truly-portable AppImage: bundle/appimage/Readest_<ver>_<amd64|aarch64>.AppImage
-              if [ "$arch" = "x86_64" ]; then
-                appimage_name="Readest_${version}_amd64.AppImage"
-                key="linux-x86_64-appimage"
-              else
-                appimage_name="Readest_${version}_aarch64.AppImage"
-                key="linux-aarch64-appimage"
-              fi
-              # The Linux leg builds with `cargo tauri build` WITHOUT `--target`
-              # (no matrix args), so cargo emits bundles under target/release/
-              # (host-target default) — NOT target/<triple>/release/ like the
-              # macOS/Windows legs, which DO pass `--target`. So there is no
-              # ${rust_target} subdir here.
-              add_entry "${bundle}/release/bundle/appimage/${appimage_name}" "$appimage_name" "$key"
-              ;;
-            *)
-              echo "::error::unknown release leg: $release"; exit 1
-              ;;
-          esac
-
-      # Attest the distributable binaries staged in nightly-out (apks, AppImage,
-      # app.tar.gz, setup/portable exe). gh attestation verify is digest-based,
-      # so it verifies these against readest/readest even though they ship via
-      # download.readest.com rather than a GitHub release. The .sig updater
-      # signatures are excluded — they are not binaries users run.
-      - name: attest nightly binaries
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
-        with:
-          subject-path: |
-            nightly-out/Readest*
-            !nightly-out/*.sig
-
-      - name: upload artifacts + fragment to R2
-        shell: bash
-        run: |
-          set -euo pipefail
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          base="r2:readest-releases/nightly/${version}"
-          out="$PWD/nightly-out"
-          # Artifacts (exclude the local frag/ scratch dir).
-          rclone copy "$out" "$base/" --exclude "frag/**"
-          # Per-leg manifest fragment.
-          rclone copy "$out/frag" "$base/manifest-fragments/"
-
-  assemble-manifest:
-    needs: [compute-version, build]
-    if: ${{ always() && needs.build.result != 'cancelled' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: install rclone + jq
-        run: sudo apt-get update && sudo apt-get install -y rclone jq
-
-      - name: configure rclone
-        run: |
-          mkdir -p ~/.config/rclone
-          cat > ~/.config/rclone/rclone.conf <<EOF
-          [r2]
-          type = s3
-          provider = Cloudflare
-          access_key_id = ${{ secrets.RELEASE_R2_ACCESS_KEY_ID }}
-          secret_access_key = ${{ secrets.RELEASE_R2_SECRET_ACCESS_KEY }}
-          endpoint = https://${{ secrets.RELEASE_R2_ACCOUNT_ID }}.r2.cloudflarestorage.com
-          EOF
-
-      - name: assemble + atomically promote latest.json
-        run: |
-          set -euo pipefail
-          version="${{ needs.compute-version.outputs.nightly_version }}"
-          base="r2:readest-releases/nightly"
-
-          # Pull only the fragments that SUCCEEDED legs uploaded.
-          rclone copy "$base/${version}/manifest-fragments" ./frag || true
-          if [ -z "$(ls -A ./frag 2>/dev/null)" ]; then
-            echo "::error::no manifest fragments found — all build legs failed; manifest NOT promoted"
-            exit 1
-          fi
-
-          # Merge every fragment's .platforms into one manifest.
-          jq -s \
-            --arg version "$version" \
-            '{version: $version, pub_date: (now | todateiso8601), notes: "Nightly build", platforms: (map(.platforms) | add)}' \
-            ./frag/*.json > latest.json
-
-          echo "Assembled latest.json:"
-          jq '{version, platforms: (.platforms | keys)}' latest.json
-
-          # Promote the manifest with a directory `rclone copy`, exactly like the
-          # stable release flow writes releases/latest.json (upload-to-r2.yml).
-          # A single-file `rclone copyto`/`moveto` first issues a CreateBucket
-          # probe (PUT /<bucket>) that the object-scoped R2 token can't satisfy
-          # (403 AccessDenied); a directory copy PUTs the object directly. R2
-          # PutObject is atomic, so readers never observe a half-written manifest.
-          mkdir -p promote && cp latest.json promote/latest.json
-          rclone copy promote "$base/"
-
-      - name: prune old nightly folders (keep newest 7)
-        run: |
-          set -euo pipefail
-          base="r2:readest-releases/nightly"
-          # Version dirs are <base>-<YYYYMMDDHH>. Lexicographic order is NOT
-          # chronological across a base-version bump (e.g. 0.2.0-* sorts after
-          # 0.11.0-*), so sort by the numeric stamp tail (everything after the
-          # last '-') to keep the newest 7 by build time.
-          mapfile -t dirs < <(rclone lsf "$base/" --dirs-only | sed 's:/$::' \
-            | sed -E 's/^(.*)-([0-9]{10})$/\2 \1-\2/' | sort -n -k1,1 | cut -d' ' -f2-)
-          count=${#dirs[@]}
-          if [ "$count" -gt 7 ]; then
-            for d in "${dirs[@]:0:$((count-7))}"; do
-              echo "pruning $d"
-              rclone purge "$base/$d"
-            done
-          fi
-
-      - name: notify on failure
-        if: failure()
-        run: echo "::error::Nightly assemble failed — manifest not promoted."

.github/workflows/pull-request.yml

@@ -1,321 +1,59 @@
 name: PR checks
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
 permissions:
-  contents: read
+  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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@v4
         with:
           submodules: 'true'
-      - name: setup sccache
-        uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10
       - name: Install minimal stable with clippy and rustfmt
-        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           toolchain: stable
           override: true
-          components: rustfmt, clippy
-      - name: Cache apt packages
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        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
+          sudo apt-get install -y libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libsoup-3.0-dev
+      - name: Format
         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
-      - name: Unit tests
-        working-directory: apps/readest-app/src-tauri
-        run: cargo test -p Readest --lib
+        run: cargo clippy -- -D warnings
 
   build_web_app:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@v4
         with:
           submodules: 'true'
 
       - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.1
 
       - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        uses: actions/setup-node@v4
         with:
-          node-version: 24
+          node-version: 22
           cache: pnpm
 
       - name: install Dependencies
         working-directory: apps/readest-app
         run: |
-          pnpm install --frozen-lockfile --prefer-offline && pnpm setup-vendors
+          pnpm install && pnpm setup-pdfjs
 
-      - name: run format check
-        run: |
-          pnpm format:check || (pnpm format && git diff && exit 1)
-
-      # pnpm lint here is web-only (tsgo + biome). The koplugin syntax check
-      # (lint:lua) runs in the test_extensions job, which installs LuaJIT only
-      # when the koplugin sources changed.
-      - name: run lint
+      - name: build the web App
         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
-
-      - name: cache playwright browsers
-        id: playwright-cache
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: install playwright browsers
-        working-directory: apps/readest-app
-        run: |
-          if [ "${{ steps.playwright-cache.outputs.cache-hit }}" = 'true' ]; then
-            npx playwright install-deps chromium
-          else
-            npx playwright install --with-deps chromium
-          fi
-
-      - name: run web e2e tests
-        id: web_e2e
-        working-directory: apps/readest-app
-        run: pnpm test:e2e:web
-
-      - name: upload e2e report
-        if: ${{ failure() && steps.web_e2e.outcome == 'failure' }}
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: playwright-report
-          path: apps/readest-app/playwright-report/
-          retention-days: 7
-
-  # The jsdom unit suite is the slowest part of the PR checks, so it is split
-  # across two parallel shards (vitest --shard). The browser tests need
-  # Playwright and run only on shard 1; koplugin + browser-extension tests
-  # moved to the test_extensions job.
-  test_web_app:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1, 2]
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          submodules: 'true'
-
-      - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-
-      - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: install Dependencies
-        working-directory: apps/readest-app
-        run: |
-          pnpm install --frozen-lockfile --prefer-offline && pnpm setup-vendors
-
-      # Playwright is only needed by the browser tests, which run on shard 1.
-      - name: cache playwright browsers
-        if: matrix.shard == 1
-        id: playwright-cache
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: install playwright browsers
-        if: matrix.shard == 1
-        working-directory: apps/readest-app
-        run: |
-          if [ "${{ steps.playwright-cache.outputs.cache-hit }}" = 'true' ]; then
-            npx playwright install-deps chromium
-          else
-            npx playwright install --with-deps chromium
-          fi
-
-      - name: run web unit tests (shard ${{ matrix.shard }}/2)
-        working-directory: apps/readest-app
-        run: pnpm test:pr:web:unit --shard=${{ matrix.shard }}/2
-
-      - name: run web browser tests
-        if: matrix.shard == 1
-        working-directory: apps/readest-app
-        run: pnpm test:browser
-
-  # Browser-extension tests + build always run. The koplugin lint + Lua tests
-  # (and the ~45s LuaJIT/busted install they need) only run when the koplugin
-  # sources changed, so most PRs skip that cost entirely.
-  test_extensions:
-    runs-on: ubuntu-latest
-    # pull-requests: read lets dorny/paths-filter list a PR's changed files
-    # via the REST API (the top-level grant is contents: read only).
-    permissions:
-      contents: read
-      pull-requests: read
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          submodules: 'true'
-
-      - name: detect koplugin changes
-        id: changes
-        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4
-        with:
-          filters: |
-            koplugin:
-              - 'apps/readest.koplugin/**'
-
-      - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-
-      - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: install Dependencies
-        working-directory: apps/readest-app
-        run: |
-          pnpm install --frozen-lockfile --prefer-offline && pnpm setup-vendors
-
-      - name: run extension tests
-        working-directory: apps/readest-app
-        run: pnpm test:extension
-
-      - name: build browser extension
-        working-directory: apps/readest-app
-        run: pnpm build-browser-ext
-
-      - name: cache apt packages
-        if: steps.changes.outputs.koplugin == 'true'
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        with:
-          path: /var/cache/apt/archives
-          key: apt-test-koplugin-${{ runner.os }}
-
-      - name: install LuaJIT + busted (for koplugin lint + tests)
-        if: steps.changes.outputs.koplugin == 'true'
-        run: |
-          sudo apt-get update
-          # luajit  — pnpm lint:lua + pnpm test:lua
-          # luarocks/libsqlite3-dev — required to build lsqlite3complete
-          sudo apt-get install -y luajit luarocks libsqlite3-dev
-          # Install busted + the SQLite binding the LibraryStore specs use,
-          # both pinned to Lua 5.1 (LuaJIT-compatible). System-wide install
-          # so `luarocks --lua-version=5.1 path` (sourced by
-          # scripts/test-koplugin.mjs) picks them up.
-          sudo luarocks --lua-version=5.1 install busted
-          sudo luarocks --lua-version=5.1 install lsqlite3complete
-
-      - name: lint koplugin
-        if: steps.changes.outputs.koplugin == 'true'
-        working-directory: apps/readest-app
-        run: pnpm lint:lua
-
-      - name: run koplugin tests
-        if: steps.changes.outputs.koplugin == 'true'
-        working-directory: apps/readest-app
-        run: pnpm test:lua
-
-  build_tauri_app:
-    runs-on: ubuntu-latest
-    env:
-      SCCACHE_GHA_ENABLED: 'true'
-      RUSTC_WRAPPER: sccache
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          submodules: 'true'
-
-      - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
-
-      - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: 24
-          cache: pnpm
-
-      # The tauri tests run `next dev`, whose Turbopack cache lives in
-      # `.next/dev/cache` (a different path from the `next build` cache).
-      - name: cache Turbopack dev cache
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        with:
-          path: apps/readest-app/.next/dev/cache
-          key: turbo-dev-tauri-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            turbo-dev-tauri-${{ runner.os }}-
-
-      - name: install Dependencies
-        working-directory: apps/readest-app
-        run: |
-          pnpm install --frozen-lockfile --prefer-offline && pnpm setup-vendors
-
-      - name: setup sccache
-        uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10
-
-      - name: install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1
-        with:
-          toolchain: stable
-          # Disable this action's built-in rust-cache so the explicit
-          # Swatinem/rust-cache below is the single cache (it's the one
-          # configured with cache-workspace-crates for the vendored tauri fork).
-          cache: false
-
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
-        with:
-          # cache-workspace-crates caches the path/workspace crates too: the
-          # vendored tauri fork (packages/tauri, packages/tauri-plugins, wired
-          # via [patch.crates-io]) and the local src-tauri/plugins/*. These are
-          # workspace members that rust-cache prunes by default, so the whole
-          # tauri stack — plus every crates.io plugin that depends on the
-          # patched `tauri` — rebuilt on every run. They change only
-          # sporadically (pinned submodules), so caching them is a big win.
-          # The key is bumped (-ws) so the old workspace-crate-less cache is
-          # invalidated and the next run repopulates it with the workspace
-          # crates included.
-          key: tauri-cargo-ws
-          cache-all-crates: 'true'
-          cache-workspace-crates: 'true'
-
-      - name: Cache apt packages
-        uses: actions/cache@2c8a9bd7457de244a408f35966fab2fb45fda9c8 # v6.0.0
-        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
+          pnpm build-web

.github/workflows/release.yml

@@ -5,12 +5,10 @@ on:
   release:
     types: [published]
 
-permissions: read-all
-
 jobs:
   get-release:
     permissions:
-      contents: read
+      contents: write
     runs-on: ubuntu-latest
     outputs:
       release_id: ${{ steps.get-release.outputs.release_id }}
@@ -19,14 +17,14 @@ jobs:
       release_version: ${{ steps.get-release-notes.outputs.release_version }}
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@v4
       - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        uses: actions/setup-node@v4
       - name: get version
         run: echo "PACKAGE_VERSION=$(node -p "require('./apps/readest-app/package.json').version")" >> $GITHUB_ENV
       - name: get release
         id: get-release
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
+        uses: actions/github-script@v7
         with:
           script: |
             const { data } = await github.rest.repos.getLatestRelease({
@@ -37,7 +35,7 @@ jobs:
             core.setOutput('release_tag', data.tag_name);
       - name: get release notes
         id: get-release-notes
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
+        uses: actions/github-script@v7
         with:
           script: |
             const fs = require('fs');
@@ -50,177 +48,63 @@ jobs:
             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@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9
-        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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-
-      - name: create KOReader plugin zip
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          version=${{ needs.get-release.outputs.release_version }}
-          plugin_zip="Readest-${version}-1.koplugin.zip"
-          meta_file="apps/readest.koplugin/_meta.lua"
-          perl -i -pe "s/^}/    version = \"${version}\",\n}/" "${meta_file}"
-
-          # Exclude dev-only artifacts from the published plugin zip:
-          #   scripts/  — i18n + build helpers
-          #   docs/     — design notes
-          #   spec/     — busted test suite
-          #   .busted   — busted runner config
-          # Mirror these in apps/readest.koplugin/scripts/build-koplugin.mjs
-          # for local builds.
-          cd apps
-          zip -r ../${plugin_zip} readest.koplugin \
-            -x 'readest.koplugin/scripts/*' \
-               'readest.koplugin/docs/*' \
-               'readest.koplugin/spec/*' \
-               'readest.koplugin/.busted'
-          cd ..
-
-          echo "Uploading ${plugin_zip} to GitHub release"
-          gh release upload ${{ needs.get-release.outputs.release_tag }} ${plugin_zip} --clobber
-
   build-tauri:
     needs: get-release
     permissions:
       contents: write
-      # Required by actions/attest-build-provenance: id-token mints the Sigstore
-      # OIDC identity, attestations writes the provenance to the repo's store.
-      id-token: write
-      attestations: write
     strategy:
       fail-fast: false
       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'
+            args: '--target x86_64-pc-windows-msvc'
           - 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: 60
+    timeout-minutes: 20
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@v4
 
       - name: initialize git submodules
         run: git submodule update --init --recursive
 
       - name: setup pnpm
-        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.14.4
 
       - name: setup node
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        uses: actions/setup-node@v4
         with:
-          node-version: 24
+          node-version: 22
           cache: pnpm
 
-      - name: setup Java (for Android build only)
-        if: matrix.config.release == 'android'
-        uses: actions/setup-java@ad2b38190b15e4d6bdf0c97fb4fca8412226d287 # 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@40fd30fb8d7440372e1316f5d1809ec01dcd3699 # 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 --frozen-lockfile --prefer-offline
+        run: pnpm install
 
-      - name: copy pdfjs-dist and simplecc-dist to public directory
-        run: pnpm --filter @readest/readest-app setup-vendors
+      - name: copy pdfjs-dist to public directory
+        run: pnpm --filter @readest/readest-app setup-pdfjs
 
       - name: install Rust stable
-        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+        uses: dtolnay/rust-toolchain@stable
         with:
           targets: ${{ matrix.config.rust_target }}
 
-      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+      - uses: Swatinem/rust-cache@v2
         with:
-          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 libwebkit2gtk-4.1-dev libjavascriptcoregtk-4.1 libjavascriptcoregtk-4.1-dev gir1.2-javascriptcoregtk-4.1 gir1.2-webkit2-4.1 libappindicator3-dev librsvg2-dev patchelf xdg-utils
-
-      - name: install dependencies (ubuntu only - armhf specific)
-        if: contains(matrix.config.os, 'ubuntu') && matrix.config.arch == 'armhf'
-        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
+          key: ${{ matrix.config.os }}-cargo-${{ hashFiles('Cargo.lock') }}
 
       - name: create .env.local file for Next.js
         run: |
@@ -229,103 +113,19 @@ jobs:
           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: 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 }}
+      - name: copy .env.local to apps/readest-app
+        run: cp .env.local apps/readest-app/.env.local
+
+      - name: install dependencies (ubuntu only)
+        if: matrix.config.os == 'ubuntu-22.04'
         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 .
+          sudo apt-get update
+          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
 
-          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: attest Android apks
-        if: matrix.config.release == 'android'
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
-        with:
-          subject-path: |
-            apps/readest-app/Readest_${{ needs.get-release.outputs.release_version }}_universal.apk
-            apps/readest-app/Readest_${{ needs.get-release.outputs.release_version }}_arm64.apk
-
-      - name: download and update latest.json for Android release
-        if: matrix.config.release == 'android'
+      - uses: tauri-apps/tauri-action@v0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          cd apps/readest-app/
-          # Use -f so curl fails on HTTP errors instead of writing the 404 body
-          # ("Not Found") into latest.json and clobbering the release asset with
-          # invalid JSON, which then breaks tauri-action's updater merge on every
-          # subsequent build.
-          if ! curl -fsSL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json; then
-            echo "::error::Failed to download existing latest.json; aborting to avoid clobbering the release asset."
-            exit 1
-          fi
-          if ! jq empty latest.json 2>/dev/null; then
-            echo "::error::Existing latest.json is not valid JSON; aborting."
-            exit 1
-          fi
-
-          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@84b9d35b5fc46c1e45415bdb6144030364f7ebc5 # v0
-        id: tauri
-        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 }}
@@ -334,50 +134,18 @@ 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
-          # On Linux, build with the Rust `cargo tauri` CLI installed in the
-          # step above so the new (truly-portable AppImage) bundler is used.
-          # Without this, tauri-action falls back to the npm @tauri-apps/cli.
-          tauriScript: ${{ matrix.config.release == 'linux' && 'cargo tauri' || '' }}
           releaseId: ${{ needs.get-release.outputs.release_id }}
           releaseBody: ${{ needs.get-release.outputs.release_note }}
           args: ${{ matrix.config.args || '' }}
 
-      # Attest the freshly built desktop bundles (installers, AppImage, dmg,
-      # updater archives + their .sig). tauri-action reports their on-disk paths
-      # as a JSON array; fromJSON('"\n"') yields a real newline to join them into
-      # the newline-delimited list subject-path expects.
-      - name: attest desktop bundles
-        if: matrix.config.release != 'android' && steps.tauri.outputs.artifactPaths != ''
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
-        with:
-          subject-path: ${{ join(fromJSON(steps.tauri.outputs.artifactPaths), fromJSON('"\n"')) }}
-
-      - name: upload release notes to GitHub release
-        env:
-          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)
+      - name: 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 }}
@@ -400,71 +168,35 @@ jobs:
           echo "Uploading $bin_file to GitHub release"
           gh release upload ${{ needs.get-release.outputs.release_tag }} $bin_file --clobber
 
-          echo "Signing portable binary"
-          pushd apps/readest-app/
-          pnpm tauri signer sign "../../$bin_file"
-          popd
-          echo "Uploading signature to GitHub release"
-          gh release upload ${{ needs.get-release.outputs.release_tag }} $bin_file.sig --clobber
-
-      # The portable rebuild above is not produced by tauri-action, so it is not
-      # covered by the "attest desktop bundles" step; attest it here. Exactly one
-      # portable exe is staged at the workspace root per Windows leg.
-      - name: attest Windows portable binary
-        if: matrix.config.os == 'windows-latest'
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
-        with:
-          subject-path: Readest_*-portable.exe
-
-      - 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: |
-          # Use -f so curl fails on HTTP errors instead of writing the 404 body
-          # ("Not Found") into latest.json and clobbering the release asset with
-          # invalid JSON, which then breaks tauri-action's updater merge on every
-          # subsequent build.
-          if ! curl -fsSL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json; then
-            echo "::error::Failed to download existing latest.json; aborting to avoid clobbering the release asset."
-            exit 1
-          fi
-          if ! jq empty latest.json 2>/dev/null; then
-            echo "::error::Existing latest.json is not valid JSON; aborting."
-            exit 1
-          fi
-
-          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]
+  update-release:
     permissions:
-      contents: read
-    uses: ./.github/workflows/upload-to-r2.yml
-    with:
-      tag: ${{ needs.get-release.outputs.release_tag }}
-    secrets: inherit
+      contents: write
+    runs-on: ubuntu-latest
+    needs: [get-release, build-tauri]
+
+    steps:
+      - name: update release
+        id: update-release
+        uses: actions/github-script@v7
+        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
+            })

.github/workflows/scorecard.yml

@@ -1,78 +0,0 @@
-# This workflow uses actions that are not certified by GitHub. They are provided
-# by a third-party and are governed by separate terms of service, privacy
-# policy, and support documentation.
-
-name: Scorecard supply-chain security
-on:
-  # For Branch-Protection check. Only the default branch is supported. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
-  branch_protection_rule:
-  # To guarantee Maintained check is occasionally updated. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
-  schedule:
-    - cron: '26 4 * * 3'
-  push:
-    branches: [ "main" ]
-
-# Declare default permissions as read only.
-permissions: read-all
-
-jobs:
-  analysis:
-    name: Scorecard analysis
-    runs-on: ubuntu-latest
-    # `publish_results: true` only works when run from the default branch. conditional can be removed if disabled.
-    if: github.event.repository.default_branch == github.ref_name || github.event_name == 'pull_request'
-    permissions:
-      # Needed to upload the results to code-scanning dashboard.
-      security-events: write
-      # Needed to publish results and get a badge (see publish_results below).
-      id-token: write
-      # Uncomment the permissions below if installing in a private repository.
-      # contents: read
-      # actions: read
-
-    steps:
-      - name: "Checkout code"
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
-
-      - name: "Run analysis"
-        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
-        with:
-          results_file: results.sarif
-          results_format: sarif
-          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
-          # - you want to enable the Branch-Protection check on a *public* repository, or
-          # - you are installing Scorecard on a *private* repository
-          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
-          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
-
-          # Public repositories:
-          #   - Publish results to OpenSSF REST API for easy access by consumers
-          #   - Allows the repository to include the Scorecard badge.
-          #   - See https://github.com/ossf/scorecard-action#publishing-results.
-          # For private repositories:
-          #   - `publish_results` will always be set to `false`, regardless
-          #     of the value entered here.
-          publish_results: true
-
-          # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore
-          # file_mode: git
-
-      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
-      # format to the repository Actions tab.
-      - name: "Upload artifact"
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: SARIF file
-          path: results.sarif
-          retention-days: 5
-
-      # Upload the results to GitHub's code scanning dashboard (optional).
-      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
-      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
-        with:
-          sarif_file: results.sarif

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

@@ -1,74 +0,0 @@
-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
-
-permissions:
-  contents: read
-
-jobs:
-  upload-to-r2:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-    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: |
-          sudo apt-get update
-          sudo apt-get install -y rclone
-
-      - 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"

.github/workflows/vercel-merge.yml

@@ -4,20 +4,20 @@ on:
     branches:
       - main
 permissions:
-  contents: read
+  contents: write
+  deployments: write
+  pull-requests: write
 jobs:
   build_and_deploy:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@v4
         with:
           submodules: 'true'
-      - uses: amondnet/vercel-action@de09aeac2ace6599ec9b11ef87558759a496bac4 # v42
+      - uses: amondnet/vercel-action@v25
         with:
           vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          github-comment: false
+          github-token: ${{ secrets.GITHUB_TOKEN }}
           vercel-args: '--prod'
           vercel-org-id: ${{ secrets.ORG_ID}}
           vercel-project-id: ${{ secrets.PROJECT_ID}}

.gitignore

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

.gitmodules

@@ -1,27 +1,6 @@
 [submodule "packages/foliate-js"]
 	path = packages/foliate-js
-	url = https://github.com/readest/foliate-js.git
+	url = https://github.com/chrox/foliate-js.git
 [submodule "packages/tauri"]
 	path = packages/tauri
-	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
-[submodule "packages/js-mdict"]
-	path = packages/js-mdict
-	url = https://github.com/readest/js-mdict.git
-[submodule "apps/readest-app/src-tauri/plugins/tauri-plugin-webview-upgrade"]
-	path = apps/readest-app/src-tauri/plugins/tauri-plugin-webview-upgrade
-	url = https://github.com/readest/tauri-plugin-webview-upgrade.git
+	url = https://github.com/chrox/tauri.git

.husky/pre-commit

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

.husky/pre-push

@@ -1,3 +0,0 @@
-pnpm -C apps/readest-app format:check
-pnpm -C apps/readest-app lint
-pnpm -C apps/readest-app test

.prettierignore

@@ -0,0 +1 @@
+packages/foliate-js/

.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "trailingComma": "all",
+  "printWidth": 100,
+  "semi": true,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "jsxSingleQuote": true,
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

.vscode/extensions.json

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

.vscode/settings.json

@@ -4,29 +4,4 @@
     "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": "biomejs.biome",
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "explicit"
-  },
-  "[css]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[typescript]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[typescriptreact]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[json]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  }
-}
+}

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/readest/readest/issues) for known issues or fixes.
+- Before opening a new pull request, try searching through the [issue tracker](https://github.com/chrox/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/readest/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/chrox/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.
 
@@ -43,8 +43,8 @@ git submodule update --init --recursive
 ```bash
 # might need to rerun this when code is updated
 pnpm install
-# copy vendors dist libs to public directory
-pnpm --filter @readest/readest-app setup-vendors
+# copy pdfjs-dist to Next.js public directory
+pnpm --filter @readest/readest-app setup-pdfjs
 ```
 
 #### 3. Verify Dependencies Installation
@@ -86,7 +86,7 @@ Recommended Visual Studio Code plugins for development:
 
 - JavaScript and TypeScript Nightly (ms-vscode.vscode-typescript-next)
 - VS Code ESLint extension (dbaeumer.vscode-eslint)
-- Biome - Code formatter and linter (biomejs.biome)
+- Prettier - Code formatter (esbenp.prettier-vscode)
 - rust-analyzer (rust-lang.rust-analyzer) (for Tauri development only)
 
 ### When you're done

Cargo.toml

@@ -1,42 +1,3 @@
 [workspace]
-members = [
-  "apps/readest-app/src-tauri",
-  "packages/tauri/crates/tauri",
-  "packages/tauri-plugins/plugins/fs"
-]
-exclude = [
-  "packages/qcms"
-]
+members = ["apps/readest-app/src-tauri"]
 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

@@ -1,71 +0,0 @@
-FROM docker.io/library/node:24-slim@sha256:24dc26ef1e3c3690f27ebc4136c9c186c3133b25563ae4d7f0692e4d1fe5db0e AS dependencies
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-RUN corepack prepare pnpm@11.1.1 --activate
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
-COPY apps/readest-app/package.json ./apps/readest-app/
-COPY patches/ ./patches/
-COPY packages/ ./packages/
-RUN --mount=type=cache,id=pnpm,sharing=locked,target=/pnpm/store pnpm install --frozen-lockfile
-RUN test -f packages/foliate-js/vendor/pdfjs/annotation_layer_builder.css \
-    && test -d packages/simplecc-wasm/dist/web \
-    || { printf '\nERROR: Required git submodules are not initialized in the source directory.\nEnsure submodules are initialized before running docker build.\nRun: git submodule update --init packages/foliate-js packages/simplecc-wasm\n\n'; exit 1; }
-RUN pnpm --filter @readest/readest-app setup-vendors
-
-FROM docker.io/library/node:24-slim@sha256:24dc26ef1e3c3690f27ebc4136c9c186c3133b25563ae4d7f0692e4d1fe5db0e AS development-stage
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-RUN corepack prepare pnpm@11.1.1 --activate
-WORKDIR /app
-COPY --from=dependencies /app /app
-COPY . .
-WORKDIR /app/apps/readest-app
-EXPOSE 3000
-ENTRYPOINT ["pnpm", "dev-web", "-H", "0.0.0.0"]
-
-FROM docker.io/library/node:24-slim@sha256:24dc26ef1e3c3690f27ebc4136c9c186c3133b25563ae4d7f0692e4d1fe5db0e AS build
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-RUN corepack prepare pnpm@11.1.1 --activate
-WORKDIR /app
-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
-# Opt into the self-contained `.next/standalone` tree for this image only;
-# next.config.mjs gates `output: 'standalone'` on BUILD_STANDALONE so other
-# web builds keep their default output.
-ENV BUILD_STANDALONE=true
-RUN pnpm build-web
-
-# Production runtime ships only the standalone server, its traced node_modules,
-# and the static/public assets — no pnpm, no source tree, no dev dependencies,
-# no build cache. `output: 'standalone'` (next.config.mjs) emits the self-contained
-# tree under .next/standalone, so the entrypoint is a plain `node server.js`.
-FROM docker.io/library/node:24-slim@sha256:24dc26ef1e3c3690f27ebc4136c9c186c3133b25563ae4d7f0692e4d1fe5db0e AS production-stage
-ENV NODE_ENV=production
-ENV PORT=3000
-ENV HOSTNAME=0.0.0.0
-WORKDIR /app
-# Monorepo-rooted standalone tree: server.js + hoisted, traced node_modules.
-COPY --from=build --chown=node:node /app/apps/readest-app/.next/standalone ./
-# Static and public assets are not part of the standalone trace; copy them next
-# to the server so their default relative paths resolve.
-COPY --from=build --chown=node:node /app/apps/readest-app/.next/static ./apps/readest-app/.next/static
-COPY --from=build --chown=node:node /app/apps/readest-app/public ./apps/readest-app/public
-USER node
-EXPOSE 3000
-ENTRYPOINT ["node", "apps/readest-app/server.js"]

README.md

@@ -5,22 +5,17 @@
   <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 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.
+[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.
 
 [![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>
 
@@ -29,16 +24,14 @@
   <a href="#planned-features">Planned Features</a> •
   <a href="#screenshots">Screenshots</a> •
   <a href="#downloads">Downloads</a> •
-  <a href="#documentation">Documentation</a> •
   <a href="#getting-started">Getting Started</a> •
-  <a href="#troubleshooting">Troubleshooting</a> •
-  <a href="#support">Support</a> •
+  <a href="#contributors">Contributors</a> •
   <a href="#license">License</a>
 </p>
 
 <div align="center">
   <a href="https://readest.com" target="_blank">
-    <img src="./data/screenshots/landing_all_platforms.png" alt="Readest Banner" width="100%" />
+    <img src="./data/screenshots/landing_preview.png" alt="Readest Banner" width="100%" />
   </a>
 </div>
 
@@ -46,38 +39,38 @@
 
 <div align="left">✅ Implemented</div>
 
-| **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.                                        | ✅         |
+| **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.                             | ✅         |
+| **Sync across Platforms**               | Synchronize book files, reading progress, notes, and bookmarks across all supported platforms. | ✅         |
+| **Text-to-Speech (TTS) Support**        | Enable text-to-speech functionality for a more accessible reading experience.                  | ✅         |
 
 ## Planned Features
 
 <div align="left">🛠 Building</div>
 <div align="left">🔄 Planned</div>
 
-| **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.         | 🔄           |
+| **Feature**                     | **Description**                                                                            | **Priority** |
+| ------------------------------- | ------------------------------------------------------------------------------------------ | ------------ |
+| **Support iOS and Android**     | Expand the APP to work on iOS and Android devices.                                         | 🛠           |
+| **Library Management**          | Organize, sort, and manage your entire ebook library.                                      | 🛠           |
+| **AI-Powered Summarization**    | Generate summaries of books or chapters using AI for quick insights.                       | 🔄           |
+| **Sync with Koreader**          | Synchronize reading progress, notes, and bookmarks with [Koreader][link-koreader] devices. | 🔄           |
+| **Keyboard Navigation**         | Implement vimium-style keybindings for book navigation.                                    | 🔄           |
+| **Support OPDS/Calibre**        | Integrate OPDS/Calibre to access online libraries and catalogs.                            | 🔄           |
+| **Audiobook Support**           | Extend functionality to play and manage audiobooks.                                        | 🔄           |
+| **Handwriting Annotations**     | Add support for handwriting annotations using a pen on compatible devices.                 | 🔄           |
+| **Advanced Reading Stats**      | Track reading time, pages read, and more for detailed insights.                            | 🔄           |
+| **In-Library Full-Text Search** | Search across your entire ebook library to find topics and quotes.                         | 🔄           |
 
 Stay tuned for continuous improvements and updates! Contributions and suggestions are always welcome—let's build the ultimate reading experience together. 😊
 
@@ -85,41 +78,26 @@ 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)
 
+![TTS](./data/screenshots/tts_control.png)
+
 ![Footnote](./data/screenshots/footnote_popover.png)
 
 ![Wikipedia](./data/screenshots/wikipedia_vertical.png)
 
-![Theming Dark Mode](./data/screenshots/theming_dark_mode.png)
+![Themeing Dark Mode](./data/screenshots/theming_dark_mode.png)
 
 ---
 
 ## Downloads
 
-### Mobile Apps
+The Readest app is available for download! 🥳 🚀
 
-<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].
-
-## Documentation
-
-Guides, tutorials, and FAQs for installing and using Readest live in the official documentation:
-
-📖 **[https://readest.com/docs][link-docs]**
+- 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 👀
 
 ## Requirements
 
@@ -129,8 +107,8 @@ Guides, tutorials, and FAQs for installing and using Readest live in the officia
 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 v24
-nvm use v24
+nvm install v22
+nvm use v22
 npm install -g pnpm
 rustup update
 ```
@@ -144,16 +122,16 @@ To get started with Readest, follow these steps to clone and build the project.
 ```bash
 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 vendors dist libs to public directory
-pnpm --filter @readest/readest-app setup-vendors
+# copy pdfjs-dist to Next.js public directory
+pnpm --filter @readest/readest-app setup-pdfjs
 ```
 
 ### 3. Verify Dependencies Installation
@@ -171,51 +149,21 @@ 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
-pnpm tauri icon ../../data/icons/readest-book.png
-git checkout apps/readest-app/src-tauri/gen/android
-
-pnpm tauri android dev
-# or if you want to dev on a real device
-pnpm tauri android dev --host
 ```
 
 For iOS:
 
 ```bash
-# Set up the iOS environment (run once)
-pnpm tauri ios init
-pnpm tauri icon ../../data/icons/readest-book.png
-
 pnpm tauri ios dev
-# or if you want to dev on a real device
-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
@@ -231,101 +179,34 @@ nix develop ./ops#android # enter a dev shell for the android app
 
 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/readest/readest/graphs/contributors">
   <p align="left">
-    <img width="500" src="https://contrib.rocks/image?repo=readest/readest" alt="A table of avatars from the project's contributors" />
+    <img width="300" 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 at [donate.readest.com](https://donate.readest.com), where you'll find all available donation methods, including GitHub Sponsors, card payments, and crypto. Your contribution helps us fix bugs faster, improve performance, and keep building great features.
-
 ## 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 libraries and frameworks are used in this software:
+The following libraries and software 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.
+- [react-icons](https://github.com/react-icons/react-icons), which has various open-source licenses.
 - [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.
+[Bitter](https://fonts.google.com/?query=Bitter), [Fira Code](https://fonts.google.com/?query=Fira+Code), [Literata](https://fonts.google.com/?query=Literata), [Merriweather](https://fonts.google.com/?query=Merriweather), [Noto Sans](https://fonts.google.com/?query=Noto+Sans), [Roboto](https://fonts.google.com/?query=Roboto), [LXGW WenKai](https://github.com/lxgw/LxgwWenKai), [MiSans](https://hyperos.mi.com/font/en/), [Source Han](https://github.com/adobe-fonts/source-han-sans/), [WenQuanYi Micro Hei](http://wenq.org/wqy2/)
 
 ---
 
@@ -333,23 +214,15 @@ We would also like to thank the [Web Chinese Fonts Plan](https://chinese-font.ne
 
 [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/badge/license-AGPL--3.0-teal
-[badge-release]: https://img.shields.io/github/v/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-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%20Web%2C%20PWA-green
+[badge-last-commit]: https://img.shields.io/github/last-commit/readest/readest?color=green
+[badge-commit-activity]: https://img.shields.io/github/commit-activity/m/readest/readest
 [badge-discord]: https://img.shields.io/discord/1314226120886976544?color=5865F2&label=discord&labelColor=black&logo=discord&logoColor=white&style=flat-square
-[badge-hellogithub]: https://abroad.hellogithub.com/v1/widgets/recommend.svg?rid=8a5b6ade2aee461a8bd94e59200682a7&claim_uid=eRLUbPOy2qZtDgw&theme=small
-[badge-donate]: https://donate.readest.com/badge.svg
-[badge-deepwiki]: https://deepwiki.com/badge.svg
-[badge-reddit]: https://img.shields.io/reddit/subreddit-subscribers/readest?style=flat&logo=reddit&color=F37E41
-[badge-language-coverage]: https://img.shields.io/badge/coverage-53%25%20population%20🌍-green
-[link-donate]: https://donate.readest.com/?tickers=btc%2Ceth%2Csol%2Cusdc
-[link-appstore]: https://apps.apple.com/app/apple-store/id6738622779?pt=127463130&ct=github&mt=8
+[link-macos-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-docs]: https://readest.com/docs
 [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
@@ -357,8 +230,3 @@ We would also like to thank the [Web Chinese Fonts Plan](https://chinese-font.ne
 [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

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

apps/readest-app/.agents/memory

@@ -1 +0,0 @@
-../.claude/memory

apps/readest-app/.agents/plans

@@ -1 +0,0 @@
-../.claude/plans

apps/readest-app/.agents/rules

@@ -1 +0,0 @@
-../.claude/rules

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

@@ -1,148 +0,0 @@
-# Readest Project Memory
-
-## Key Reference Documents (aggregators)
-- [Bug Patterns](bug-patterns.md) · [CSS & Style](css-style-fixes.md) — EPUB CSS + style.ts · [TTS](tts-fixes.md)
-- [Layout & UI](layout-ui-fixes.md) — insets/z-index · [Platform Compat](platform-compat-fixes.md) — Android/iOS/Linux/macOS · [Annotator & Reader](annotator-reader-fixes.md)
-## Safety & Security
-- [In-place delete wiped originals](in-place-delete-wiped-originals.md) — never `fs.removeFile` `external` source;
-- [Backup zip Windows paths (#4703)](backup-windows-zip-paths-4703.md) — `\` entry names broke restore; normalize
-- [download_file scope Android (#4639)](download-file-scope-android-regression.md) — strict `is_allowed` broke
-- [Security advisories 2026-06](security-advisories-web-2026-06.md) — 4 GHSA #4638 (OPDS SSRF, storage key, Stripe
-## Paginator & Scroll
-- [Reading ruler line-aware](reading-ruler-line-aware.md) — snaps to real lines; iframe frame-offset map
-- [TOC expand + auto-scroll](toc-expand-and-autoscroll.md) — #4059 collapse-default breaks scroll-to-current
-- [BooknoteView auto-scroll (#4352)](booknote-view-autoscroll-4352.md) — reload via `initialized` ref;
-- [TOC current-position row](toc-current-position-row.md) — synthetic row; insert AFTER to keep flatItems index
-- [Swipe page-turn bg flash](paginator-swipe-bg-flash.md) — static `#background`; `computeBackgroundSegments` per-rAF
-- [Paginated texture occlusion (#4399)](paginated-texture-occlusion-4399.md) — opaque bg occludes texture; `hasTexture
-- [Background overflows column (#4394)](paginator-gutter-bleed-asymmetry-4394.md) — bg bled into gutter; clamp to
-- [Inline-block column overflow](inline-block-column-overflow.md) — body can't fragment; `#demoteUnfragmentableBoxes`
-- [FXL fit-width scroll reset (#4683)](fixed-layout-paginated-scroll-reset-4683.md) — scrollTop not reset;
-- [PDF spread 1px seam (#4587)](pdf-spread-canvas-seam-4587.md) — fractional dpr truncates; pin `canvas.style=viewport`
-- [PDF scrolled wheel double (#4727)](pdf-scroll-mode-wheel-double-4727.md) — drop manual `scrollBy` over native
-- [Scrolled header title center (#4436)](scrolled-header-title-center-4436.md) — view covering `renderedStart + size/2`
-- [Duokan fullscreen cover scroll](duokan-fullscreen-cover-scroll.md) — #4379 cover collapses; gate on `this.#column`
-- [TOC table heading clip (#4439)](toc-table-heading-clip-4439.md) — #4400 scroll-wrapper `overflow:auto` clips
-- [Page-turn bg-replace reflow (#4785)](pageturn-bg-replace-reflow-4785.md) — `#replaceBackground` rebuilt context per
-## Critical Files (Most Bug-Prone)
-- `src/utils/style.ts` EPUB CSS hub · `packages/foliate-js/paginator.js` layout/image/bg · `src/services/tts/TTSController.ts` TTS state machine
-- `src/hooks/useSafeAreaInsets.ts` insets · `src/app/reader/components/FoliateViewer.tsx` view orchestration · `.../annotator/Annotator.tsx` annotation lifecycle
-## Sync Notes
-- [Grimmory native sync](grimmory-native-sync.md) — Booklore-fork REVERTED; id by ISBN/ASIN + koreader-hash
-- KOSync: [CFI spine resolution](kosync-cfi-spine-resolution.md) convert via CFI's own spine; [connect() false-positive #4692](kosync-connect-false-positive-4692.md)
-- [Empty-start CFI sync](empty-start-cfi-sync.md) — `isMalformedLocationCfi` → discard synced value
-- [Custom fonts vanish on sync (#4410)](custom-fonts-reincarnation-4410.md) — CRDT remove-wins; re-import
-- koplugin: [note deletion](koplugin-note-deletion-sync.md) `recordDeletion` tombstone; [stats #4666](koplugin-stats-sync.md) statistics.sqlite3 delta LuaSettings; [bulk download #4751](koplugin-bulk-download-4751.md)
-- [Statusless books re-pin top (#4677)](sync-statusless-book-rebump-4677.md) — `(a??null)!==(b??null)`
-- [Pull cursor via synced_at (#4678)](sync-synced-at-cursor-4678.md) — books `synced_at` + BEFORE trigger
-- [WebDAV metadata sync (#4756)](webdav-metadata-sync-4756.md) — PR #4776; LWW on `book.updatedAt` +
-- [File-sync refactor (#4784)](webdav-filesync-refactor-plan.md) — `FileSyncEngine`/`FileSyncProvider`/`merge.ts`;
-- [Third-party library auto-sync (#4835)](third-party-library-autosync-4835.md) — `useLibraryFileSync` parity w/
-- [WebDAV connect nullified (#4780)](webdav-connect-nullified-4780.md) — catch+finally saved STALE closure;
-- [WebDAV credential sync (#4810)](webdav-credential-sync-4810.md) — `webdav.*` missing from
-- [Multi-window settings clobber (#4580)](multiwindow-settings-clobber-4580.md) — stale window overwrites shared
-- Google Drive: [research](gdrive-sync-provider-research.md) Drive as `FileSyncProvider` token-persist+resumable; [multi-PR status](gdrive-provider-multipr-status.md)
-- [Hardcover progress edition_id (#4792)](hardcover-progress-edition-id-4792.md) — `edition_id` fell back to
-## Build, Testing & CI
-- [format:check separate gate](verify-format-check-gate.md) — `pnpm format:check` own gate before push
-- [Worktree rebase submodule drift](worktree-rebase-submodule-drift.md) — rebase leaves foliate-js submodule old; `git
-- [Android CDP e2e lane](android-cdp-e2e-lane.md) — `pnpm test:android` adb+CDP; CI KVM emulator
-- [CDP Android WebView profiling](cdp-android-webview-profiling.md) — adb+CDP JS probes; locked-device freezes fetch
-- [Tauri Rust↔JS parser parity](tauri-parser-parity-tests.md) — #4369 cross-check; `dcterms:modified`→`published`
-- [TTS browser e2e harness](tts-browser-e2e-harness.md) — seed `settings.globalViewSettings` or getMergedRules crashes
-- [TTS paragraph+RSVP sync (#3235)](tts-sync-paragraph-rsvp-3235.md) — TTS-is-clock; overlay CLONE via CSS Custom
-- [fastlane App Store](fastlane-apple-appstore-submission.md) — keep `APPLE_API_KEY_PATH` out of macOS build env
-- [Turbopack cache OOM (#4619)](turbopack-build-cache-oom-docker-standalone.md) — partial cache freeze; gate on
-- [Deps override workflow](deps-security-overrides-workflow.md) — overrides in `pnpm-workspace.yaml`; tauri-plugins
-- [pdfjs vendor wasm](pdfjs-vendor-wasm-decoders.md) — pdfjs 5.7 moved JBIG2 to `jbig2.wasm`; copy `wasm/*`
-- [CI/PR delivery + push keepalive](ci-pr-delivery-and-push.md) — temp-index plumbing; SSH `ServerAliveInterval`
-## Platform Compat
-- [Android hyphen selection (#1553)](android-hyphen-selection-bounds-1553.md) — Blink start handle on last hyphen;
-- [NativeFile vs RemoteFile I/O](android-nativefile-remotefile-io.md) — NativeFile slow; asset Range broken;
-- [Window-state sanitizer (#4398)](window-state-sanitize-4398.md) — invalid json crashes WebView2; sanitize before
-- [Android Open-with intent (#4521)](android-open-with-intent-flow.md) — VIEW gated by `autoImportBooksOnOpen`
-- [Dict lookup browser hijack (#4559)](dict-lookup-browser-hijack-4559.md) — missing `<queries>` sdk36; filter in
-- [Large-PDF OOM range flood (#3470)](pdf-oom-range-flood-3470.md) — un-awaited ranges OOM; MAX_CONCURRENT_RANGES=6
-- [Android themed icon (#4733)](android-themed-icon-4733.md) — no monochrome → force-commit; tint=SRC_IN
-## Reader Features & UI
-- [Mobile reading widgets (#1602/PR#4842)](mobile-reading-widgets.md) — home-screen widget iOS+Android; gotchas: iOS
-- [PDF scrolled-mode lag (#4795/#4031)](pdf-scroll-lag-preload-4795.md) — 415ms/page render vs 50% margin; widen to
-- [Scrolled-PDF pinch-zoom (#4817)](scrolled-pdf-pinch-zoom-4817.md) — live pinch + no-shift (gap×`--scroll-zoom` +
-- [Search modes #4560 + spoiler-bound bug](search-modes-4560-and-spoiler-bound-bug.md) — regex + nearby-words;
-- [OPDS groups carousel (#4750)](opds-groups-carousel-4750.md) — >=2 groups → virtuoso carousel; `scrollToIndex`
-- [WebDAV browser sort + search (#4724)](webdav-browse-sort-search-4724.md) — PR #4786;
-- [Image zoom trackpad flicker (#4742)](image-zoom-trackpad-flicker-4742.md) — macOS pinch=`ctrl+wheel`;
-- [Instant Highlight ate tap/swipe](instant-highlight-tap-paginate.md) — preventDefault killed tap-paginate;
-- [Keyboard selection adjust (#4728)](keyboard-selection-adjust-4728.md) — Shift+←/→ char, Ctrl/Alt+Shift word;
-- [Double-click word select](iframe-double-click-word-select.md) — orphaned `iframe-double-click` →
-- [Cross-page selection auto-turn (#4741)](cross-page-selection-autoturn-4741.md) — `useAutoPageTurn` dwell;
-- [Annotator onLoad listener leak (#4735)](annotator-onload-listener-leak-paragraph-mode.md) — `useRendererInputListener
-- [Paragraph mode toggle/resume (#4717)](paragraph-mode-toggle-resume-4717.md) — snapshot live Set; resume from fresh
-- [Paragraph-mode accidental exit (#4474)](paragraph-mode-accidental-exit-4474.md) — `paragraph-show-controls`; bar
-- [#4584 tap-death](issue-4584-tap-death-investigation.md) — UNFIXED; `isPopuped` RED HERRING; likely WebView-148
-- [Dblclick-drag turns page (#4524)](dblclick-drag-pageturn-4524.md) — `isMouseDown` gates `postSingleClick`
-- [Tap to open image/table (#4600)](tap-to-open-image-table-4600.md) — `iframe-open-media` + `detectMediaTarget`
-- [PDF/CBZ Contrast view-menu](pdf-cbz-contrast-view-menu.md) — per-book `contrast`; ONE `filter:` (invert+contrast);
-- [iOS instant-dict double popup](ios-instant-dict-double-popup.md) — once-per-gesture latch; `isLongPressHold` 300ms
-- Dict: [popup font size #4443](dict-popup-font-size-4443.md) `--dict-font-scale` MDict `::part(dict-content)`; [lemmatization #4574](dict-lemmatization-4574.md)
-- Word Lens: [inline gloss](wordlens-feature.md) CFI-safe `<ruby cfi-skip>…<rt cfi-inert>` TTS/search isolation; [en-en](wordlens-en-en.md)
-- [Stripe highest-active plan (#4694)](stripe-plan-highest-active-4694.md) — `plans.plan` = MAX over active subs
-- [Save image to gallery (#4680)](save-image-to-gallery-android.md) — MediaStore; sharekit 0-byte self-copy
-- [Webtoon Mode (#3647)](webtoon-mode-3647.md) — no-gap scrolled images; FXL fit-width; `--scroll-page-gap`
-- [Biometric app-lock (#4645)](biometric-app-lock-4645.md) — flag from `appLockStore`; plugin `cfg(mobile)`
-- [Reference Pages (#4542)](reference-pages-672-4542.md) — 'reference' progressStyle; `referencePageCount`
-- [E-ink screen refresh page-turner (#4687)](eink-screen-refresh-pageturner-4687.md) — bindable 'refresh' action;
-- [Share intent + toolbar (#4014)](annotation-share-toolbar-4014.md) — Share gated mobile+macOS;
-- [Instant highlight delete orphan (#4773)](instant-highlight-delete-orphan-4773.md) — stale memoized index + in-place
-- [Empty highlight leak on annotate cancel (#4791)](empty-highlight-leak-on-annotate-cancel-4791.md) — Annotate
-- [Customize Toolbar global (#4760)](customize-toolbar-global-serializeconfig.md) — `serializeConfig` ref-compare →
-- [Customize Toolbar e-ink black bar (#4839)](customize-toolbar-eink-black-bar-4839.md) — preview Zone copied
-- Native TTS: [iOS #4676](native-ios-tts-4676.md) AVSpeechSynthesizer pause==stop rate `pow^(1/2.5)`; [offline halt #4613](native-tts-offline-autoadvance-4613.md)
-- Edge TTS: [word highlight #4017](edge-tts-word-highlighting-4017.md) `audio.metadata` WordBoundary by rAF gate on UA; [drift](tts-word-highlight-singletextnode-drift.md)
-- [TTS highlight granularity setting](tts-highlight-granularity-setting.md) — Word/Sentence; gate `prepareSpeakWords`
-- [TTS start-from-selection](tts-start-from-selection.md) — use last mark at/before sel; cloneRange+deselect
-- [Reuse TTS session on mode entry](tts-reuse-session-mode-entry.md) — `redispatchPosition()` + `tts-sync-request`
-- RSVP: [control-bar overlap REVERT](rsvp-control-bar-overlap-revert.md) #4585 fixed/#4589 stale-reverted; [font face/family #4519](rsvp-font-settings-4519.md) `getBaseFontFamily` overlay top doc; [RTL word #4630](rsvp-rtl-word-display-4630.md)
-- [Overlay z-index scale](zindex-overlay-scale.md) — RSVP 100 / Settings 110 / ModalPortal 120 / toast 130 / app-lock
-- [Global annotation page-turn lag (#4575)](global-annotation-pageturn-perf-4575.md) — `global` re-fanned every turn;
-- [Overlayer splitRange text nodes](overlayer-splitrange-textnodes.md) — `'p,h1-h4'` dropped `li`; walk text nodes +
-- [Android image callout freeze](android-image-callout-freeze.md) — `.no-context-menu` on ANCESTOR
-- [Table dark-mode tint (#4419)](table-dark-mode-tint-4419.md) — `blockquote, table *` tint gated on `overrideColor`
-- [Footnote aside border line (#4438)](footnote-aside-namespace-order-4438.md) — @font-face before @namespace; hoist
-- Proofread: [enhancements #4700](proofread-enhancements-4700.md) regex UI/Ctrl+P reuse/`wholeWord` no-op; [per-book CRDT #4781](proofread-per-book-crdt-sync.md)
-- [Russian hanging-preposition NBSP (#4769)](russian-hanging-prepositions-nbsp-4769.md) — generic `nbsp` +
-- OPDS: [Firefox strict-XML #4479](opds-firefox-strict-xml-4479.md) junk after `</feed>` slice to last close; [JSON search #4502](opds2-json-search-4502.md) expand `{?query}` BEFORE resolveURL; [HTML desc #4503](opds-html-description-4503.md) decode-once+sanitize; [self-link meta #4749](opds-self-link-metadata-4749.md) `rel:self` deref; [popular dedup #4782](opds-popular-catalog-dedup-4782.md)
-- [D-pad Navigation](dpad-navigation.md) — Android TV remote / arrow-key nav
-- [koplugin cover upload (#4374)](koplugin-cover-upload.md) — `extractLocalCover` via `getCoverImage`
-## Library Fixes
-- [Book action platform surfaces](book-actions-platform-surfaces.md) — context menu Tauri-desktop-only; cross-platform
-- [Tauri menu append race (#4389)](tauri-menu-append-race-4389.md) — single `await Menu.new({ items })`
-- TXT: [author recognition #4390](txt-author-recognition-4390.md) `parseLabeledAuthor`+`isPlausibleAuthorName`; [chapter measure-word FP #4658](txt-chapter-measure-word-4658.md)
-- [Cover stale (in-place mutation)](cover-stale-inplace-mutation-memo.md) — pure `getBookWithUpdatedMetadata`
-- [Series/author back no-op (#4437)](series-folder-back-noop-4437.md) — Next 16.2 empty-search no-op; `handleBack`
-- [Library/reader separate texture (#4743)](library-reader-separate-texture-4743.md) — `libraryBackground*`
-- [List view series overflow (#4796)](list-view-series-overflow-4796.md) — fixed `h-28` clipped series+description
-- [Recently-read shelf (#3797)](recent-read-shelf-3797.md) — PR #4829; reuse `BookItem` + shared `useOpenBook`; flex
-## Architecture & Patterns
-- foliate-js submodule at `packages/foliate-js/`; multiview paginator preloads adjacent sections
-- [Markdown .md support (#774)](markdown-md-support-774.md) — in-memory foliate book (no EPUB) in `src/utils/md.ts`;
-- Style: `getLayoutStyles()` always, `getColorStyles()` when overriding color; `transformStylesheet()` rewrites EPUB CSS at load
-- TTS independent section tracking (`#ttsSectionIndex`); safe insets: native plugin → useSafeAreaInsets → styles; Dropdowns `DropdownContext`
-- Stale settings closure: store-hook `settings` stale across `await`; persist `useSettingsStore.getState().settings` ([#4780](webdav-connect-nullified-4780.md)
-- [Foliate touch-listener capture phase](foliate-touch-listener-capture-phase.md) — suppress gestures via
-- [iframe cross-realm instanceof](iframe-cross-realm-instanceof.md) — `instanceof Element` false; duck-type `'closest'
-- [Virtuoso + OverlayScrollbars](virtuoso_overlayscrollbars.md) — useOverlayScrollbars for mobile webviews
-- [Design system → DESIGN.md](feedback_design_system_doc.md) — never `pl/pr/ml/mr/text-left/right` (RTL)
-## Workflow & Feedback
-- [Commit messages English-only](feedback-commit-message-english-only.md) — English only (no CJK, no em/en dashes)
-- [Test file filter](feedback_test_file_filter.md) — `pnpm test <path>` without `--` runs one file
-- [Rebase before PR](feedback_pr_rebase.md) — rebase onto origin/main before PRs
-- [New branch per PR](feedback_pr_new_branch.md) — fresh branch from main per PR/issue
-- [Use worktree](feedback_use_worktree.md) — never `git worktree add`; always `pnpm worktree:new`
-- [Never push every change](feedback_dont_push_every_change.md) — commit locally until user confirms
-- [No test seams in prod](feedback_no_test_seams_in_prod.md) — prod never imports `__reset*ForTests`
-- [No lookbehind regex](feedback_no_lookbehind_regex.md) — never `(?<=)`/`(?<!)`; build check rejects
-- [en plurals manual](feedback_en_plurals_manual.md) — only plural variants + proper nouns; `_one`/`_other`
-- [i18n:extract prunes keys](i18n-extract-prunes-keys.md) — `removeUnusedKeys` deletes valid keys; revert churn, add
-- [Dependabot transitive fixes](dependabot-pnpm-overrides.md) — pin in `pnpm-workspace.yaml` `overrides:`; alert#≠issue#
-- [Upgrade gstack locally](feedback_gstack_upgrade.md) — upgrade from project `.claude/skills/gstack`

apps/readest-app/.claude/memory/android-cdp-e2e-lane.md

@@ -1,21 +0,0 @@
----
-name: android-cdp-e2e-lane
-description: "pnpm test:android — CDP+adb e2e lane driving the installed app on a device/emulator; harness design, gotchas, CI workflow"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 16f94822-04b0-4be3-a47e-8a2e3cab290a
----
-
-New test tier (PR #4545, merged 2026-06-12): `pnpm test:android` → `scripts/test-android.sh` → `vitest.android.config.mts` (node env, serial, retry 1) → `src/__tests__/android/*.android.test.ts`. Helpers in `src/__tests__/android/helpers/`: `adb.ts` (tap/longPress/`motionGesture` = one-shell DOWN/MOVE/UP chain), `cdp.ts` (forward `webview_devtools_remote_<pid>`, node:http discovery with Host header, `CdpPage.evaluate` async-IIFE), `reader.ts` (fixture open + probes). Soft-skips without adb/device/app. Covers the [[android-hyphen-selection-bounds-1553]] cases: prone long-press → app handles, drag repair clamp, tap dismissal, handle-drag extension, mid-paragraph native handles, cross-page corner-dwell auto-turn.
-
-Design principles (per chrox): discover-don't-assume (find a hyphenated on-screen paragraph at runtime, start in main text via `gotoChapter('chapter\\s*4')`), force hyphenation by injecting `p{hyphens:auto!important;text-align:justify!important}` into section docs (app settings irrelevant), poll-don't-sleep (`waitFor`), fixture `sample-alice.epub` opened TRANSIENTLY via MediaStore VIEW intent.
-
-Gotchas:
-- MediaStore `_data` is the canonical `/storage/emulated/0/...` path — query `_data LIKE '%/<basename>'`, NOT the `/sdcard/` symlink you pushed to. `content query --projection` takes ONE column or space-separated (not comma). VIEW with `--grant-read-uri-permission` works on a permissionless fresh install.
-- Multi-section books: each section is its own iframe — record + restore pagination via the TARGET section's frame x (`c.index === sectionIndex`), not `contents[0]`.
-- Corner auto-turn (#1354) zone is the reading area INSET by content margins — a drag point in the bottom margin is ignored by `cornerAt`; aim ~4% inside the text area.
-- adb `input motionevent` 5px moves are under touch slop → no pointermove; make post-turn drag movements large.
-- Verified green on Xiaomi 13 (physical) AND fresh Pixel_9_Pro AVD (`emulator -avd Pixel_9_Pro`, install the aarch64 dev APK), ~21 s.
-
-CI: `.github/workflows/android-e2e.yml` — ubuntu-latest + KVM udev rule, debug x86_64 APK (`tauri android build --debug --target x86_64`; gradle skips keystore.properties when absent so NO signing secrets), `reactivecircus/android-emulator-runner@v2` (api 34, AVD snapshot cached), nightly + workflow_dispatch + `e2e-android` PR label; not PR-blocking. NOTE: emulator-runner not SHA-pinned yet (repo convention pins by SHA).

apps/readest-app/.claude/memory/android-hyphen-selection-bounds-1553.md

@@ -1,30 +0,0 @@
----
-name: android-hyphen-selection-bounds-1553
-description: "#1553 Android selection breaks on first word of hyphenated paragraphs — Blink generated-hyphen bounds bug, full RCA + app-side repair/suppress fix"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 16f94822-04b0-4be3-a47e-8a2e3cab290a
----
-
-Issue #1553 root cause (verified live on Xiaomi 13, WebView 147, via [[cdp-android-webview-profiling]]):
-
-**Upstream**: filed as crbug **522869957** (2026-06-12, by chrox, with full analysis + repro + screenshot). Pre-existing same-root-cause report: crbug **41496034** (Jan 2024, "­" framing — why searches missed it; P2 Available, on "Rendering Core 2026 Fixit" hotlist; MS triager confirmed soft-hyphen cause in Feb 2024). Cross-link comments posted on both.
-
-**Blink bug** — `LayoutSelection::ComputePaintingSelectionStateForCursor` (third_party/blink/renderer/core/editing/layout_selection.cc) compares `paint_range_` offsets (paragraph **IFC text-content space**, via `OffsetMapping::GetTextContentOffset`) against `position.TextOffset()` — but auto/soft-hyphen fragments are **layout-generated text with self-relative offsets {0,1}**. So a touch selection starting at IFC offset 0 (first word of a paragraph) makes EVERY hyphen fragment in that paragraph report `kStart` → each records a start bound (`SelectionBoundsRecorder`, last paint wins) → **native start handle is drawn at the paragraph's LAST hyphen**. The highlight itself is correct because the sibling path `ComputeSelectionStatus(InlineCursor&)` HAS the `IsLayoutGeneratedText()` remap; the bounds path lacks it. Still unfixed upstream as of Chromium main (June 2026); seemingly unreported.
-
-Key facts:
-- Trigger: touch selection (handles visible — `ShouldRecordSelection` gates on `IsHandleVisible()`, so desktop/mouse unaffected; iOS=WebKit unaffected) + selection start at IFC offset ≤1 + generated hyphens in the same paragraph. **Multicol NOT required** (reproduced in a plain top-document div).
-- Worse than cosmetic: long-press **drag-extension re-anchors the base by hit-testing the bogus bound** → observed anchor jump 0→325 (offset just before last hyphen), selection became [53,325] instead of [0,53]. Explains "select upward works" workaround (upward drags anchor on the correct end bound).
-- Auto-hyphens show up as separate ~0.3em rects in `Range.getClientRects()` on hyphenated lines — usable as a generated-hyphen detector.
-- **JS `removeAllRanges()+addRange()` does NOT hide already-visible touch handles synchronously** — the empty selection must commit through one painted frame (double-rAF in the iframe window) before re-adding; then handles stay hidden for all later JS selection updates.
-
-Fix (**PR #4545, MERGED 2026-06-12**; worktree cleaned): detection utils in `src/utils/sel.ts` (`isHyphenHandleBugProneRange`, `repairJumpedSelectionRange`, `hasTrailingHyphenRectPattern`); gesture-initial anchor capture + touchend sanitize in `useTextSelector` (repair jumped anchor → suppress handles via empty-commit → `makeSelection(handlesSuppressed)`); `SelectionRangeEditor.tsx` renders custom drag handles (reuses `Handle` + extracted `buildRangeFromPoints`/`getHandlePositionsFromRange` in annotatorUtil) for suppressed selections. Gated to Android app + exact bug condition; flipping to always-custom-handles later = drop the proneness gate.
-
-Gotcha: `input motionevent DOWN/MOVE/UP` (adb) simulates long-press-drag; `input swipe x y x y 700` simulates plain long-press.
-
-Two post-fix races found by chrox & fixed (commits c6e9f48, 9a63157):
-1. **Tap-dismiss resurrection** — an Android tap doesn't clear the selection, it COLLAPSES it to a caret at the tap point, with selectionchange ~10-20ms AFTER touchend; the tap's touchend re-entered sanitize (fallback prone-check on the still-valid old selection), the collapse raced into the double-rAF window (also MUTATING the held Range in place), and makeSelection committed a collapsed range as a suppressed selection → "empty custom handles at the tap spot". Fix = gesture gate (`if (!initial) return`) + post-rAF abort when `sel.rangeCount > 0 || finalRange.collapsed`.
-2. **Extent overshoot** — the corrupted drag has TWO modes: base re-anchors at the bogus bound (anchor jump, Argentina test) OR the EXTENT lands there while the anchor stays at 0 (range then CONTAINS the initial anchor → jump-repair doesn't fire; observed +1013 chars). Fix = `rangeFromAnchorToPoint`: rebuild [gesture-initial anchor → caret at last native touch position] (`pointerPos`, reset per-gesture in handleTouchStart), fallback to jump-repair.
-
-Verify-build gotcha: `pnpm dev-android` snapshots the Next bundle at build START — an amend after kickoff ships the PRE-amend frontend (grep of out/ chunks for comment text is a FALSE-POSITIVE check; compare out/ mtime vs commit time instead).

apps/readest-app/.claude/memory/android-image-callout-freeze.md

@@ -1,31 +0,0 @@
----
-name: android-image-callout-freeze
-description: "Android WebView native long-press image callout collides with app touch handlers and freezes the app; reusable `.no-context-menu` fix"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 50bec34f-7090-4bf4-a194-9bf4029527bf
----
-
-Recurring Android-only freeze: long-pressing an `<img>` triggers the WebView's
-native image callout (context menu / drag / magnifier) which collides with the
-app's own touch handlers (long-press multi-select, or pinch/pan) and freezes the
-whole app until restart.
-
-**Root cause:** `-webkit-touch-callout: none` does NOT inherit, so a
-`.no-context-menu` class on a *container* never reaches descendant images.
-
-**Fix:** the `.no-context-menu img, .no-context-menu a` rule in
-`src/styles/globals.css` (sets `-webkit-touch-callout: none; -webkit-user-drag:
-none; user-select: none`). Apply the `no-context-menu` class to an *ancestor* of
-the image so the descendant rule reaches it. Harmless on desktop
-(`-webkit-touch-callout` is a no-op there; right-click-save still works).
-
-Occurrences so far:
-- Book covers on the bookshelf — PR #4345 (`BookshelfItem.tsx`, gated on
-  `appService?.isMobileApp`; added the `.no-context-menu img` rule).
-- Image preview / zoom viewer — issue #4420, `ImageViewer.tsx` root container
-  (applied unconditionally — no selectable text there, so no need to gate).
-
-**How to apply:** when a new "Android freezes on long-press of an image" report
-comes in, find the `<img>` and put `no-context-menu` on a containing element.

apps/readest-app/.claude/memory/android-nativefile-remotefile-io.md

@@ -1,27 +0,0 @@
----
-name: android-nativefile-remotefile-io
-description: "Why NativeFile is slow on Android, why RemoteFile (range fetch) can't replace it (asset-protocol Range is broken), measured CDP numbers, and the viable speedups"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 8057ac9c-2e3e-446d-86aa-29baddfbfe66
----
-
-On-device investigation (Xiaomi 2211133C, Android 16, WebView/Chrome 147, wry 0.54.4) of `src/utils/file.ts` `NativeFile` vs `RemoteFile` Android I/O. Verified live via CDP injection into the running app's WebView.
-
-**Why NativeFile is slow (root cause):** `NativeFile.readData` → `#readAndCacheChunkSafe` does `open()+seek()+read()+close()` = **4 Tauri IPC round-trips per chunk**, opens a FRESH handle every chunk (never reuses `this.#handle`), and `read()` ships raw bytes across the Android Kotlin↔JS IPC bridge (serialization cost = the unresolved tauri-apps/tauri#9190). Code already notes "~400 ms per IPC round-trip" at `nativeAppService.ts:313`.
-
-**Can RemoteFile replace NativeFile on Android? NO** — and whole-file load is NOT an alternative (RemoteFile's whole point is random access WITHOUT loading the file into RAM). The Tauri/wry Android **asset protocol mishandles Range requests** (still true on WebView 147), which is exactly `RemoteFile.fetchRange`'s mechanism:
-- `Range: bytes=START-…` with **START ≥ 1024 → hard `TypeError: Failed to fetch`**; `0 ≤ START < 1024` → body truncated to `1024-START` bytes. Reading the zip central directory (EOF) / OPF / cover = non-zero offsets = all fail. "Known issue" at `nativeAppService.ts:244` — confirmed STILL broken.
-- **ROOT CAUSE (localized):** Tauri's `crates/tauri/src/protocol/asset.rs` range logic is CORRECT (seek+read [start,end], 206, Content-Range, Content-Length; `MAX_LEN=1000*1024` cap is BY DESIGN — RemoteFile already chunks at the same `MAX_RANGE_LEN`). The bug is in **wry `src/android/binding.rs`**: it STRIPS the `Content-Length` header ("WebResourceResponse will auto-generate") and hands Android a `ByteArrayInputStream` of the already-sliced partial body + a `Content-Range` header. The Android WebView then **double-applies the offset** (skips another `start` bytes) → `1024-start` truncation, empty body for start≥1024. **Unchanged through wry 0.55.1**, so bumping wry won't fix it; needs an upstream wry patch (or local vendor/patch) and fights Android's intercepted-206 quirks.
-- Plain `fetch(assetUrl)` (no Range) returns the full file fast — but loading the whole file defeats RemoteFile's purpose, so NOT a fix.
-
-**Measured (10 MB mobi, 1 MB chunks):** native fresh-handle **44 MB/s** (222 ms) · native one-handle **100 MB/s** (98 ms) · asset plain-fetch **281 MB/s** (35 ms, full file correct). Per-call 4 KB scattered read via NativeFile ≈ **16 ms/op** (kills imports doing many small reads). So: plain-fetch is **6.3×** native and **2.8×** one-handle; just reusing the handle is **2.3×**.
-
-**Per-IPC decomposition (warm):** open 1.33 ms, seek 0.60 ms, read(4 KB) 3.02 ms (read carries ~2.4 ms fixed bridge-serialization beyond the round-trip = the tauri#9190 ceiling), seek+read(1 MB) 8.18 ms.
-
-**SOLUTION (implemented, branch `feat/android-rangefile-protocol`, verified on-device):** a custom `rangefile` URI scheme (`src-tauri/src/range_file.rs`, registered via `register_asynchronous_uri_scheme_protocol`) that carries the byte range in the URL **query** (`http://rangefile.localhost/?path=&start=&end=`) instead of a `Range` header. With NO `Range` header the WebView does no offset re-application and delivers the 200 body verbatim — while bytes still stream through the WebView network stack (not the IPC bridge). Returns 200 + `X-Total-Size` (no `Content-Range`); scope-gated by `asset_protocol_scope().is_allowed()` (same security as asset protocol). TS side: `RemoteFile.fromNativePath(absPath)` (query-range mode, reads `X-Total-Size` on open, `&start=&end=` per fetch, no Range header); wired into `nativeAppService.openFile` Android branch with NativeFile fallback; CSP += `http://rangefile.localhost`.
-  - **Verified on Xiaomi/Android 16 via CDP:** byte-equal to NativeFile ground truth at ALL offsets (0,1,1024,64K,1M,5M,EOF) — the non-zero starts that failed via asset protocol now work; cache-safe across distinct ranges; real library book opens & renders end-to-end (50 rangefile requests, restored mid-file position). **1.83× faster** small scattered 4KB reads (5.2 vs 9.5 ms); bulk-sequential ≈ par (RemoteFile rarely does whole-file reads; native copyFile fast-path handles those). Why this beat the "200 trick" idea: pre-test showed the WebView re-applies the offset to 200 responses too — it's the *Range request header* that triggers it, so removing the header (range-in-URL) is the actual fix.
-  - Why this isn't the "single-call IPC command": IPC still pays the tauri#9190 bridge serialization; the rangefile path streams via the network stack. The IPC command (`open+seek+read+close` → 1 IPC, ~2× small reads) remains a valid simpler fallback if the custom scheme ever regresses.
-
-**Side-observation:** installed build's ACL rejects `plugin:fs|close` (allows open/seek/read) → possible `NativeFile` handle-leak / `close()` throw path; verify `fs:default` grants. See [[cdp-android-webview-profiling]].

apps/readest-app/.claude/memory/android-open-with-intent-flow.md

@@ -1,26 +0,0 @@
----
-name: android-open-with-intent-flow
-description: "Android \"Open with/Send to Readest\" intent pipeline + why Telegram/cloud-app opens differ from file-manager opens (issue"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 73ee84b7-27a0-4232-981c-de8235a15f07
----
-
-Android "Open with Readest" / "Send to Readest" file-intent pipeline and the #4521 ("open book from Telegram") diagnosis. Confirmed fixed by #4527.
-
-**Pipeline (ACTION_VIEW = "Open with", ACTION_SEND = "Share"):**
-- `NativeBridgePlugin.kt::handleIntent` is the real handler (NOT `MainActivity.kt` — its ACTION_SEND branch is legacy/redundant). → `emitSharedIntent("VIEW"|"SEND", uris)` → JS `useAppUrlIngress` `shared-intent` plugin listener → `app-incoming-url` event → `useOpenWithBooks`.
-- VIEW routing is now gated by `autoImportBooksOnOpen` (PR #4747, issue #4746): `shouldOpenTransient(action, autoImportBooksOnOpen)` in `helpers/openWith.ts` → only `VIEW` with the setting OFF goes `openTransient` (ephemeral book, `deletedAt` set, `filePath` = content:// URI, no library write/upload); `VIEW` with it ON falls through to the SEND path. SEND (and VIEW-with-import-on) → `window.OPEN_WITH_FILES` → `library/page.tsx::processOpenWithFiles` (full ingest + force cloud upload on mobile). The setting defaults TRUE on mobile (`DEFAULT_MOBILE_SYSTEM_SETTINGS`, desktop default still false) and its "Auto Import on File Open" toggle is now shown on mobile too. `useOpenWithBooks.handle` reads it via `appService.loadSettings()` (disk), NOT the settings store — the store is unhydrated during the cold-start intent replay and would wrongly fall back to transient. So the Telegram default is now import-to-library (persists past the dying URI grant); transient is opt-out.
-- content:// read: `nativeAppService.openFile` → if URI contains `com.android.externalstorage` → direct `NativeFile` (real path); else `copyURIToPath` → `contentResolver.openInputStream` → copy to Cache → `NativeFile`. `basename` here is LEXICAL (`@tauri-apps/api/path`), not a ContentResolver `DISPLAY_NAME` query — but EPUB format is sniffed by zip magic (`document.ts isZip()`), so an extension-less content URI still opens.
-- The Tauri deep-link plugin's `getCurrent()`/`onOpenUrl` only fire for configured deep-link domains (`https://web.readest.com`, `readest:`); `content://`/`file://` VIEW intents are filtered out by `DeepLinkPlugin.isDeepLink()`, so file opens flow ONLY through the native `shared-intent` channel, never the deep-link plugin.
-
-**#4521 root cause (Telegram open fails, file-manager works) — TWO independent axes:**
-1. **Cold-start delivery.** On cold launch the ACTION_VIEW intent reaches `handleIntent` before the JS `shared-intent` listener registers; upstream `Plugin.trigger()` drops events with no listener. **#4527** added queue+replay (`emitOrQueue`/`pendingEvents` + `registerListener` override) to fix it. **#4527 is on `dev` but NOT in released v0.11.4** (v0.11.4 has #4407 only) — the reporter's likely cause. Logs show `Queued shared-intent payload (no listener yet)` then `Replaying 1 queued event(s) after registerListener`.
-2. **Foreign-private-file read.** File-manager/MediaStore opens point at SHARED storage → Readest reads via real path / MediaProvider FUSE (it holds `MANAGE_EXTERNAL_STORAGE`), so the URI grant is irrelevant. Telegram/Gmail/Drive serve an APP-PRIVATE file via their own FileProvider with a TEMPORARY, non-persistable grant (`takePersistableUriPermission` throws → caught) → readable only in-session via `openInputStream`; the transient book's `content://` filePath then breaks on later reopen once the grant dies.
-
-**Verification gotcha (adb, no Telegram):** an adb MediaStore content-URI VIEW intent
-`adb shell am start -a android.intent.action.VIEW -d content://media/external/file/<id> -t application/epub+zip --grant-read-uri-permission -n com.bilingify.readest/.MainActivity`
-tests the pipeline (Axis 1) but CANNOT reproduce Axis 2 — shared-storage reads via FUSE bypass the grant, so it always succeeds. To reproduce the real failure use a foreign FileProvider source (Gmail/Drive/Outlook attachment "Open with Readest") or a tiny helper APK with its own FileProvider. Get the MediaStore `_id` via `adb shell content query --uri content://media/external/file --projection _id:_data | grep <name>` (MIUI `--where` chokes on `/storage/...` path tokens). Watch `adb logcat | grep -iE "NativeBridgePlugin|Open with FUSE|Failed to (open|import)|Queued|Replaying"`.
-
-Critical files: `src-tauri/plugins/tauri-plugin-native-bridge/android/src/main/java/NativeBridgePlugin.kt`, `src/hooks/useAppUrlIngress.ts`, `src/hooks/useOpenWithBooks.ts`, `src/services/nativeAppService.ts::openFile`, `src/services/bookContent.ts::resolveBookContentSource`.

apps/readest-app/.claude/memory/android-sideload-same-versioncode.md

@@ -1,14 +0,0 @@
----
-name: android-sideload-same-versioncode
-description: Android sideloaded APK reinstall allows EQUAL versionCode; only strictly-lower is blocked
-metadata: 
-  node_type: memory
-  type: reference
-  originSessionId: a58a4eba-7a3c-4560-9b52-e3713c6ad211
----
-
-Sideloaded APK installs (Readest's in-app updater path: `installPackage` → `Intent.ACTION_VIEW` with `application/vnd.android.package-archive` → system package installer, NOT Play Store) permit reinstalling an APK whose `versionCode` is **equal** to the currently installed one — it's an in-place reinstall/update as long as the signing certificate matches. Android's `INSTALL_FAILED_VERSION_DOWNGRADE` only triggers for a **strictly-lower** versionCode. (Play Store, by contrast, requires a strictly-incrementing versionCode — that constraint does NOT apply to sideload.)
-
-Consequence for the nightly update channel ([[android-open-with-intent-flow]] uses the same NativeBridge install path): Tauri derives `versionCode = major*1000000 + minor*1000 + patch`, dropping any prerelease suffix, so all nightlies on base `0.11.4` share `versionCode=11004`. That is FINE — they reinstall over each other and over stable `0.11.4`. Because the base only ever increases (0.11.4 → 0.11.5 → ...), nightly versionCode is monotonic non-decreasing, so there is never a downgrade. No need to derive a per-build versionCode from the date stamp. The app's `versionName` carries the full `0.11.4-2026061406` string, which is what the JS `getAppVersion()` updater comparison uses.
-
-A plausible-but-wrong review claim ("same versionCode means Android refuses the install as not-an-upgrade") confuses Play Store rules with sideload behavior. Corrected by the project owner 2026-06-14.

apps/readest-app/.claude/memory/android-themed-icon-4733.md

@@ -1,52 +0,0 @@
----
-name: android-themed-icon-4733
-description: "Android Material-You themed (monochrome) launcher icon — restoring it (#4733), the gen/android force-commit pipeline, and emulator verification"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 6bc82dac-a705-4ef2-ab28-c13b43f48a46
----
-
-Issue #4733 = add Android themed (Material You / monochrome) launcher icon. It had
-existed (#2122/#2153 added `ic_launcher_monochrome.png`) but PR #2353 ("fixed
-launcher icon size") rewrote the committed adaptive icon to inset the foreground
-22% and **silently dropped the `<monochrome>` layer**, so themed icons stopped
-working. Fix = re-add `<monochrome><inset android:drawable="@mipmap/ic_launcher_monochrome" android:inset="22%"/></monochrome>`
-to `ic_launcher.xml` + ship the monochrome mipmaps.
-
-**Android icon pipeline (non-obvious).** `src-tauri/gen` is gitignored, BUT specific
-customized res files are **force-added** (tracked): `mipmap-anydpi-v26/ic_launcher.xml`,
-`drawable/ic_launcher_background.xml`, `values/themes.xml`, `splash_icon.png`. CI
-(release/nightly/android-e2e) does `rm -rf gen/android` → `tauri android init` →
-`tauri icon ../../data/icons/readest-book.png` → **`git checkout .`** (restores the
-tracked customizations) → build. So **the committed gen files are the build's source
-of truth.** `tauri icon` (CLI 2.10.1) writes gen mipmaps + a DEFAULT `ic_launcher.xml`
-(foreground+background only) and does NOT emit a monochrome layer — so the monochrome
-PNGs (or a vector drawable) MUST be force-committed into `gen/.../res/` to survive
-`git checkout .`. `git add -f apps/.../gen/.../mipmap-*/ic_launcher_monochrome.png`.
-`src-tauri/icons/android/*` is the historical master but is NOT what the build reads.
-
-**Themed tint = SRC_IN (alpha only).** The launcher replaces the monochrome layer's
-RGB with the wallpaper tint, keeping only alpha → any fully-opaque artwork flattens
-to a solid blob (the original desaturated-logo monochrome lost all detail). Convey
-character via negative space. For Readest we kept the existing artwork and carved a
-**narrow vertical center-gap (spine)** via an alpha-multiply mask (ImageMagick:
-`magick src -alpha extract a.png; magick -size WxH xc:white -fill black -draw "roundrectangle ..." g.png; magick a.png g.png -compose multiply -composite na.png; magick src na.png -alpha off -compose CopyOpacity -composite out.png`),
-gap ≈ centered, width ~4% of content, from ~3%→84% of content height (pages stay
-joined at the binding). Preview-as-themed = tint `-colorize`, inset to central 56%
-(=22% inset), composite over dark bg, circular mask.
-
-**Emulator verify (Pixel_9_Pro AVD, Google Play image, NexusLauncher).** Themed icons
-toggle: Wallpaper & style (`am start -n com.google.android.apps.wallpaper/com.android.customization.picker.CustomizationPickerActivity`)
-→ "Home screen" tab → "Themed icons" switch. Only the **home screen/dock** is themed;
-the **app drawer keeps full color** (expected, not a bug). `uiautomator dump` returns
-"null root node" on the wallpaper picker (SurfaceView) → navigate by screenshot
-coords. Build for emulator = `pnpm tauri android build --debug --target aarch64 --apk`
-(NDK_HOME must be set). Gradle-standalone (`./gradlew :app:assembleUniversalDebug`)
-fails: the `rustBuild*` task shells `pnpm tauri ...` which panics at
-`tauri-cli/src/mobile/mod.rs:403` unless driven by `tauri android build`. Confirm the
-APK packaged it: `aapt2 dump xmltree --file res/mipmap-anydpi-v26/ic_launcher.xml app.apk`
-should show an `E: monochrome` node. Regression guard:
-`src/__tests__/android/themed-icon.test.ts` (asserts `<monochrome>` in the XML + a
-tracked monochrome mipmap per density). Related: [[dict-lookup-browser-hijack-4559]]
-(Android resource/manifest gotchas), [[android-cdp-e2e-lane]].

apps/readest-app/.claude/memory/annotation-share-toolbar-4014.md

@@ -1,64 +0,0 @@
----
-name: annotation-share-toolbar-4014
-description: "Share intent in the selection toolbar + drag-and-drop toolbar customizer (#4014)"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 507a0166-cb55-4f33-b633-3230c0c514ff
----
-
-#4014 (PR #4570) — added a native "Share" tool to the in-reader text-selection toolbar
-plus a drag-and-drop customizer (show/hide + reorder tools). Branch
-`feat/annotation-share-toolbar-4014`; spec + plan in
-`docs/superpowers/{specs,plans}/2026-06-13-annotation-share-toolbar*`.
-
-Key facts / gotchas:
-- **`src/utils/share.ts` is dual-purpose** — it already held share-LINK helpers
-  (`buildShareUrl`/`parseShareDeepLink` for the `/s/{token}` feature). Text-share was
-  added there: `shareSelectedText(text, position?, appService?)` and
-  `canShareText(appService)`.
-- **Native share is gated to mobile + macOS only** (`isMobileApp || isMacOSApp`).
-  Windows/Linux desktop are excluded because `@choochmeque/tauri-plugin-sharekit-api`'s
-  share UI can FREEZE the app on Windows (issue #4343) — `nativeAppService.saveFile`
-  gates `shareFile` the same way. Ladder: native → `navigator.share` → clipboard.
-  `canShareText` = that OR web `navigator.share`; used to gate Share's visibility in
-  toolbar + customizer + the quick-action dropdown.
-- **Toolbar order is a view setting**: `AnnotatorConfig.annotationToolbarItems`
-  (`src/types/book.ts`), default in `DEFAULT_ANNOTATOR_CONFIG` = the original 8 tools,
-  **Share hidden by default** (starts in the "Available" tray). No migration needed:
-  the `{...getDefaultViewSettings(ctx), ...saved}` merge in `settingsService.ts` +
-  `getToolbarToolTypes(undefined,...)` fallback both yield the default.
-- **Pure helpers** in `src/utils/annotationToolbar.ts` (unit-tested) own all
-  order/visibility logic: `getToolbarToolTypes`/`getAvailableToolTypes` (canShare-gated,
-  dedup, drop-unknown), `add/remove/reorderToolbar`. `ALL_ANNOTATION_TOOL_TYPES` is
-  asserted to match the `annotationToolButtons` registry order by a test.
-- **Customizer** = `src/components/settings/AnnotationToolbarCustomizer.tsx`, a sub-page
-  off `ControlPanel` (Behavior panel) via `NavigationRow`. Two `@dnd-kit` zones; chips are
-  tap-to-toggle AND drag. Design evolved heavily during live browser testing (see gotchas):
-  - **WYSIWYG**: "In toolbar" renders a faithful preview of the real selection popup —
-    `selection-popup bg-gray-600 text-white`, icon-only 32×32 buttons (mirrors
-    `AnnotationToolButton`), `w-fit max-w-full` (content-width, start-aligned). "Available"
-    tools are labeled icon+text chips. Zone content uses `px-4` to align with `SubPageHeader`.
-  - **dnd-kit multiple-containers pattern** (NOT the simple single-list one): single
-    `{toolbar, available}` state; `onDragOver` live-reparents across zones; custom
-    `collisionDetection` = `pointerWithin` → `rectIntersection` fallback, snapping a zone-id
-    hit to the closest inner chip (plain `closestCorners`/`closestCenter` CANNOT drop into an
-    empty zone). `rectSortingStrategy` (NOT `horizontalListSortingStrategy`, which breaks
-    wrapped layouts).
-  - **NO `DragOverlay`** — the settings modal is a CSS-`transform` container, so a
-    `position:fixed` overlay is offset from the cursor. In-place `useSortable` transform
-    (relative translate) tracks correctly.
-  - **`itemsRef` stale-closure fix**: dnd-kit calls `onDragEnd` with the handler captured at
-    drag START, so the closed-over `items` is stale → a cross-zone drag would bounce back on
-    release. Read live state from `itemsRef.current` in `handleDragEnd`/tap handlers.
-  - **Add all** (rebuilds in canonical `ALL_ANNOTATION_TOOL_TYPES` order, NOT prior order) /
-    **Clear all** header buttons.
-  - Cross-platform guard: when editing on a `!canShare` device, `persist` re-appends a
-    `share` that was synced-in but hidden, so it isn't dropped for share-capable devices.
-- **Empty toolbar suppresses the popup**: when `getToolbarToolTypes` yields [] (user cleared
-  all), `Annotator.tsx` does NOT render the `AnnotationPopup` on a plain selection (gated on
-  `toolButtons.length > 0 || highlightOptionsVisible || annotationNotes.length > 0`) — no
-  empty bar, but highlight-edit/notes popups still work. (Earlier tried fallback-to-default;
-  user wanted full suppression instead.)
-- Adding a tool to the union (`AnnotationToolType`) is compile-checked: the
-  `createAnnotationToolButtons` generic in `AnnotationTools.tsx` requires every member.

apps/readest-app/.claude/memory/annotator-onload-listener-leak-paragraph-mode.md

@@ -1,25 +0,0 @@
----
-name: annotator-onload-listener-leak-paragraph-mode
-description: "Paragraph mode degrades over chapters on Android (#4735) — Annotator onLoad leaked renderer-scroll + native-touch listeners on long-lived objects; per-view fix + the reusable per-section-leak pattern"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 980f8d79-9360-4402-bd49-8dd389200c1e
----
-
-PR #4735 (`fix/annotator-input-listener-leak`). Reported: reading a 3000-chapter web novel in **paragraph reading mode** on Android (Z Fold 7), paragraph transitions get sluggish after a few chapters and keep degrading until app restart. Classic per-section-transition resource leak.
-
-**Root cause — Annotator `onLoad` attaches listeners to objects that OUTLIVE the section.** `Annotator.tsx`'s `onLoad` (wired via `useFoliateEvents(view, { onLoad })` to the foliate `load` event, which fires once per section document load) did:
-- `view.renderer.addEventListener('scroll', handleScroll)` — never removed
-- `view.renderer.addEventListener('scroll', () => repositionPopups())` — anonymous, unremovable
-- Android: `eventDispatcher.on('native-touch', handleNativeTouch)` — never `off`'d
-
-`view.renderer` is created ONCE per book (`createElement('foliate-view')` + `view.open()` in `FoliateViewer.tsx`), lives the whole session; the global `eventDispatcher` too. So every `load` permanently adds listeners. **foliate fires `load` for PRELOADED neighbour sections too** (`paginator.js#loadAdjacentSection` → `dispatchEvent(new CustomEvent('load',…))`, `#preloadNext` loads up to 8), so the accrual is several-per-chapter, not one. The doc-scoped `detail.doc.addEventListener(...)` listeners do NOT leak (the section iframe is destroyed by foliate's `#destroyView`, taking them with it). Only the renderer-/dispatcher-scoped ones leak.
-
-**Why paragraph mode + Android specifically.** Every paragraph advance calls `renderer.goTo({index, anchor})` (`focusCurrentParagraph`), which scrolls the renderer container → `paginator.js:~1161` `this.#container.addEventListener('scroll', () => { if(!#isAnimating) dispatchEvent(new Event('scroll')) })` → runs ALL accumulated scroll listeners. Normal paginated reading scrolls only on occasional page turns, so the same leak is far less felt. Cost is REAL on Android: `handleScroll` (useTextSelector.ts, the `#873` selection-pin workaround) early-returns unless `osPlatform==='android'`, then calls `getViewSettings`; `native-touch` is Android-only. Restart recreates the view/renderer → cleared (the reporter's workaround).
-
-**Fix = `useRendererInputListeners(view, {...})` hook** (`src/app/reader/hooks/`): registers the renderer `scroll` + (Android) `native-touch` listeners ONCE per view in an effect keyed `[view, enableNativeTouch]`, with cleanup; handlers routed through refs so re-renders never re-subscribe. The native-touch handler now resolves the CURRENT primary section's doc/index at fire time (`view.renderer.getContents().find(c=>c.index===primaryIndex)`) instead of capturing a load's doc/index (a load may be an off-screen preload — and the old code fan-fired EVERY loaded section's handler per touch, calling handleTouchEnd/handlePointerUp N times; new code fires once = strictly more correct). Dropped the redundant `scroll→repositionPopups` (a dedicated effect already repositions popups on scroll). `listenToNativeTouchEvents()` just sets one global `window.onNativeTouch` that re-dispatches `native-touch` via eventDispatcher — idempotent, fine to call once/view.
-
-**Reusable pattern (the lesson).** Listeners attached inside a per-section / per-event handler (`onLoad`, `load`, relocate, create-overlay) to an object that outlives that event (`view.renderer`, global `eventDispatcher`, `window`, `document`) LEAK one set per event. Audit `addEventListener`/`eventDispatcher.on` inside `onLoad`-style handlers: if the target isn't the per-section `detail.doc` (which dies with the iframe), it must move to a per-view `useEffect` with cleanup. `eventDispatcher` (`utils/event.ts`) stores async listeners in a per-event `Set` keyed by callback reference; fresh closures each call never dedupe → unbounded.
-
-**Verify gotchas.** Hook unit-tested with `renderHook` + a `MockRenderer extends EventTarget` tracking scroll listeners + a mocked `eventDispatcher` Set; assert size stays 1 across 20 re-renders, latest-handler routing, unmount→0, Android gate. NOTE: creating the mock `view` INSIDE the renderHook callback churns view identity → the `[view]`-keyed effect re-runs each render (still no leak — cleanup keeps Set at 1 — but `listenToNativeTouchEvents` call-count grows); hoist `view` outside to mirror the real stable `getView(bookKey)`. Needs on-device Android verification (Android-gated paths). Related: [[paragraph-mode-toggle-resume-4717]], [[tts-sync-paragraph-rsvp-3235]], [[android-nativefile-remotefile-io]].

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

@@ -1,90 +0,0 @@
-# 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/backup-windows-zip-paths-4703.md

@@ -1,16 +0,0 @@
----
-name: backup-windows-zip-paths-4703
-description: Backup zip exported on Windows failed to restore anywhere — backslash separators in zip entry names
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: dd015419-996e-466b-8039-f2d98312d9d6
----
-
-#4703: Backup `.zip` exported on Windows wouldn't restore on any platform (Web/Android/Windows) — books restored with metadata but missing files/covers.
-
-**Root cause:** `appService.readDirectory` returns paths with the host separator. On Windows `nativeAppService.readDir` → `getRelativePath` strips the base prefix but leaves backslashes, so `file.path` is `hash\cover.png`. `addBackupEntriesToZip` used `file.path` verbatim as the zip entry name. Restore (`restoreFromBackupZip`) matches a book's files by `e.filename.startsWith(`${hash}/`)` (forward slash) → backslash names never match → all files silently skipped. (The "garbled Unicode" reported in zip viewers was just the `\` rendered oddly.)
-
-**Fix (export side only):** normalize the zip entry name to forward slashes — `file.path.replace(/\\/g, '/')` — in `addBackupEntriesToZip` (`src/services/backupService.ts`). Keep `file.path` (host separators) for `readFile`. Test: `backup-windows-paths.test.ts` drives the now-exported `addBackupEntriesToZip` with a capturing ZipWriter stub + Windows-style backslash listing (no zip.js workers needed; the forced `useWebWorkers`/`useCompressionStream` config makes a real round-trip impractical under jsdom).
-
-**General lesson:** `readDirectory`/`readDir` paths carry host separators; normalize to `/` at any cross-platform boundary (zip entries, sync keys, anything serialized for another device). Already-broken Windows backups still need re-export — restore was left unchanged (minimal fix; matches the issue's expected behavior). See [[platform-compat-fixes]].

apps/readest-app/.claude/memory/biometric-app-lock-4645.md

@@ -1,17 +0,0 @@
----
-name: biometric-app-lock-4645
-description: "Biometric (fingerprint/Face ID) startup unlock layered over the PIN app-lock; gotchas for applock-store seeding, mobile-cfg crate, and scoped i18n"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 7d0f633b-0e69-405e-a4b4-5a1b19723d86
----
-
-Biometric app-lock (#4645, PR #4650, branch `feat/biometric-app-lock`): biometrics unlock at startup on Android/iOS, app PIN as fallback; desktop/web unchanged. Layered over the existing PIN lock — `pinCodeEnabled` stays the master switch, PIN crypto in `libs/crypto/applock.ts` untouched. All plugin access isolated behind `src/services/biometric.ts` (guarded no-op off mobile; `authenticate` uses `allowDeviceCredential:false` so PIN is the only fallback). New setting `biometricUnlockEnabled` defaults true only for NEW mobile setups; existing PIN users (undefined→off) opt in via a mobile-only toggle.
-
-Non-obvious gotchas (cost real review/rework here):
-- **`AppLockScreen` must read startup-snapshot settings from `appLockStore`, NOT `settingsStore`.** `Providers` seeds ONLY the app-lock store via `useAppLockStore.initialize()` (from its own `loadSettings()`), before the gate mounts. `settingsStore.settings` starts `{}` and is seeded later by page-level init — reading the flag from `settingsStore` in the gate RACES and silently no-ops. Fix = thread the value through `initialize()` like `pinHash`/`pinSalt`.
-- **`tauri-plugin-biometric` is `#![cfg(mobile)]`** — empty on desktop, so registration must be `#[cfg(any(target_os="ios",target_os="android"))]`-gated (like `haptics`/`sign-in-with-apple`). Desktop `clippy:check` does NOT compile that line, so the Rust side needs a real device build to verify. The dep pin lands in the **workspace-root `Cargo.lock`** (resolved when cargo runs), NOT `src-tauri/Cargo.lock` (which doesn't exist/track here).
-- **Scoped i18n without churn:** `public/locales/en` is NOT scanner-managed (key-as-content fallback). Running the full `i18n:extract` reconciles ALL strings and pulls in unrelated drift already on main (e.g. Word Lens keys). For a clean PR, discard the scanner output and add only your new keys to the 33 langs in `i18n-langs.json`. "Face ID"/"Touch ID" are Apple brands — keep verbatim in every locale.
-
-Related: [[ios-instant-dict-double-popup]] (same applock/gate area), [[custom-fonts-reincarnation-4410]] (settings-sync flag patterns).

apps/readest-app/.claude/memory/book-actions-platform-surfaces.md

@@ -1,14 +0,0 @@
----
-name: book-actions-platform-surfaces
-description: Where to add a library book action so it reaches every platform (context menu is desktop-only)
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 4efb7b40-cce1-4742-9730-7e93e643d196
----
-
-The library book **context menu** (`BookshelfItem.tsx::bookContextMenuHandler`, native `Menu.new`) only renders where `appService.hasContextMenu` is true — that is **Tauri desktop only** (`nativeAppService.ts`: `!(ios||android)`). It is **false on web AND on iOS/Android**. So a book action added only to the context menu (+ `getBookContextMenuItemIds` in `libraryUtils.ts`) never reaches phone/web users.
-
-The cross-platform home for book-level actions is the **`BookDetailView` action-icon row** (`src/components/metadata/BookDetailView.tsx`), shown in `BookDetailModal`, reachable on every platform (BookItem tap → details, `Bookshelf.tsx::handleShowDetailsBook`). That row is `flex-nowrap` inside a fixed `h-32` column and already holds up to ~5 icons (Edit/Delete/Download/Upload/Export) — adding more risks phone overflow; keep additions to one small icon.
-
-**Rule:** desktop-only fast path → context menu; must reach mobile → BookDetailView (or both). Example: the "Search on Goodreads" feature (#4543) added both — `searchGoodreads` context-menu id + a `FaGoodreads` button in BookDetailView, opening `getGoodreadsSearchUrl` via [[open-external-url-helper]]. In-reader highlighted-text Goodreads search is a built-in [[web-search-provider]] entry instead.

apps/readest-app/.claude/memory/booknote-view-autoscroll-4352.md

@@ -1,48 +0,0 @@
----
-name: booknote-view-autoscroll-4352
-description: "Annotation/bookmark list (BooknoteView) auto-scroll-to-nearest regression after virtualization (#4352) and its TOCView-mirroring fix"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: bda988b9-28ec-450f-874e-ee9c104f7603
----
-
-After #4352 virtualized `BooknoteView` (sidebar annotations/bookmarks list,
-`src/app/reader/components/sidebar/BooknoteView.tsx`), the list stopped
-auto-scrolling to the nearest annotation for the current reading position (it
-stranded at the top showing Chapter 1). #4352 replaced the per-item
-`useScrollToItem` with a single `virtuosoRef.scrollToIndex`, but missed the
-machinery `TOCView` already had. Two distinct failure paths:
-
-1. **Reload (annotations tab active at load; progress arrives AFTER mount):** the
-   OverlayScrollbars `initialized` callback (deferred init) resets the wrapped
-   viewport `scrollTop` to 0, clobbering the scroll; the `lastScrolledCfiRef`
-   guard then blocks any retry. Fix = re-apply `scrollToIndex` to the *current*
-   nearest index inside the `initialized` callback, read via a **ref**
-   (`nearestIndexRef`) because that callback is the mount-time closure. Double
-   rAF (settle the reset, then re-assert once rows are measured).
-2. **Tab-switch (open panel while reading; progress KNOWN at mount):** firing a
-   `scrollToIndex` synchronously on the freshly mounted, unmeasured list either
-   no-ops (`behavior:'smooth'`) or **wedges Virtuoso into rendering nothing**
-   (`behavior:'auto'`). Fix = mount Virtuoso *natively* centered via
-   `initialTopMostItemIndex` + an `initialScrollHandledRef` gate so the scroll
-   effect SKIPS that first jump. This is exactly TOCView's design.
-
-The fix mirrors [[toc-expand-and-autoscroll]] (same OverlayScrollbars-resets-
-scrollTop + Virtuoso-lands-short-on-unmeasured-rows pattern). Test:
-`src/__tests__/components/BooknoteView.test.tsx` stubs Virtuoso (spy-able
-`scrollToIndex`, captures `initialTopMostItemIndex`) and captures the mount-time
-`initialized` callback — forcing a ref-based fix (modeled on `TOCView.test.tsx`).
-
-**Dev-server verification gotchas (cost hours here):**
-- The `localhost:3000` dev server was running from a *different worktree*
-  (`/Users/chrox/dev/readest-fix-4394-bg-gutter-bleed`), not the main checkout.
-  Edits weren't compiled until copied into that worktree's path. Check
-  `ps aux | grep next-server` for the serving cwd. Book data is per-origin
-  (OPFS/IndexedDB on localhost:3000) so you can't verify on another port.
-- After ~10 rapid file syncs, **Fast Refresh corrupts the mounted tab's state**
-  — identical code that worked started rendering 0 items. A *brand-new tab*
-  (close the old one) renders correctly. Always verify in a fresh tab.
-- Chrome MCP `javascript_tool` querying `.booknote-item` count catches Virtuoso
-  mid-render (returns 0 even when it later paints fine). Trust the *screenshot*
-  (the painted frame), not a synchronous DOM count, for virtualized lists.

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

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

@@ -1,20 +0,0 @@
----
-name: cdp-android-webview-profiling
-description: "How to drive the Android WebView via CDP (adb) to run JS probes/benchmarks inside the live Readest app, and the gotchas that waste time"
-metadata: 
-  node_type: memory
-  type: reference
-  originSessionId: 8057ac9c-2e3e-446d-86aa-29baddfbfe66
----
-
-Driving the on-device Readest WebView via CDP to run JS probes/benchmarks **inside the live app** (no rebuild) — used for the NativeFile/RemoteFile I/O study ([[android-nativefile-remotefile-io]]).
-
-**Setup:** app must be running → `adb shell cat /proc/net/unix | grep webview_devtools_remote_<pid>` → `adb forward tcp:9222 localabstract:webview_devtools_remote_<PID>`. Discover targets with a Node `http.get` to `/json/list` (set header `Host: localhost`) — **curl mishandles the WebView's HTTP framing and hangs/returns empty**. Connect `ws://127.0.0.1:9222/devtools/page/<id>`, then `Runtime.enable` + `Runtime.evaluate {expression:'(async()=>{...})()', awaitPromise:true, returnByValue:true}`. Helper scripts kept in `/tmp/cdp/` (eval.mjs, disc.mjs).
-
-**Gotchas that burned time:**
-- **Locked device freezes `fetch`.** When the screen is locked the page is `visible:false`; Chromium freezes the network task queue so EVERY `fetch()` (same-origin and asset) hangs forever — but Tauri `invoke()` still resolves. Must have the user **unlock + keep Readest foregrounded**. Set `svc power stayon true` + `settings put system screen_off_timeout 1800000` after unlock (revert `stayon false` when done).
-- **`visible:false` also throttles `setTimeout`** (background timer coalescing → ~60 s). Don't rely on setTimeout guards in probes when the page may be hidden; `invoke`-only probes still work hidden.
-- `window.__TAURI_INTERNALS__` is ALWAYS injected (independent of `withGlobalTauri`) → use `.convertFileSrc(path)` and `.invoke(cmd,args)` from injected JS. Android asset URL = `http://asset.localhost/<encodeURIComponent(path)>`.
-- Real book files live in **internal** storage (`/data/user/0/com.bilingify.readest/...`), not the external `Android/data/.../files` dir (that's `forbidden path` to the fs plugin). `$APPCACHE` = `/data/user/0/com.bilingify.readest/cache` holds import temp copies (in asset scope `$APPCACHE/**/*`). `adb run-as` is denied on the release build.
-- fs plugin invokes: `plugin:fs|open{path,options}→rid`, `seek{rid,offset,whence}` (Start=0), `read{rid,len}`→ArrayBuffer whose **last 8 bytes are bigendian nread**, `close{rid}` (**not ACL-allowed** in the installed build). `read_dir`/`stat` on out-of-scope abs paths return `forbidden path`. Tauri v2 `BaseDirectory`: AppData=14, AppLocalData=15, AppCache=16.
-- zsh: `$PIPESTATUS[0]` is a bash-ism (empty in zsh; use `$pipestatus[1]`) — don't trust it for exit codes.

apps/readest-app/.claude/memory/ci-pr-delivery-and-push.md

@@ -1,26 +0,0 @@
----
-name: ci-pr-delivery-and-push
-description: Delivering small PRs from a dirty dev tree without a worktree; the slow pre-push hook + proxy SSH-drop and its keepalive fix
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: c1097233-8b53-422a-98ec-3f0146f32f6b
----
-
-How CI/config PRs get delivered in this repo when `dev` has unrelated uncommitted WIP, and the push gotcha.
-
-**Packaging a commit onto a fresh PR branch WITHOUT `pnpm worktree:new`** (the worktree script does a full `pnpm install` + `tauri android init` + icon gen — disproportionate for a YAML/package.json-only PR, and you can't `git checkout` a branch in the dev tree because the user's WIP blocks it):
-1. Edit the target files in the dev tree (only files NOT in the user's WIP set — verify with `git status --short -- <files>`), `git add` just those, commit on `dev` (mirrors how the user wanted the pin committed).
-2. Re-parent onto `origin/main` (or onto the existing PR-branch tip for a fast-forward add) via a temp index — no checkout, no worktree, dev working tree untouched:
-   ```
-   export GIT_INDEX_FILE=$(mktemp); git read-tree <BASE>
-   git update-index --cacheinfo 100644,$(git rev-parse HEAD:<path>),<path>   # per changed file
-   TREE=$(git write-tree); unset GIT_INDEX_FILE
-   NEW=$(git log --format=%B -n1 HEAD | git commit-tree $TREE -p <BASE>)
-   git update-ref refs/heads/<branch> $NEW
-   ```
-3. Verify `git diff --stat <BASE>..<branch>` shows ONLY the intended files, then push.
-
-This is how PR #4547 (pin `android-emulator-runner` + shard `test_web_app`) was built on top of `origin/main` while `dev` carried 49 files of unrelated dictionary/goodreads WIP.
-
-**Push gotcha (now fixed in `~/.ssh/config`):** `git push` opens the SSH connection BEFORE running the pre-push hook; the husky hook runs the FULL vitest suite (~55s, 5271 tests) + format + lint. The user pushes through a SOCKS proxy (`nc -x 127.0.0.1:8119` → `ssh.github.com:443`), so the idle connection got dropped during the hook → "Broken pipe", ref never transferred (remote stayed at old SHA — always `git ls-remote` to confirm). Fix added: `ServerAliveInterval 15` + `ServerAliveCountMax 60` under `Host github.com`. Also: **`--no-verify` is safe once the hook has already passed** on the same tree — re-running it just re-opens the idle window. See also [[feedback_dont_push_every_change]], [[feedback_use_worktree]].

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

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

apps/readest-app/.claude/memory/cover-bg-image-texture-suppression.md

@@ -1,47 +0,0 @@
----
-name: cover-bg-image-texture-suppression
-description: Cover painted via body background-image vanished under an active bg texture (parchment) because textureAwareBackground misclassified it as transparent
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 9d32520c-53be-4871-9104-d93617736e30
----
-
-EPUB cover pages that paint the cover via a `<body>` CSS `background-image`
-(EPUB sets `background-color` transparent + `background-size:100% 100%`, no
-`<img>` — e.g. Sigil/duokan样书《商梯》) showed the **background texture instead
-of the cover** on the first page. Reported "Xiaomi only" but it's
-texture-only, not Android-only.
-
-Root cause (verified on-device via adb+CDP, Xiaomi 13 WV147): foliate
-`packages/foliate-js/paginator.js` `textureAwareBackground(resolved, hasTexture)`.
-foliate captures the body bg into `view.docBackground` via
-`getComputedStyle(body).background` (the SHORTHAND), which always serializes the
-transparent background-*color* first: `rgba(0, 0, 0, 0) url("blob:…") no-repeat
-fixed 50% 50% / 100% 100% …`. The old `isTransparent` regex
-`/^\s*(transparent|rgba\(0,\s*0,\s*0,\s*0\))/` matched that prefix → under an
-active texture (`--bg-texture-id` != none) it returned `''` → no bg segment in
-the host `#background` → texture (`.foliate-viewer::before`) showed through. With
-no texture it worked (returns the cover bg unchanged), which is why desktop/
-default looked fine.
-
-Fix: a bg that carries an image is NOT transparent. Add `hasImage =
-/\burl\(/i.test(resolved)` and gate `isTransparent` on `!hasImage`. A full-page
-cover should occlude the texture; plain `none` transparent pages still drop so
-the texture shows through. Helps scrolled (line ~1464) and paginated (~1482)
-callers alike. Test: `paginator-background-segments.test.ts` (added the
-url()-keeps case; kept the existing `none`-drops case).
-
-NOT the bug (ruled out on-device): Rust `parse_epub_metadata` cover EXTRACTION
-(library thumbnail was correct), shorthand serialization (WV147 emits the url
-fine), the cover blob URL (loads 1200x1800 fine), `background-attachment:fixed`
-(Android falls back to scroll but the segment sets `background-attachment:
-initial` anyway). Related: [[paginated-texture-occlusion-4399]],
-[[dark-mode-texture-body-bg-4446]], [[paginator-swipe-bg-flash]].
-
-CDP verify recipe: pid changes per app restart — re-derive socket from
-`/proc/net/unix` (`webview_devtools_remote_<pid>`), `adb forward tcp:9333
-localabstract:…`; curl mishandles WV HTTP framing → raw-socket fetch `/json`;
-pure-python WS client (omit Origin for M111+); paint a 50%-width test segment
-with the cover blob bg into `#background` + `Page.captureScreenshot` to see
-cover-vs-texture side by side.

apps/readest-app/.claude/memory/cover-stale-inplace-mutation-memo.md

@@ -1,20 +0,0 @@
----
-name: cover-stale-inplace-mutation-memo
-description: Library cover (or any memoized child) not updating until refresh — in-place object mutation defeats React.memo
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: ec78c172-79e7-448c-8671-780dcc115613
----
-
-Symptom: edit a book's cover in Book Details → Save → return to library, the cover shows the OLD image; a full page refresh fixes it. Title/author DO update.
-
-Root cause: `handleUpdateMetadata` in `src/app/library/page.tsx` mutated the existing `book` object IN PLACE (`book.metadata = …; book.coverImageUrl = …; book.updatedAt = …`) then passed that same reference to `updateBook`. `<BookCover>` (`src/components/BookCover.tsx`) is `React.memo`'d with a custom comparator reading `coverImageUrl`/`metadata.coverImageUrl`/`updatedAt` off the book. Because the previous-render snapshot (`prevProps.book`) is the *same mutated object*, every field compares equal → memo skips → cover never re-renders. Title updates because `BookItem` is NOT memoized. Refresh works because `loadLibraryBooks` (`libraryService.ts`) strips `coverImageUrl` on save and REGENERATES it from `${hash}/cover.png` on load (the file was overwritten by `updateCoverImage`).
-
-KEY INSIGHT: cloning inside `updateBook` would NOT fix it — once the original object is mutated, `prevProps` already reads the new values. The fix must leave the object React holds as `prevProps` untouched.
-
-Fix (PR for fix/txt-open-with-conversion): pure helper `getBookWithUpdatedMetadata(book, metadata)` in `src/utils/book.ts` returns a NEW book object (`{...book, metadata, title, author, primaryLanguage, updatedAt, coverImageUrl}`); `handleUpdateMetadata` uses it instead of mutating. Cover URL is set from `metadata.coverImageBlobUrl || metadata.coverImageUrl` (cached/blob URL is a unique path = the new image; `'_blank'` for remove). Unit test asserts immutability of the input + new reference.
-
-General rule: when a memoized child reads fields off a store object, NEVER mutate that object in place to "update" it — build a new object. Same trap could bite any `React.memo` field comparator in this codebase.
-
-On-device CDP verification (reusable): the cover SET path uses the native Tauri file picker (`selectFiles` → `openDialog`), NOT automatable via CDP; the installed emulator app is the released bundled build (`http://tauri.localhost/...`), not the dev server. So I verified the MECHANISM directly in the live WebView: extracted the zustand library store from the React fiber tree (the library page calls `useLibraryStore()` with NO selector, so its fiber hook `memoizedState` holds the full state incl. `library`/`setLibrary`/`updateBook`), injected an Alice book, then A) mutated it in place + `setLibrary([sameRef])` → rendered `<img src>` stayed stale (bug), B) `setLibrary([{...book,coverImageUrl:NEW}])` → `<img src>` updated immediately (fix). Restore with `Page.reload` (injected book was in-memory only). See [[cdp-android-webview-profiling]], [[android-cdp-e2e-lane]].

apps/readest-app/.claude/memory/cross-page-selection-autoturn-4741.md

@@ -1,57 +0,0 @@
----
-name: cross-page-selection-autoturn-4741
-description: Cross-page selection/highlight in paginated mode via extracted useAutoPageTurn; all four selection gestures drive the corner-dwell turn
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 33b70e98-fb55-467a-b03f-e4065491bc7e
----
-
-#4741: in paginated (non-scrolling) mode, extend a selection/highlight past the
-page edge by turning the page mid-gesture. Branch `feat/cross-page-highlight-autoturn`.
-
-**Extracted `src/app/reader/hooks/useAutoPageTurn.ts`** from `useTextSelector` —
-the corner-dwell auto page-turn (#1354), now **decoupled from the DOM selection**
-so selection-less gestures can drive it. API: `notePoint`/`noteAutoTurnPoint`
-(window-coord engagement point), `cancel`, `isAutoTurning`, `onAfterTurn(cb)`
-(Set of subs), `cornerAtPoint`, `readingAreaRect`. Liveness at dwell fire-time is
-an injected predicate, not `doc.getSelection()`: `noteCorner(corner, isInCorner)`.
-`useTextSelector` keeps the dual-signal native liveness (`pointerCornerNow ||
-caretCornerNow`); point-only callers use `noteAutoTurnPoint` (last-point liveness).
-Pure exports `getReadingAreaRect`, `turnForFocusBeyondPage`, `keyboardTurnDirection`.
-
-**Key trap:** the old `armDwell` required a valid DOM selection to turn. Instant
-Highlight (`user-select:none` + CFI overlay) and AnnotationRangeEditor (CFI
-overlay) have **no** DOM selection, so the machine refused to turn for them. The
-decoupling is what makes them work at all.
-
-**Four gestures, all feeding the one machine** (`useTextSelector` re-exposes
-`noteAutoTurnPoint`/`cancelAutoTurn`/`onAutoTurn` to the editors via `Annotator`):
-1. Instant Highlight drag — `handlePointerMove`/`handleNativeTouchMove` feed the
-   finger corner. `useInstantAnnotation` now **DOM-anchors the start** (`startPosRef`
-   = `{node,offset}` at pointer-down; `buildRangeFromAnchor` builds anchor->end each
-   move) so it survives the scroll; relaxed the pointer-up `distance<10` cancel with
-   `&& !previewAnnotationRef.current`. See [[instant-highlight-tap-paginate]].
-2. `SelectionRangeEditor` handle drag — already DOM-anchored the fixed end; just
-   feed `noteAutoTurnPoint(point)` + cancel + re-emit.
-3. `AnnotationRangeEditor` handle drag — `useAnnotationEditor` changed from
-   `handleAnnotationRangeChange(startPt,endPt)` (`buildRangeFromPoints` resolved BOTH
-   ends from window coords -> lost previous page) to `applyAnnotationRange(range,...)`;
-   component anchors the non-dragged end (`fixedAnchorRef`) + builds via
-   `rangeFromAnchorToPoint` like SelectionRangeEditor.
-4. `Shift+Arrow` keyboard adjust (#4728) — `useBookShortcuts.adjustTextSelection`,
-   after `extendSelectionFromContents`, **immediate turn-on-cross** (no dwell):
-   `keyboardTurnDirection(contents, getReadingAreaRect(...))` -> `view.next()/prev()`
-   when the extended focus leaves the page. Desktop-only; gated `!scrolled`.
-
-**After-turn re-emit:** active gesture subscribes `onAfterTurn` to rebuild its range
-from the held point onto the new page immediately (instant: `reapplyInstantAnnotation`;
-editors: `subscribeAutoTurnReemit` -> `updateFromDraggedPoint(lastPoint)`). Native
-selection does NOT subscribe (browser extends its own). The Android #873 scroll-pin
-(`selectionPosition`) is re-anchored after every turn via `onAfterTurn` in useTextSelector.
-
-`focusCaretWindowPos` promoted `useTextSelector` -> `src/utils/sel.ts` (keyboard reuse).
-Scope: within-section column turns only (a Range can't span two iframe docs).
-Tests: `useAutoPageTurn.test.ts` (21), `useTextSelector-instantTurn.test.ts`,
-`useInstantAnnotation.test.ts`, `useAnnotationEditor.test.ts`; existing autoTurn/
-instantHold suites stay green (regression net for the extraction).

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

@@ -1,74 +0,0 @@
-# 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/custom-fonts-reincarnation-4410.md

@@ -1,27 +0,0 @@
----
-name: custom-fonts-reincarnation-4410
-description: Custom fonts/textures disappear when logged into cloud sync after re-import-after-delete; CRDT remove-wins needs a reincarnation token
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 2b61b392-4d32-4516-84bd-f362bba22378
----
-
-# #4410 — disappearing custom fonts when logged into cloud
-
-**Symptom:** custom fonts vanish a few seconds after opening a book (or ~1 min idle) ONLY when logged into cloud sync; logging out fixes it; a brand-new never-deleted font is fine; problem starts after deleting a font / "Clear Custom Fonts" then re-uploading the same file.
-
-**Root cause — CRDT remove-wins.** The replica sync (`src/libs/crdt.ts`, `src/libs/replicaInterpret.ts`) is remove-wins: once a row has a `deleted_at_ts` tombstone, a plain field upsert does NOT revive it. Only a `reincarnation` token whose effective HLC beats the tombstone revives it. `isReplicaRowAlive(row)` = `!deleted_at_ts || (reincarnation && updated_at_ts >= deleted_at_ts)`. In `mergeReplica` the reincarnation candidate's timestamp is the **row's `updated_at_ts`** (fresh on every upsert), NOT the token's mint time — so preserving an old token still revives, as long as the upsert carries it.
-
-Flow that broke: import→delete writes a server tombstone (`publishReplicaDelete`). Re-upload same file → same `contentId` → `addFont` cleared `deletedAt` locally and called `publishFontUpsert` with `reincarnation = undefined` → server tombstone survives → next pull (boot 5s / periodic / book-open / visibility) sees `isReplicaRowAlive===false` → `softDeleteByContentId` → font disappears.
-
-**Fix (PR for #4410):** in `addFont` (`src/store/customFontStore.ts`) and `addTexture` (`src/store/customTextureStore.ts`), when re-adding an existing entry, mint a reincarnation token (`Math.random().toString(36).slice(2)`, matching OPDS) when `!!contentId && !existing.reincarnation && (existing.deletedAt || existing.contentId === new.contentId)`; otherwise preserve `existing.reincarnation`. Covers both re-import-after-local-delete AND the stale-local race (local still live but another device tombstoned the row). Token is inert without a tombstone, so live re-imports are safe.
-
-**Coverage matrix across collection kinds (all share the remove-wins replica):**
-- Dictionary — handles BOTH cases (gold standard): `dictionaryService.ts importDictionaries` via `findTombstonedDictionaryMatches` + `shouldMintReincarnationForLiveReimport` (helpers in `dictionaries/dictionaryDedup.ts`), mints `uuidv4()`.
-- OPDS — case 1 only: `customOPDSStore.addCatalog` (`existing?.deletedAt && !input.reincarnation`).
-- Fonts / Textures — handled NEITHER → this bug. Now fixed to dictionary-parity.
-
-Whole chain carries the token: returned font → `publishFontUpsert` upsert AND `queueReplicaBinaryUpload` → manifest publish (`replicaBinaryUpload.ts` uses `record.reincarnation`).
-
-Note: `saveCustomFonts`/`saveCustomTextures` persist tombstoned (deletedAt) entries too, so the soft-deleted entry is still in the store at re-import time → the `existing.deletedAt` branch fires. (OPDS strips deleted at save; fonts/textures keep them.)

apps/readest-app/.claude/memory/customize-toolbar-eink-black-bar-4839.md

@@ -1,14 +0,0 @@
----
-name: customize-toolbar-eink-black-bar-4839
-description: Customize Toolbar preview rendered as a solid black bar in e-ink; preview surfaces copying bg-gray-600 need eink-bordered
-metadata:
-  type: project
----
-
-#4839: the Customize Toolbar sub-page (`AnnotationToolbarCustomizer.tsx`) toolbar **preview** Zone copied the live popup's `selection-popup bg-gray-600 text-white` but rendered as an unreadable solid black bar under `[data-eink='true']`.
-
-**Why:** the real reader popup earns its e-ink chrome from `.popup-container` (globals.css `[data-eink] .popup-container` → `bg base-100` + 1px `base-content` border). The preview Zone is a plain `<div>` with NO `popup-container`, so the dark `bg-gray-600` survived in e-ink; the base-content (inverted via `[data-eink] button`) chip icons then sat black-on-black.
-
-**How to apply:** any e-ink "preview" surface that mimics the live popup must scope the dark fill to non-e-ink (`not-eink:bg-gray-600 not-eink:text-white`) and add `eink-bordered` so e-ink renders it as `bg-base-100` + 1px `base-content` border (don't just rely on `eink-bordered`'s `!important` to override the gray — drop the gray in e-ink outright). Also fix copied white hint text (`text-white/70` → `not-eink:text-white/70 eink:text-base-content`) since the surface turns base-100. Chip icons need no change — they are `<button>`s, already inverted to base-content by the global `[data-eink] button` rule. Guard: render test asserts `.selection-popup` element carries `eink-bordered`. Verify rendered colors via `getComputedStyle` under `[data-eink]` (set `data-theme='default-light'` first or theme vars are unresolved → transparent); note daisyUI returns **oklch** not rgb — e-ink correct = bg `oklch(1 0 0)`, border/icon `oklch(0.2 0 0)`. PR #4841.
-
-Same feature as [[customize-toolbar-global-serializeconfig]]; e-ink conventions in [[feedback_design_system_doc]].

apps/readest-app/.claude/memory/customize-toolbar-global-serializeconfig.md

@@ -1,48 +0,0 @@
----
-name: customize-toolbar-global-serializeconfig
-description: Customize Toolbar applied per-book not global; root cause = serializeConfig compared viewSettings by reference (!==) so array values were always stored as stale per-book overrides
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: c6601464-9463-4ac3-99c0-e7527e4051b5
----
-
-Customize Toolbar (annotation bar, #4014, shipped v0.11.12) changes only applied
-to the book where edited, not globally. Fixed in PR #4760 (MERGED, squashed onto
-main as 7da5f8321).
-
-**Root cause:** `serializeConfig` (`src/utils/serializer.ts`) decides which per-book
-viewSettings to persist as overrides via `globalViewSettings[key] !== value` — a
-*reference* compare. It deep-clones the config first (`JSON.parse(JSON.stringify)`),
-so any **array/object** viewSettings value (`annotationToolbarItems`, and latently
-`paragraphMode`, `proofreadRules`, `ttsHighlightOptions`, `noteExportConfig`) is a
-fresh reference ≠ global → stored as a per-book override on **every** save (progress
-autosave serializes with settings each relocate). On reopen the merge
-`{ ...globalViewSettings, ...perBookOverrides }` lets the stale override shadow
-global → a global toolbar change never reaches already-saved books.
-
-**Fix (final — minimal, general, no special-casing):** compare viewSettings values
-by content, not reference. Added `isSameViewSettingValue(a,b) = a===b ||
-JSON.stringify(a)===JSON.stringify(b)`, used in the viewSettings reduce ONLY
-(searchConfig left on `!==` — it holds functions / large `results`). The field
-stays `annotationToolbarItems` in `AnnotatorConfig` (normal per-book viewSettings,
-honors the isGlobal "Apply to This Book" toggle). PR diff is just serializer.ts +
-serializer.test.ts.
-
-**Iteration history (user steered):** (1) a `GLOBAL_ONLY_VIEW_SETTINGS` exception
-forcing global save + strip/ignore per-book — rejected "don't make it an exception";
-(2) move field to `SystemSettings.globalReadSettings` — rejected "too much";
-(3) rename `annotationToolbarItems`→`annotationToolbar` for a clean slate — rejected,
-keep the original name (it's synced in globalViewSettings). Landing point: keep the
-name, fix only the serializer reference-compare bug.
-
-**Known limitation (no rename clean-slate):** existing books may carry a per-book
-`annotationToolbarItems` override from the buggy v0.11.12 build. The value compare
-stops new ones and drops an existing one on next save when it matches global, but
-does NOT retroactively clear an override whose content differs from current global —
-those books keep the stale toolbar until re-saved while equal to global. A follow-up
-one-time migration (clear persisted per-book toolbar overrides) would close this if
-needed.
-
-Tests: `src/__tests__/utils/serializer.test.ts` — array setting equal to global is
-not persisted; differing array still persisted.

apps/readest-app/.claude/memory/dark-mode-texture-body-bg-4446.md

@@ -1,73 +0,0 @@
----
-name: dark-mode-texture-body-bg-4446
-description: "#4446 dark-mode bg texture occluded by body.theme-dark opaque bg !important (style.ts getDarkModeLightBackgroundOverrides); verified on Xiaomi via CDP; multiview = patch ALL section iframes"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 61f864c0-488e-466c-89e9-86df66b57d42
----
-
-RESOLVED — PR #4564 MERGED 2026-06-12 (`fix/dark-mode-texture-4446`, built on origin/main
-via temp-index plumbing from the dirty dev tree; branch + local mods cleaned after merge).
-User-verified on the Xiaomi via `pnpm dev-android` (full aarch64 build + `adb install -r`,
-~7 min).
-
-#4446 remaining case (after [[paginated-texture-occlusion-4399]] fixed light mode): in
-**dark mode** the bg texture is absent in paginated entirely, and absent in the scrolled
-text area while header/footer still show it.
-
-**Root cause (verified live on Xiaomi 2211133C via CDP, no rebuild).**
-`getDarkModeLightBackgroundOverrides` (style.ts ~194) emits
-`body.theme-dark { background-color: ${bg} !important; }`, applied when
-`isDarkMode && !overrideColor` (style.ts ~320). That paints every section iframe's body
-opaque dark (`rgb(34,34,34)`), which occludes the host `.foliate-viewer::before` texture.
-Downstream it also poisons foliate: `resolveBackground(view.docBackground)` resolves the
-opaque body color, so `textureAwareBackground` keeps the paginated `#background` segment
-and the scrolled `view.element` inline bg opaque too. The #4399 fix is intact (container
-is transparent); this is a second, dark-mode-only occluder one layer deeper.
-
-- Paginated: segment + iframe body span the full viewer → no texture anywhere.
-- Scrolled: iframes cover only the text column → header/footer strips keep texture
-  (grid-cell + the #4486 notch overlay, see [[notch-mask-texture-4486]]).
-
-**Proof:** injecting `body.theme-dark{background-color:transparent !important}` into ALL
-section iframes + clearing the segment/view inline bgs reveals the leaves texture in both
-modes instantly.
-
-**Regression source (git-proven):** commit `176b950c9` = PR #4392 (2026-06-01, shipped
-v0.11.4) added the rule. NOT foliate-js — the foliate swipe-flash regression (#4399,
-167757a→142bf11) broke LIGHT-mode textures in the same release window, which is why it
-looked like one. The transformStylesheet light-bg rewriter (also #4392) was EXONERATED
-for the repro book: Alice's stylesheets have zero body/html background rules (verified by
-on-device stylesheet enumeration). **No #4392 revert needed** — its callout attribute
-selectors + rewriter fix real legibility bugs (#4028; #4419/#4426 build on them).
-
-**Fix (applied):** make the rule `background-color: transparent !important` —
-UNCONDITIONALLY, not gated on hasBackgroundTexture, because foliate captures
-`docBackground` once per section load (paginator.js `load` listener; `setStyles` re-runs
-`#replaceBackground` but never re-captures), so a texture-gated body bg would go stale on
-live texture toggling. Visuals without texture are identical: the dark fill comes from the
-paginator container `fallbackBg` / reader grid cell. Book-forced light page bgs stay
-neutralized (theme-dark fill shows through); page-level rewriter output is cascade-beaten
-by our `!important` body rule and later-in-head `html` rule; only book `!important`
-page rules survive — consistent with the #4399 "book-forced opaque page wins" policy.
-Test: `style-get-styles.test.ts` "#4446" cases. E2E device-verified: with the fixed CSS
-present at load, capture is transparent and the paginated segments array comes out EMPTY.
-
-**Verification gotchas (cost ~30 min):**
-- **Multiview!** The renderer shadow root holds MULTIPLE section iframes (adjacent preload).
-  Patching `sr.querySelector('iframe')` hits a section possibly 18k px off-viewport →
-  "fix didn't work". Patch every `sr.querySelectorAll('iframe')`.
-- `elementsFromPoint` reports the iframe ELEMENT's computed bg (transparent) — the
-  occluding paint is its content document's body, invisible to the top-doc/shadow stack walk.
-- Switching `renderer.setAttribute('flow', ...)` can reload section docs and silently wipe
-  styles injected into them (but not always — re-check after every flow switch).
-- Pseudo-element paint test: patch the `#background-texture` style text with
-  `background-color: red` — if red doesn't show, the pseudo is occluded, not broken.
-- **Stale preload views**: after patching styles via `renderer.setStyles`, views loaded
-  PRE-patch keep their opaque `docBackground` and `#clearViewsExcept` keeps `|i−index|≤2`
-  across navigation — an opaque segment can come from a kept old view, not the fresh one.
-  Jump ≥3 sections to guarantee fresh captures.
-- **Capture-time instrumentation**: the paginator dispatches `load` synchronously right
-  BEFORE `docBackground = getBackground(doc)` — an event listener on the renderer sees
-  exactly what the capture will see (class list, computed bgs, active rules).

apps/readest-app/.claude/memory/dblclick-drag-pageturn-4524.md

@@ -1,47 +0,0 @@
----
-name: dblclick-drag-pageturn-4524
-description: Web double-click-and-drag selection turned the page; deferred single-click fired mid-drag while button held
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 5fe20151-9768-4e7c-9cee-2aa25da5318c
----
-
-#4524: on Readest Web, **double-click a word then drag** to extend the native
-selection also **turned the page** (a plain double-click did not). The user
-expects browser-native double-click-drag word-by-word selection without a page
-turn.
-
-**Root cause** (`src/app/reader/utils/iframeEventHandlers.ts` `handleClick`):
-the first click of a potential double-click schedules a deferred
-`postSingleClick()` after `DOUBLE_CLICK_INTERVAL_THRESHOLD_MS` (250ms).
-- Plain double-click: the 2nd `click` fires fast, updates `lastClickTime`, posts
-  `iframe-double-click`; when the 1st click's timer fires, the
-  `Date.now() - lastClickTime >= 250` check is now false → single-click
-  suppressed → no page turn.
-- Double-click **+ drag**: the user holds the button down on the 2nd click and
-  drags, so the 2nd `mouseup`/`click` is delayed past 250ms. At first-click+250ms
-  `lastClickTime` is still the 1st click → check passes → `iframe-single-click`
-  posted **while the button is still held** → `usePagination.handlePageFlip`
-  turns the page.
-
-**Fix**: module-level `isMouseDown` flag (set in `handleMousedown`, cleared in
-`handleMouseup`); the deferred `postSingleClick()` returns early when
-`isMouseDown` is true (a drag is in progress). Cannot affect a normal single
-click — `isMouseDown` is false by the time its deferred timer fires; only a
-held button (drag) suppresses it.
-
-**Verification gotcha**: reproduced live by dispatching synthetic
-mousedown/mouseup/click to the reading iframe doc (found via deep shadow-DOM
-walk; the foliate iframe sits in nested shadow roots, `document.querySelectorAll('iframe')`
-returns 0). Watch `iframe-single-click` on `window` 'message' + the
-`.progress-info-label` "N / M" page text. NOTE: back-to-back synthetic gestures
-share the module's real `setTimeout` deferrals and `lastClickTime`, so a
-follow-up "normal single click" repro can spuriously show no single-click — the
-vitest unit test (fake timers) is the authoritative regression check, not
-chained browser repros. Iframe listeners are attached once
-(`detail.doc.isEventListenersAdded`), so a full page reload is required to pick
-up edits — Fast Refresh won't re-bind them.
-
-Test: `src/__tests__/reader/utils/iframeEventHandlers.test.ts`. Related:
-[[foliate-touch-listener-capture-phase]], [[progressbar-focus-ring-4397]].

apps/readest-app/.claude/memory/dependabot-pnpm-overrides.md

@@ -1,21 +0,0 @@
----
-name: dependabot-pnpm-overrides
-description: How to fix transitive-dependency Dependabot/CVE alerts in the readest monorepo (pnpm overrides location + style)
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: cdc9c728-a2c7-4a9e-b87a-44046560a4fa
----
-
-Transitive npm security advisories (Dependabot alerts against `pnpm-lock.yaml`) are fixed by pinning a **minimum patched version** in the `overrides:` block of **`pnpm-workspace.yaml`** at the monorepo root — NOT `package.json`'s `pnpm.overrides`.
-
-**Why:** the repo uses pnpm 9+ (`pnpm@11.x`), which reads `overrides`/`patchedDependencies`/`catalog` from `pnpm-workspace.yaml`. A `pnpm.overrides` block added to root `package.json` is silently ignored — `pnpm install` runs fast and the lockfile doesn't change. There is already a long list of security pins in that `overrides:` block (glob, undici, qs, body-parser, etc.).
-
-**How to apply:**
-1. `gh api repos/readest/readest/dependabot/alerts/<N>` → get package + `first_patched_version` + vulnerable range.
-2. Confirm parent ranges allow the patch (`cat node_modules/.pnpm/<parent>@*/.../package.json | grep '"<pkg>"'`).
-3. Add/raise the entry in `pnpm-workspace.yaml` `overrides:` in the existing style: `<pkg>: '>=<patched>'` (e.g. `shell-quote: '>=1.8.4'`). **Check for an existing too-low pin** — e.g. `qs: '>=6.14.2'` still allowed the vulnerable 6.15.1; had to raise to `'>=6.15.2'`.
-4. `pnpm install --lockfile-only` then `pnpm install`. Verify with `pnpm why -r <pkg>` (should show only the patched version). Stale dirs may linger in `node_modules/.pnpm` but are harmless if the lockfile has zero refs to the old version.
-5. Dependabot **alert numbers are not GitHub issue numbers** — don't use `Closes #N`; alerts auto-dismiss when the vulnerable version leaves the default-branch lockfile. Reference the `/security/dependabot/<N>` URLs in the PR body instead.
-
-First done in PR #4523 (shell-quote 1.8.4 / GHSA-w7jw-789q-3m8p, qs 6.15.2 / GHSA-q8mj-m7cp-5q26). Diff stays scoped to just the bumped packages; prefer this over `pnpm update <pkg>` which incidentally refreshes unrelated in-range patches (e.g. react-is). See [[feedback_pr_new_branch]] [[feedback_use_worktree]].

apps/readest-app/.claude/memory/deploy-workers-dev-sni-proxy.md

@@ -1,24 +0,0 @@
----
-name: deploy-workers-dev-sni-proxy
-description: "pnpm deploy crashes in China — workers.dev SNI-blocked, wrangler ws WebSocket bypasses http_proxy; fix = NODE_OPTIONS preload"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 65342d98-7939-41ed-9e10-2efc466946b1
----
-
-`pnpm deploy` (and `pnpm upload`) crashed for chrox (behind GFW, Privoxy at `http://127.0.0.1:8118`) with an **unhandled `ws` `'error'` event → Node process crash** (ETIMEDOUT to Facebook/Vultr/Twitter IPs).
-
-**Trigger:** `opennextjs-cloudflare deploy`/`upload` ALWAYS runs `populateCache({target:"remote"})` BEFORE the real deploy (no skip flag; only `cacheChunkSize`/`env` knobs). That step calls wrangler's `unstable_startWorker({remote:true})`, which opens a **WebSocket** to a `*.workers.dev` edge host. (`preview` uses `target:"local"` → unaffected.)
-
-**Root cause (two layers):**
-1. `*.workers.dev` is **SNI-blocked** by the GFW, not merely DNS-poisoned. Proof: encrypted DoH gives the REAL Cloudflare IPs (104.18.x), but a *direct* TLS connect to that correct IP with SNI=workers.dev is still `Connection reset by peer` before TLS starts. So **DoH/dnscrypt-proxy does NOT help** — the connection must avoid being made directly at all.
-2. wrangler's REST calls honor `http_proxy` (undici `ProxyAgent`/`EnvHttpProxyAgent`), but the raw `ws` handshake falls back to `https.globalAgent` and **ignores proxy env**. So it connects directly → SNI reset → crash. The crash fires async (unhandled WS 'error'), so `opennextjs-cloudflare deploy`'s `await` can't catch it.
-
-**Attempt 1 — proxy preload (tried, then REMOVED):** a zero-dep preload that replaced `https.globalAgent` with a `CONNECT`-tunnel agent (CONNECT hides the SNI = defeats the block + does remote DNS; loopback bypassed so the local populate worker on 127.0.0.1 still works). Verified `https.get('https://workers.dev')` → 301 via proxy. This got PAST the WebSocket crash — the local populate worker started and enumerated all 17 cache assets — **BUT the actual R2 writes through the remote binding then timed out** ("Failed to send request to R2 worker: aborted due to timeout", retrying forever). The proxy establishes the connection but can't reliably carry the sustained cache-write traffic. So the preload alone is NOT sufficient. Deleted it.
-
-**Attempt 2 — replicate `wrangler deploy` in the npm script (tried, then reverted):** skip populate by bypassing `opennextjs-cloudflare deploy` and running `CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false OPEN_NEXT_DEPLOY=true wrangler deploy` directly (traced from `runWrangler`: stock deploy's real step is plain `wrangler deploy` vs `wrangler.toml` which has `main=.open-next/worker.js`+all bindings; no generated config/skew mapping; the env flag stops wrangler 4.x auto-loading `.env`/`.dev.vars` into the worker — OpenNext's adapter handles env). Works, but hacky (replicates internals, drift risk).
-
-**Fix that SHIPPED — config flag (cleanest).** populateCache is gated by `if (!config.dangerous?.disableIncrementalCache && incrementalCache)`. So in `open-next.config.ts`: `config.dangerous = { ...config.dangerous, disableIncrementalCache: true }`. This makes the STOCK `opennextjs-cloudflare deploy`/`upload` skip populate (no script hack, no env flag, no drift) — reverted package.json to stock. Caveat: it's the SAME flag the runtime reads, so it ALSO disables the runtime incremental cache — **but readest uses ZERO ISR (no `revalidate`/`unstable_cache`/`'use cache'`/`generateStaticParams`), so runtime caching is a no-op anyway → no real loss.** Re-enable = delete the one line (from a network that can reach the CF edge). `defineCloudflareConfig` returns `OpenNextConfig` (broad type; `dangerous.disableIncrementalCache?: boolean` exists), tsgo+biome clean. `preview` was always fine (local populate).
-
-Related: [[turbopack-build-cache-oom-docker-standalone]], [[r2-rclone-createbucket-403]].

apps/readest-app/.claude/memory/deps-security-overrides-workflow.md

@@ -1,45 +0,0 @@
----
-name: deps-security-overrides-workflow
-description: "How to fix transitive npm Dependabot alerts in the readest monorepo (pnpm-workspace overrides, where config lives, tauri-plugins is separate)"
-metadata: 
-  node_type: memory
-  type: reference
-  originSessionId: c61e7dd2-4033-4bd1-8f32-22056e4ef322
----
-
-Fixing transitive npm Dependabot security alerts (manifest `pnpm-lock.yaml`).
-
-**Where pnpm config lives (non-obvious):** the MAIN monorepo's `overrides`,
-`patchedDependencies`, `onlyBuiltDependencies`, `allowBuilds` are in
-**`pnpm-workspace.yaml`** (newer pnpm style) — NOT the root `package.json`
-(root `package.json` has no `pnpm` section). The root `pnpm-lock.yaml` is what
-Dependabot scans; alerts report manifest `pnpm-lock.yaml` = this root lockfile.
-
-**`packages/tauri-plugins` is a SEPARATE project**, not part of the main pnpm
-workspace. It's a git submodule (`tauri-plugins-workspace`) with its OWN
-`pnpm-lock.yaml` and its own `package.json` `pnpm.overrides` +
-`minimumReleaseAge: 4320`. The `minimumReleaseAge` (3-day age gate) applies ONLY
-there — the main monorepo has NO age gate, so `^X` specs resolve to the very
-latest matching version. Dependabot does not scan the tauri-plugins lockfile.
-`pnpm-workspace.yaml` `packages:` = `apps/*`, send-email worker, extensions,
-`packages/foliate-js` (NOT tauri-plugins).
-
-**Recipe for a transitive advisory:**
-1. Add `pkg: '>=X.Y.Z'` to the `overrides:` block in `pnpm-workspace.yaml`
-   (forces all transitive instances up). For risky 0.x packages, BOUND it like
-   the existing `vite: '>=7.3.2 <8'` (e.g. `esbuild: '>=0.28.1 <0.29'`).
-2. For packages that are also DIRECT deps, bump the spec in
-   `apps/readest-app/package.json` too (e.g. the vitest family:
-   `vitest`, `@vitest/browser-playwright`, `@vitest/browser-webdriverio`,
-   `@vitest/coverage-v8` — move in lockstep).
-3. `pnpm install`, then `grep -oE "pkg@[0-9.]+" pnpm-lock.yaml | sort -u` to
-   confirm no vulnerable versions remain.
-4. Verify: `pnpm test` + `pnpm lint` + `pnpm build-web` (the last exercises
-   esbuild in the OpenNext/Cloudflare bundle path).
-
-**Override applicability:** an override forces a transitive version regardless
-of the parent's declared range ONLY when the package is a regular dep (no peer
-warning). esbuild is a regular dep of vite; vite 7.3.x pins esbuild `^0.27.0`
-but esbuild 0.28.x is API-compatible for vite's usage (0.28 changelog = install
-integrity + minifier/codegen fixes). Verified via PR #4618 (alerts #238/#239
-esbuild→0.28.1, #240 @vitest/browser→4.1.9).

apps/readest-app/.claude/memory/dict-import-contenturi-filename-4489.md

@@ -1,45 +0,0 @@
----
-name: dict-import-contenturi-filename-4489
-description: "Android dict import \"incomplete bundle\" — ext-less content URIs; classify used getFilename (string) not basename (content resolver)"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 92f1011c-89b9-4ae1-b128-f24cfb4462a8
----
-
-#4489 / #4472: importing a StarDict bundle (`.ifo`+`.idx`+`.dict.dz`) on **some** Android
-devices fails with "Skipped incomplete bundles"; works on Xiaomi/Boox and web.
-
-**Root cause — two filename resolvers diverged.** Tauri's Android `path.file_name`
-(used by `basename`) special-cases `content://`/`file://` URIs and calls the native
-`getFileNameFromUri` plugin → **content resolver DISPLAY_NAME** (real filename WITH ext).
-See `tauri-2.11.2/src/path/android.rs`. Our `getFilename()` (`src/utils/path.ts`) is pure
-JS string-parse of the URI. On devices whose SAF URI is an **opaque ext-less document id**
-(e.g. `content://com.android.providers.downloads.documents/document/msf%3A20`), getFilename
-→ `msf%3A20` (no ext) while basename → `21cen.dict.dz`. Working devices return
-`primary%3ADictionaries%3A21cen.dict.dz` (ext in the URI) so getFilename happens to work.
-
-The OLD `selectFileTauri` extension filter ALREADY used `basename` (so files passed the
-filter and got imported), but **threw the resolved name away** and returned the raw URI.
-Then `dictionaryService.classify()` re-derived the name with `getFilename()` → no ext →
-every file orphaned → "incomplete bundle". The bug is the divergence, not the picker.
-
-**Fix (PR for #4489):**
-- `SelectedFile.name?: string` added (`useFileSelector.ts`).
-- `resolveTauriFileName(path, appService)`: `basename` for `content://` / iOS `file://`,
-  else `getFilename` — resolved ONCE in `selectFileTauri`, reused by the ext filter AND
-  stored on `SelectedFile.name`. Removed `processTauriFiles`.
-- `classify()` (`dictionaryService.ts`): `source.file?.name ?? source.name ?? getFilename(path)`.
-- Test: `groupBundlesByStem.test.ts` — ext-less content URIs + `name` form a complete bundle.
-- Also fixes #4472 issue 3 (uploaded dict files renamed to the SAF dir path).
-
-**Emulator repro (real granted URI, no rebuild needed):** drive SAF picker → "Downloads"
-location → returns `content://...downloads.documents/document/msf%3A<id>` (ext-less).
-basename resolves the real name ONLY for granted URIs (synthetic URIs → "path does not have
-a basename"). Verified via CDP `invoke('plugin:path|basename',{path,ext:null})`. See
-[[cdp-android-webview-profiling]] for the CDP harness (`src/__tests__/android/helpers/`).
-
-**Also fixed same turn:** e-ink "black spot" on the Settings→Dictionaries `+` badges
-(Import Dictionary / Add Web Search) — add `eink-inverted` to the round badge span, mirroring
-the font import button #4454 (`globals.css` `[data-eink] .eink-inverted` → base-content bg +
-base-100 icon).

apps/readest-app/.claude/memory/dict-lemmatization-4574.md

@@ -1,22 +0,0 @@
----
-name: dict-lemmatization-4574
-description: "Dictionary lookup lemmatizes inflected words (ran→run, mice→mouse) before lookup; pluggable per-language registry, English impl, candidate-chain integration"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: d4206b72-47da-4c3d-adab-04df32c1137a
----
-
-#4574 FR: dictionary lookup should normalize inflected forms before lookup. Dicts that store only base headwords (Oxford Dictionary of English, Cambridge, Longman) miss `ran`/`mice`/`children`/`analyses`/`realised` even though `run`/`mouse`/`child`/`analysis`/`realise` exist.
-
-**Integration point** (single, central): `src/services/dictionaries/lookupCandidates.ts` `buildLookupCandidates(word, lang?)` — appends `getLemmaCandidates(lower, lang)` to the tail of `[trimmed, lower, title, upper]`. Lemmas sit AFTER exact/case so exact match always wins. The pre-existing lookup loop in `DictionaryResultsView.tsx` (`useDictionaryResults`, shared by desktop popup + mobile sheet) tries each candidate and breaks on first non-empty hit; wiring was a one-liner passing `langCode` (already in effect scope) as the 2nd arg. Applies to ALL definition providers (mdict/stardict/dict/slob + online builtins).
-
-**New module** `src/services/dictionaries/lemmatize/`:
-- `index.ts` — `getLemmaCandidates(word, lang)` + `Record<string, Lemmatizer>` registry (`Lemmatizer = (word)=>string[]`). Lang normalized via `normalizedLangCode` (utils/lang.ts) to primary subtag. **Missing/empty lang defaults to `'en'`** (`normalizedLangCode(lang) || 'en'`); **explicit non-English with no registered lemmatizer → `[]`** (we never force English onto e.g. `fr`/`zh`). Add a language = register one fn, no caller changes.
-- `english.ts` — `lemmatizeEnglish(word)`: `IRREGULAR_GROUPS` (base→[forms], flattened to inflected→base at load) for suppletive verbs / irregular plurals / irregular comparatives, + regular suffix rules (plural -s/-es/-ies→y/-ves→f,fe/-ses→sis; past -ed/-d/-ied→y + de-double; -ing + e-restore + de-double + -ying→ie; comparative -er/-est/-ier→y; possessive `'s`; adverb -ly). ASCII-single-token guard `/^[a-z][a-z'’-]*$/` (no-op on phrases/numbers/CJK/accented). Lowercases input; never returns the input itself or single letters.
-
-**Key design insight: over-generate, let the dictionary validate.** The lemmatizer need not be linguistically precise — a bogus stem just misses and the loop moves on. So rules can be liberal. Cost is bounded: lemmas only fire AFTER exact+case all return empty (genuine "not a headword"), and the English rules produce ~2–5 candidates.
-
-**Ordering gotcha**: `-ses→-sis` rule must come BEFORE generic `-es`/`-s` so `analyses`→`analysis` (the issue's expected noun) is tried ahead of `analyse` (the verb). Both are linguistically valid for `analyses`; issue wants the noun.
-
-Tests: `__tests__/services/dictionaries/lemmatize/{english,index}.test.ts` + extended `lookupCandidates.test.ts` (all 8 issue cases asserted). Existing trim test's `spaced` sample swapped to `planet` (non-inflecting) since no-lang path now defaults to English lemmatization. Pure functions, fully deterministic — no live MDX needed. Related: [[dict-lookup-browser-hijack-4559]], [[wordlens-feature]].

apps/readest-app/.claude/memory/dict-lookup-browser-hijack-4559.md

@@ -1,17 +0,0 @@
----
-name: dict-lookup-browser-hijack-4559
-description: Android system-dictionary lookup landing in the OEM browser instead of Eudic/欧路 — package-visibility + PROCESS_TEXT browser hijack
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 5e397668-b766-439c-873c-00ccb1da715a
----
-
-#4559 (PR #4568): on VIVO/iQOO (OriginOS) the system-dictionary lookup opened `com.vivo.browser/.BrowserActivity` instead of an installed dictionary. TWO root causes, both in the Android half of `show_lookup_popover` (`tauri-plugin-native-bridge/.../NativeBridgePlugin.kt`):
-
-1. **Package-visibility filtering (primary).** App is `targetSdk 36`, but the native-bridge manifest had NO `<queries>` for `ACTION_PROCESS_TEXT`. Under Android 11+ filtering, `queryIntentActivities(PROCESS_TEXT)` then returns only *auto-visible* apps — web browsers are auto-visible (web-intent exception), arbitrary dictionary apps (Eudic/欧路/GoldenDict) are NOT. So the query returned just the browser. Fix = add `<queries><intent><action PROCESS_TEXT/><data text/plain/></intent></queries>` to the plugin manifest (mirrors the native-tts `TTS_SERVICE` pattern). This alone is likely the whole user-visible fix.
-2. **Browser hijack.** Even when visible, an OEM browser registering `ACTION_PROCESS_TEXT` can be the system default and swallow a plain `startActivity`. Fix = filter browsers out of the handler set in a pure `decideLookupDispatch(handlers, browserPackages, remembered)` (new `LookupDispatch.kt`, JUnit-tested): no-browser → implicit (unchanged, keeps native "Always"); browser+1 dict → explicit `setClassName` direct launch; browser+≥2 → `createChooser` + `EXTRA_EXCLUDE_COMPONENTS`; browser-only → `unavailable:true`. Browsers detected via `queryIntentActivities(ACTION_VIEW https + BROWSABLE)` (auto-visible, no `<queries>` needed).
-
-**Remember-the-choice** (the maintainer wanted "smooth once chosen"): `ACTION_CHOOSER` has NO native "Always" button (mutually exclusive with `EXTRA_EXCLUDE_COMPONENTS` — the resolver that *has* Always can't exclude and obeys the browser default). Re-implemented Always: pass an `IntentSender` to `createChooser`; system returns `EXTRA_CHOSEN_COMPONENT` to a manifest `LookupChoiceReceiver` (exported=false; explicit intra-app PendingIntent so non-exported is fine; FLAG_MUTABLE on S+) which persists pkg/class to a plain SharedPreferences (`readest_lookup_dictionary_v1`). Next lookup fast-paths it. Reset UI: `get_lookup_dictionary`/`clear_lookup_dictionary` commands (build.rs COMMANDS + default.toml + autogenerated TOMLs/schema/reference regenerate on `cargo build -p tauri-plugin-native-bridge`) → Android-only conditional reset row in `CustomDictionaries.tsx`, only shown when something is actually remembered (`getRememberedLookupApp` returns null otherwise, so no clutter).
-
-Maintainer DECLINED a settings picker to pre-pick a specific app ("we won't call the app directly"); browser-exclusion respects that (dynamic, not a user-set hardcode). Verified: gradle JUnit (7 cases) + vitest (12). `test:rust`/`clippy` were blocked by UNRELATED stale shared-`target/` cache (deleted sibling worktree `readest-feat-android-rangefile-protocol` path in `fs` plugin permission scan) — not my change; validated Rust via targeted plugin build. Related: [[android-open-with-intent-flow]], [[android-nativefile-remotefile-io]].

apps/readest-app/.claude/memory/dict-popup-font-size-4443.md

@@ -1,45 +0,0 @@
----
-name: dict-popup-font-size-4443
-description: Adjustable dictionary popup font size via ::part() + em-rebasing; the only cross-shadow font hook for MDict
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: b105ba93-61b7-4d28-a269-1201a7be89bd
----
-
-#4443 — adjustable dictionary popup font size (independent of the reading view).
-SHIPPED: merged to main via PR #4734.
-
-**The lever** = `DictionarySettings.fontScale` (number, default 1), set in
-Settings → Language → Dictionaries (`SettingsSelect`, 85–175%). Stored in the
-dictionary settings; SYNCED by adding `dictionarySettings.fontScale` to
-`SETTINGS_WHITELIST` (whole-field LWW, like providerOrder). `setFontScale` in
-`customDictionaryStore` + default-merge in `loadCustomDictionaries`
-(`?? DEFAULT_DICTIONARY_SETTINGS.fontScale`).
-
-**Plumbing**: `useDictionaryResults` returns `fontScale`; `DictionaryResultsBody`
-puts `data-dict-content` + inline `--dict-font-scale` on each per-tab container
-(the `setContainerRef` div). All CSS lives in `globals.css`.
-
-**Two non-obvious CSS facts that drove the design:**
-1. **MDict renders into a Shadow DOM** (`shadowHost.attachShadow`, the only
-   provider that does) → its body is unreachable by ordinary popup CSS.
-   `::part(dict-content)` is the ONLY hook. So `mdictProvider` sets
-   `body.setAttribute('part','dict-content')` AND adds a stable host class
-   `dict-shadow-host` (the `::part()` rule needs a host selector subject).
-   `--dict-font-scale` inherits across the shadow boundary, so the outer rule
-   `…::part(dict-content){font-size: calc(var(--dict-font-scale,1) * 0.875rem)}`
-   resolves it. The dict's own shadow CSS never targets our wrapper `<div>`, so
-   no cascade fight — em-based dict content scales from it, px-based stays fixed
-   (expected for a font-size lever).
-2. **Light-DOM providers size text with Tailwind `text-*` = root-relative `rem`**,
-   which a container `font-size` can't move. Fix = re-base the utilities to `em`
-   WITHIN `[data-dict-content]` only: `[data-dict-content] .text-sm{font-size:.875em}`
-   etc. Higher specificity than the bare utility + declared after `@tailwind
-   utilities` → wins, no `!important`. Container itself = `calc(scale * 1em)`.
-
-**Verify**: the CSS contract (em-rebasing + `::part` + var inheritance) needs a
-real browser — jsdom has no layout. Covered by
-`dict-popup-font-size.browser.test.ts` (scale 1 → 18/14/14px, scale 1.5 →
-27/21/21px, incl. the shadow body). Provider/store/whitelist sides have jsdom
-unit tests. See [[css-style-fixes]].

apps/readest-app/.claude/memory/download-file-scope-android-regression.md

@@ -1,22 +0,0 @@
----
-name: download-file-scope-android-regression
-description: "#4639 strict is_allowed broke ALL Android downloads to app data dir (covers/dicts/books); fix = app.path() base-dir membership, not glob scope"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: e78227be-6260-405a-88fb-48ffe4b20615
----
-
-Regression from [[security-advisories-web-2026-06]] PR #4639 (commit 4025c4d7b). On Android every `download_file` into the app's own data dir failed: `permission denied: path not in filesystem scope: /data/user/0/com.bilingify.readest/Readest/{Books/<hash>/cover.png, Dictionaries/<id>/*.mdx, ...}`. The error string IS `transfer_file.rs Error::Forbidden` from `ensure_path_allowed`.
-
-**Root cause (non-obvious):** `app.fs_scope().is_allowed(p)` returns **false** for the app's own files on Android. `FsExt::fs_scope()` returns the GLOBAL `state::<Scope>().scope`, but the capability scope patterns that cover the data dir (`$APPDATA/Readest/**/*`, `**/Readest/**/*`) are **command-scoped**, NOT in that global scope. The fs plugin's `resolve_path` (tauri-plugin-fs `commands.rs`) passes because it checks `fs_scope.scope.is_allowed(p) || scope.is_allowed(p)` where the 2nd `scope` is rebuilt from `global_scope.allows()+command_scope.allows()` per-command — that's where those patterns live. This is the SAME gap `dir_scanner::read_dir` works around with `|| contains("Readest")`. So #4639's note "Chose STRICT is_allowed (NOT read_dir's contains-Readest hatch)" was the bug — strict `is_allowed` rejects the app's own dir on Android.
-
-Why fs-plugin writes work but `download_file` didn't: app writes via `baseDir: AppData` + relative path → `webview.path().resolve(rel, AppData)` → canonical form matched by the per-command scope. `download_file`/`upload_file` use raw `tokio::fs` with a JS-supplied ABSOLUTE path, so none of that applies.
-
-**WRONG first attempt (don't repeat):** canonicalizing the symlink (`/data/user/0/<pkg>` → `/data/data/<pkg>`, since `is_allowed` only canonicalizes EXISTING paths and a download target doesn't exist yet) then re-calling `is_allowed`. Verified on-device it STILL fails — the patterns aren't in the global scope at ALL, so no path form matches. The canonicalize-existing-ancestor helper is still useful, just for the prefix check below, not for `is_allowed`.
-
-**Shipped interim fix** (PR #4651, commit 75b469931): owner rejected the base-dir-membership version as over-engineered ("bloody hard coded" dir list) and asked to mirror `dir_scanner` instead. `ensure_path_allowed` = reject relative+`..` (`has_disallowed_components`) → `if app.fs_scope().is_allowed(p) || is_within_app_storage(p) Ok`. `is_within_app_storage(file_path, app_identifier) = file_path.contains("Readest") || file_path.contains(app_identifier)` where `app_identifier = &app.config().identifier` (NOT a hardcoded literal; `config()` is inherent on AppHandle — NO `use tauri::Manager`). The bundle id (`com.bilingify.readest`) is in EVERY Android sandbox path incl. the cache dir, so it closes the OPDS-to-`$APPCACHE` gap that `contains("Readest")` alone misses (`Readest` is the `DATA_SUBDIR`, capital-R; cache dir has only the lowercase bundle id). `..` rejection keeps GHSA-55vr-pvq5-6fmg (`~/.ssh/id_rsa` has neither marker). Substring posture = same as `dir_scanner`. **Follow-up (deferred):** replace the substring fallback with `BaseDirectory`+relative resolved via `app.path()` (the app already has `appService.resolvePath()` → `{baseDir, fp}`; callers currently flatten it to an absolute string) so targets are in-scope by construction.
-
-(Rejected earlier attempt, kept for context: base-dir-membership via `app.path()` dirs + `is_inside_any` canonicalizing both sides for the `/data/user/0`↔`/data/data` symlink. Correct but owner found the dir enumeration ugly.)
-
-**On-device verify recipe (Xiaomi fuxi 2211133C, real release-signed devtools build):** `pnpm dev-android` = `tauri android build -t aarch64 -- --features devtools && adb install -r .../app-universal-release.apk`. Local keystore (`gen/android/keystore.properties` → `/Users/chrox/dev/Android/keys/upload-readest-keystore.jks`, alias `upload`) matches installed signer → `-r` PRESERVES user data (dicts/books). CDP probe: `adb forward tcp:9333 localabstract:webview_devtools_remote_<pid>` (socket name = app pid; stale sockets linger — pick the one matching `adb shell pidof`); fetch `/json/list` via node http (NOT curl — mishandles WebView framing); Node v24 has global `WebSocket`. Raw `invoke('download_file',...)` needs a Channel for `on_progress`: pass `{ ['__TAURI_TO_IPC_KEY__']: () => '__CHANNEL__:'+I.transformCallback(()=>{}) }`. Result: in-scope `/data/user/0/.../Readest/x.bin` → OK; `/data/local/tmp/evil.bin` → still Forbidden. `appData=/data/user/0/com.bilingify.readest` (no `/files`); appCache/temp=`.../cache`.

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

@@ -1,40 +0,0 @@
----
-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/duokan-fullscreen-cover-scroll.md

@@ -1,21 +0,0 @@
----
-name: duokan-fullscreen-cover-scroll
-description: "Duokan fullscreen cover image invisible in scrolled mode (#4379) — paginator pins it position:absolute height:100% which collapses against auto-height scroll container"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: c45aabf0-e8a3-42b6-a5fd-c04d6eb2345c
----
-
-Issue #4379: an EPUB cover with `data-duokan-page-fullscreen` on `<html>` (Duokan/DangDang convention) shows in paginated mode but is **blank in scrolled mode**; only the first cover image, other images fine in both modes.
-
-**Root cause** — `View.setImageSize()` in `packages/foliate-js/paginator.js` has a `pageFullscreen` branch that pins each img with `position:absolute; inset:0; width:100%; height:100%` and forces ancestors + `<html>` to `height:100%`/`position:relative`. This fills the page in paginated/columnized mode (html has a fixed pixel height). In scrolled mode `scrolled()` sets `html`/`body` height to `auto`, so the `height:100%` chain resolves to **0** and the absolutely-positioned cover collapses out of view (offsetHeight 0).
-
-**Fix** — gate the fullscreen treatment on column mode: `const applyFullscreen = pageFullscreen && this.#column`. Use `applyFullscreen` for the max-height/max-width margin term and the `if` block. Add an `else if (pageFullscreen)` that `removeProperty`s the stale `position/inset/width/height/margin` on the img (and `width/height/margin/padding` on ancestors, `position` on html) so toggling paginated→scrolled doesn't leave the cover collapsed (same iframe/img is reused via `view.render(layout)` on `flow` change). In scrolled mode the cover then flows like a normal full-page image bounded by `max-height = availableHeight`.
-
-**Key facts**
-- `this.#column = layout.flow !== 'scrolled'` (set in `render()` before `setImageSize`), so it's reliable inside `setImageSize`.
-- Foliate writes these styles as **inline `!important`** → cannot be overridden from `src/utils/style.ts`; the fix must live in the paginator.
-- Regression test: `src/__tests__/document/paginator-duokan-cover.browser.test.ts` + fixture `repro-4379.epub` (cover xhtml with the duokan attr + dimensionless `<img>`). Asserts cover `img.offsetHeight > 0` in scrolled mode, paginated sanity, and paginated→scrolled toggle. Browser test (real layout) is required — jsdom can't compute the collapse.
-
-Related: [[paginator-swipe-bg-flash]], [[css-style-fixes]].

apps/readest-app/.claude/memory/edge-tts-word-highlighting-4017.md

@@ -1,23 +0,0 @@
----
-name: edge-tts-word-highlighting-4017
-description: "Edge TTS word-by-word highlighting (#4017, PR"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: afd9b381-c17d-4988-b287-07263d8bea0b
----
-
-# Edge TTS word-by-word highlighting (#4017, PR #4566)
-
-**Design: keep sentence granularity, add word highlight on top.** All clients still report `getGranularities() = ['sentence']` — switching foliate to word marks would regress media-session metadata (one word on lock screen), byMark seek (word steps), `getSpokenSentence`, and per-word synthesis. Instead: `EdgeSpeechTTS.createAudio()` returns `{url, boundaries}` (cached per payload-hash next to the blob URL), `EdgeTTSClient` runs a rAF loop syncing `audio.currentTime` (media time → playbackRate/pause-safe) against boundary ticks, and `TTSController.prepareSpeakWords/dispatchSpeakWord` match words sequentially (`indexOf` with a moving cursor; unmatched word = skip WITHOUT advancing cursor) against the sentence range text, then highlight the sub-range via the existing `#getHighlighter`.
-
-**Edge wire facts** (verified with raw WS probe + live):
-- `audio.metadata` frames: `{"Metadata":[{"Type":"WordBoundary","Data":{"Offset":1000000,"Duration":4250000,"text":{"Text":"Dr.","Length":3}}}]}` — one word/frame, ticks = 100 ns (1e7/s), offsets relative to this request's audio stream.
-- `Text` is the **verbatim input span** ("Dr.", "23", "$5.50" keep punctuation; trailing sentence punctuation stripped) → sequential indexOf matching is robust. Works for zh too.
-- The readaloud endpoint gates on **User-Agent (needs Edg/non-headless), NOT Origin** — a localhost Origin with Edg UA is accepted; default HeadlessChrome UA is rejected (close 1006).
-
-**Pre-existing bug fixed in the same PR:** browser branch did `new WebSocket(url, {headers})` → native WebSocket parses the object as a subprotocol → `SyntaxError` → on web the wss path could NEVER work (always https-proxy fallback, which strips boundaries). Node-only options now.
-
-**Probe gotchas:** Overlayer draws the highlight as a `<path>` inside `<g fill="#808080">` (NOT `<rect>` — rect-only DOM probes miss it); the overlayer svg lives in `FOLIATE-PAGINATOR`'s open shadow root (sibling layer of the iframe, not inside it). TTS auto-advance creates new views — re-query svgs per sample, never cache the list.
-
-**dev-web live-verify recipe:** gstack `browse --proxy http://127.0.0.1:8118` (flag needed on EVERY invocation; this machine's external net needs the local proxy, headless Chromium doesn't inherit it) + `browse useragent '...Edg/143...'` (context-level, doesn't break Next) — do NOT use `browse header Origin:...` (extra headers hit localhost too → Next dev 403s ALL chunks → blank page; headers can't be removed without daemon restart). Import books via synthetic drop: fetch epub from `public/`, `DataTransfer` + `DragEvent('drop')` on `.library-page` (in-memory only — re-import after every reload/restart). Patch `content.overlayer.add/remove` to log the real highlight calls — the ground truth when screenshots race. Related: [[tts-fixes]]

apps/readest-app/.claude/memory/eink-screen-refresh-pageturner-4687.md

@@ -1,30 +0,0 @@
----
-name: eink-screen-refresh-pageturner-4687
-description: "Page-turner \"Refresh Page\" action that deep-refreshes the e-ink panel (clear ghosting) on Android, via generic reflection across BOOX/Tolino/Rockchip"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 742b1517-392b-4735-8355-32b57fbfa400
----
-
-Issue #4687 — added a bindable **"Refresh Page"** page-turner action that triggers a deep e-ink full refresh (GC16) to clear ghosting. Shipped as **PR #4822 (MERGED)** (`feat/eink-screen-refresh-pageturner` → main, 55 files +470/-41), built in an isolated worktree off origin/main (worktree + branch since removed). Rebase note: origin/main's Drive-sync PR #4821 added `secure_item` native-bridge commands at the exact anchors I used (end of COMMANDS / handler list / structs / impls), so all 7 plugin files (build.rs, default.toml, commands.rs, desktop.rs, lib.rs, mobile.rs, models.rs) conflicted on apply — resolved "keep both" by re-adding `refresh_eink_screen` after the secure_item code; locales re-derived via script on main's current files; autogenerated permission files regenerated via `cargo check -p tauri-plugin-native-bridge`.
-
-**Frontend** (reuses the existing hardware page-turner binding machinery — see [[keyboard-selection-adjust-4728]] / `src/utils/keybinding.ts`):
-- `keybinding.ts`: `'refresh'` added to `PageTurnAction` + `PAGE_TURN_ACTIONS` (so `resolvePageTurn` matches it). `matchesBinding` now accepts `undefined`.
-- `types/settings.ts`: `HardwarePageTurnerSettings.bindings.refresh?: KeyBinding | null` — OPTIONAL (older persisted settings lack it; never migrate, optional-chaining handles absence). Default `refresh: null` in `constants.ts`.
-- `PageTurnerSettings.tsx`: refresh slot rendered ONLY when `appService?.isAndroidApp && viewSettings.isEink` (the user-facing Eink-mode view setting, not just hardware detection).
-- `usePagination.ts` `handleHardwarePageTurn`: branch `if (action === 'refresh') { if (appService?.isAndroidApp) refreshEinkScreen().catch(()=>{}); return true; }` BEFORE the page/section side/mode logic. Also added `bindings.refresh?.source === 'native'` to `hasNativeBinding` + the effect dep array so a media key bound to refresh still acquires page-turner key interception.
-- `bridge.ts`: `refreshEinkScreen()` → `invoke('plugin:native-bridge|refresh_eink_screen')`.
-
-**Native generic refresh** (`EinkRefreshController.kt`, new) — the answer to "compatible with most e-ink devices, generic interface not brand SDK". Android has NO public e-ink API; each vendor patches `android.view.View`. Probe via reflection, stop at first success (patterns from KOReader android-luajit-launcher EPD controllers):
-1. **Onyx BOOX (Qualcomm)**: `View.refreshScreen(0,0,w,h, 34)` instance method. `34 = FULL(32)+GC16(2)`.
-2. **Tolino/Nook (NTX/Freescale)**: `View.postInvalidateDelayed(0L,0,0,w,h, 34)`.
-3. **Rockchip (Boyue clones)**: `View.requestEpdMode(View$EINK_MODE.EPD_FULL, true)`.
-
-Deliberately do NOT bundle the Onyx SDK (`com.onyx.android.sdk.*` classes aren't on-device unless bundled — reflection would always fail) and do NOT call Onyx `setWaveformAndScheme`/None (KOReader does, but it owns the update loop; Readest leaves system auto-update in place, so switching to manual mode could FREEZE later updates). Run on UI thread against `activity.window.decorView`; `success:false` (no controller) is a soft no-op, not an error. iOS Swift stub resolves `{success:false}`.
-
-**Plugin wiring** added across `models.rs`/`commands.rs`/`mobile.rs`/`desktop.rs`/`lib.rs` + `build.rs` COMMANDS + `permissions/default.toml` `allow-refresh-eink-screen` (build regenerates `reference.md`/`schema.json`/`commands/refresh_eink_screen.toml`). App uses `native-bridge:default` so no capability edit needed.
-
-**Verified on real hardware**: ONYX BOOX Leaf5 (`ro.product.manufacturer=ONYX`). `pnpm dev-android` build+install; via adb+CDP invoked `plugin:native-bridge|refresh_eink_screen` directly in the WebView → `{success:true}`, logcat `EinkRefresh: onyx full refresh requested` (the Onyx/Qualcomm `View.refreshScreen` path, decor view), and the user visually confirmed 5/5 full GC16 screen flashes in the reader. So the onyx path works on modern BOOX without SDK bundling or `setWaveformAndScheme` priming. (CDP socket is pid-bound `webview_devtools_remote_<pid>`; re-forward when the WebView process recycles — see [[cdp-android-webview-profiling]].)
-
-**i18n**: ran into [[i18n-extract-prunes-keys]] (scanner `removeUnusedKeys:true` deleted ~314 dynamic keys / huge churn). REVERTED the scanner output and added the single `"Refresh Page"` key MANUALLY to all 33 non-en locales (en is key-as-content, needs no entry), aligning each translation with the locale's existing `"Reload Page"`/`"Next Page"` terminology. `check:translations` green.

apps/readest-app/.claude/memory/empty-highlight-leak-on-annotate-cancel-4791.md

@@ -1,46 +0,0 @@
----
-name: empty-highlight-leak-on-annotate-cancel-4791
-description: Annotate eagerly creates a highlight placeholder; cancelling the note must tear it down
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 1c75c865-8e1b-4641-ac20-81692d3ff20b
----
-
-#4791 — clicking **Annotate** on a selection eagerly creates a highlight (`note:''`)
-as the note anchor (`handleAnnotate` → `handleHighlight(true)` in `Annotator.tsx`),
-so the selection stays visible while the NoteEditor is open. Cancelling the note
-(Cancel button, overlay, Escape, switching books, closing the notebook) left that
-empty highlight leaked into config → showed as a stale card in the left-sidebar
-Booknotes list + a phantom yellow highlight.
-
-**Fix:**
-- `handleHighlight` now returns the created `BookNote` only when it pushes a NEW
-  record (returns `null` when it restyles/toggles an EXISTING one — that record
-  predates the flow and must survive a cancel).
-- `handleAnnotate` stores `created?.id` via `setNotebookNewHighlightId` (new
-  `notebookStore` field). This tracked id is what distinguishes a removable
-  placeholder from a pre-existing highlight; do NOT identify it by cfi (a fresh
-  selection can collide with an existing highlight's cfi).
-- `removeEmptyAnnotationPlaceholder(booknotes, id, now)` in `annotatorUtil.ts`
-  tombstones (`deletedAt`) the live annotation with that id ONLY if it still has
-  no note text, and returns it so the caller tears the overlay down with
-  `removeBookNoteOverlays` across ALL views (`getViewsById`, symmetric with how
-  `handleHighlight` drew it).
-- Cleanup is **presentation-driven**, not threaded through every cancel path:
-  `Notebook.tsx` runs `handleCancelNewAnnotation` from an effect whenever the
-  creation editor stops being presented (`!(isNotebookVisible && notebookNewAnnotation)`)
-  — catches Cancel/Escape/overlay/close/swipe/navigate — plus a second effect's
-  cleanup on `sideBarBookKey` change / unmount for book-switch (pinned) and
-  reader-close.
-- Save survives the guard (placeholder gains note text) and also clears the
-  tracked id. `handleCancelNewAnnotation` has stable identity (empty deps) so the
-  effects don't re-fire mid-edit; it reads settings fresh via
-  `useSettingsStore.getState().settings` (stale-closure guard, see [[webdav-connect-nullified-4780]]).
-
-**Why id-set-LAST in handleAnnotate matters:** `setNotebookNewHighlightId` is
-called after `setNotebookVisible(true)` + `setNotebookNewAnnotation`, so no
-intermediate render has (editing=false AND a fresh placeholder id) — prevents the
-presentation effect from deleting the placeholder it just created.
-
-Related: [[instant-highlight-delete-orphan-4773]], [[customize-toolbar-global-serializeconfig]].

apps/readest-app/.claude/memory/empty-start-cfi-sync.md

@@ -1,53 +0,0 @@
----
-name: empty-start-cfi-sync
-description: "Invalid synced-progress CFIs like epubcfi(/6/24!/4,,/20/1:58) — the empty-start range bug from the cfi-inert skip-link, and the read-side normalizeLocationCfi sanitizer"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: ffa4a291-55fa-4cd5-8e35-0ac2852ff5c9
----
-
-Synced progress CFIs of the form `epubcfi(/6/24!/4,,/20/1:58)` (a range with an
-**empty start** component — the `,,`) are invalid: the start collapses to the
-section beginning `(body, 0)` while the end reaches the section's last block, so
-a receiving device navigates to the **wrong end** of the section.
-
-**Root cause** — the cfi-inert a11y skip-link (`a11y.ts` prepends a 1×1
-`position:absolute` `<div cfi-inert>` as body's first child). There was a
-~2.5-month transitional window (foliate `c558766` 2026-03-11 → `569cc06`
-2026-05-30) where `epubcfi.js getChildNodes` already skipped `cfi-inert` but
-`paginator.js getVisibleRange` did **not** yet reject it. The relocate range's
-START could anchor on the skip-link; `fromRange`→`nodeToParts` asks for its
-index, `getChildNodes` filters it out, `findIndex` returns -1, the
-`.filter(x => x.index !== -1)` drops the step, and the start collapses to the
-body boundary → empty start. (Symmetric empty-END form from the next-section
-skip-link on a section's last page.)
-
-**Generation is fixed** by `569cc06` (live on `dev` via `c23c21d37`) — but that
-does NOT repair CFIs already stored on the sync server. Those keep being served.
-
-**Fix (this work):** `isMalformedLocationCfi(cfi)` predicate in `src/utils/cfi.ts`
-— true for a degenerate range (empty `parts.start` or `parts.end` via
-`CFI.parse`). Chose **discard over repair** (user call): don't derive a position
-from a corrupt CFI; drop it and let a known-good fallback win.
-- Applied ONLY at `useProgressSync.ts` `applyRemoteProgress`: a malformed
-  `syncedConfig.location` is set to `undefined` so it can't drive goTo, can't win
-  the `CFI.compare` gate, and is filtered out of the persisted config (local
-  location kept; stops re-propagation). A valid `xpointer` still recovers the
-  real position via `getCFIFromXPointer`.
-- Applied at `useKOSync.ts` `generateKOProgress` (push side): if local
-  `progress.location` is malformed, skip the CFI→XPointer conversion and reuse
-  the last known-good `config.xpointer`. Critical because once a bad CFI is
-  pushed as an XPointer the "malformed" signal is lost — other devices pull a
-  plain XPointer pointing at the wrong section end and can't discard it. The
-  kosync RECEIVE path needs no guard: `getCFIFromXPointer` builds point CFIs from
-  point XPointers, which can't take the empty-start form.
-- Deliberately NOT applied to `FoliateViewer.tsx` open path — that uses the
-  user's OWN local `config.location`; discarding it would dump them at book start
-  (`goToFraction(0)`). Left untouched per user preference; a legacy local bad
-  value self-heals on the next page-turn save.
-
-Tests: predicate in `__tests__/utils/cfi.test.ts`; repro + flag in
-`__tests__/utils/epubcfi-inert.test.ts`; discard behavior (no goTo, not
-persisted) in `__tests__/hooks/useProgressSync.test.tsx`.
-Related: [[kosync-cfi-spine-resolution]].

apps/readest-app/.claude/memory/fastlane-apple-appstore-submission.md

@@ -1,18 +0,0 @@
----
-name: fastlane-apple-appstore-submission
-description: "fastlane lanes for iOS/macOS App Store + TestFlight submission, and two gotchas (Tauri notarization trigger, fastlane cwd)"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 6604c57a-dee4-4a6e-8624-540162f41a80
----
-
-Readest's Apple App Store + TestFlight submission via fastlane (root `fastlane/Fastfile`, alongside the existing Android `upload_to_play_store` lanes). Builds are unchanged (`pnpm run release-ios-appstore` / `release-macos-universial-appstore` → `tauri build` + `xcrun altool --upload-app`); fastlane only does the post-upload App Store version + review submission and TestFlight distribution on the already-uploaded build.
-
-Lanes (per-platform, each does App Store review submit AND TestFlight, sharing a `submit_apple_build` helper): `release_ios`, `release_macos`. App Store via `upload_to_app_store(skip_binary_upload: true, ipa:/pkg:, platform: "ios"/"osx", submit_for_review: true, automatic_release: true, force: true, skip_screenshots: true, skip_metadata: false, release_notes:{"en-US"=>...}, promotional_text:{"en-US"=>...})`; TestFlight via `upload_to_testflight(distribute_only: true, app_platform: "ios"/"osx", distribute_external: true, groups:["Beta Testers"])`. App Store submit runs FIRST (it waits for build processing, which the TestFlight distribute then needs). `release_notes_text` parses `apps/readest-app/release-notes.json` (latest version by `Gem::Version`, drops notes matching `/\b(?:Android|Windows|Linux)\b/i`, prefixes each `– `). Auth: `app_store_connect_api_key`. Commands: `pnpm run submit-appstore-ios` / `submit-appstore-macos`.
-
-GOTCHA 1 (Tauri notarization): `tauri build` auto-notarizes the macOS App Store bundle whenever the FULL App Store Connect API key trio (`APPLE_API_KEY` + `APPLE_API_ISSUER` + `APPLE_API_KEY_PATH`) is in the build env. Notarization REJECTS App Store builds ("not signed with a valid Developer ID certificate" / "no secure timestamp") because they use an Apple Distribution cert — App Store apps are NOT notarized. So `APPLE_API_KEY_PATH` must stay OUT of `.env.apple-appstore.local` (the macOS build env). `asc_api_key` instead DERIVES the `.p8` path from the key id: `repo_path("apps/readest-app/private_keys/AuthKey_#{key_id}.p8")` (the keys are named `AuthKey_<KEYID>.p8`, same convention altool uses; honors an explicit `APPLE_API_KEY_PATH` when set, e.g. the iOS build env which DOES need it and iOS doesn't notarize).
-
-GOTCHA 2 (fastlane cwd): fastlane changes cwd to the `./fastlane` folder when EXECUTING a lane (`__dir__` is just "."), so raw `File.read("./apps/...")` breaks with "No such file". `fastlane lanes` only PARSES (doesn't run lane bodies) so it won't catch this — verify path-dependent lanes by actually RUNNING one. Fix = `repo_path(rel) = File.expand_path(rel, File.expand_path("..", __dir__))`, route every path (release-notes.json, .p8, ipa, pkg) through it.
-
-GOTCHA 3 (dotenv shadowing): bare `dotenv` on PATH is the Ruby gem (`-f` syntax); package.json scripts use the npm `dotenv-cli` (`-e` syntax) resolved from `apps/readest-app/node_modules/.bin`. The submit scripts run `dotenv -e .env.apple-appstore.local -- bash -c 'cd ../.. && fastlane release_*'` — the `cd ../..` is required because fastlane does NOT search upward for the `fastlane/` dir (pnpm runs scripts from `apps/readest-app`).

apps/readest-app/.claude/memory/feedback-commit-message-english-only.md

@@ -1,14 +0,0 @@
----
-name: feedback-commit-message-english-only
-description: "Commit messages (and PR titles) must be English-only — no CJK characters, no em/en dashes"
-metadata: 
-  node_type: memory
-  type: feedback
-  originSessionId: c0199d69-f314-45ee-bf7c-867b908641cc
----
-
-Git commit messages must be **English only**: no CJK characters (no 中文/量词/example glyphs like 第一封信) and no em/en dashes (— –). Use plain ASCII punctuation (comma, colon, parentheses, `...`). The same applies to PR titles for consistency.
-
-**Why:** the user (a maintainer of readest/readest) keeps the project's git history English-only and clean.
-
-**How to apply:** when a fix is about Chinese/CJK text, describe the concept in English in the commit subject/body (e.g. "measure-word prose", "the classifiers for 'letter' and 'book'") instead of pasting the glyphs. Keep the concrete CJK examples and screenshots in the PR *body* / code / tests, where they aid understanding — that is fine. First seen on PR #4660 ([[txt-chapter-measure-word-4658]]), where "量词" in the subject had to be amended to "measure-word".

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,11 +0,0 @@
----
-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

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

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

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

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

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

apps/readest-app/.claude/memory/fixed-layout-paginated-scroll-reset-4683.md

@@ -1,40 +0,0 @@
----
-name: fixed-layout-paginated-scroll-reset-4683
-description: "Fit-width tall fixed-layout page opens scrolled-to-end on WebKit page turn (#4683); Blink unaffected; fix = explicit scrollTop=0 on page-turn render"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 780a4235-5498-42c8-8286-7021c6fcf1ed
----
-
-#4683: in paginated fixed-layout (PDF / fixed-layout EPUB) **fit-width** mode, when a
-page is scaled taller than the viewport (`isOverflowY` true, host gets a vertical
-scrollbar), turning to the next page opened the new page **scrolled to the bottom**
-instead of the top. Root cause: `FixedLayout` host (`:host{overflow:auto;align-items:center}`
-in `packages/foliate-js/fixed-layout.js`) scrolls vertically; `#render`'s `transform`
-re-centered `container.scrollLeft` on every render but **never reset `container.scrollTop`**.
-On a page turn the freshly-shown page inherited the previous page's offset (≈ bottom, since
-the reader scrolled down to finish, and same-size pages share maxScrollTop).
-
-**Engine-specific — WebKit only.** WebKit (Linux WebKitGTK, iOS, macOS WKWebView)
-*preserves* a scroll container's offset when `#showSpread` swaps the flow content
-(old frame → `position:absolute;visibility:hidden`, new frame appended). **Blink**
-(Android WebView, Chrome, WebView2) *resets* scrollTop to 0 on that swap, so the bug
-never manifests there. Reporter was on Ubuntu/WebKitGTK `WebView 605.1.15`.
-
-**Fix:** new exported pure helper `computePaginatedScroll({elementWidth,containerWidth,scrollTop,pageTurn})`
-→ `{scrollLeft:(elementWidth-containerWidth)/2, scrollTop: pageTurn?0:scrollTop}`.
-Thread a `pageTurn` flag into `#render(side, pageTurn=false)`; set `true` ONLY at the
-3 navigation entry points (`#showSpread`, `#goLeft`, `#goRight`). Plain re-renders
-(ResizeObserver, zoom/scale-factor attr, pageColors, goToSpread same-index re-render)
-keep `pageTurn=false` so resize/pinch-zoom of a tall page does NOT jar to the top.
-Test: `src/__tests__/document/fixed-layout-paginated-scroll.test.ts` (pure-helper pattern,
-like [[booknote-view-autoscroll-4352]] sibling fixed-layout helper tests — the custom
-element can't be instantiated in jsdom: no ResizeObserver + getBoundingClientRect=0).
-
-**Verification recipe (the bug is NOT Android-reproducible):** CDP on Xiaomi showed
-`view.next()` already yields scrollTop 0 on Blink → can't distinguish fix on Android.
-Proved on REAL WebKit instead: auto-running HTML mirroring host CSS + `#showSpread` swap,
-opened via `open -a Safari file://…`, screenshot. Safari `AppleWebKit/605.1.15` (== reporter)
-showed scrollTop 420/440 (bug) without reset, 0 with reset. readest fixed-layout page turn
-goes through `view.next()`/`view.prev()` (`usePagination.ts`), the same path.

apps/readest-app/.claude/memory/foliate-touch-listener-capture-phase.md

@@ -1,19 +0,0 @@
----
-name: foliate-touch-listener-capture-phase
-description: "To intercept/suppress reader touch gestures from the app, use capture-phase listeners — foliate-js's paginator registers bubble-phase doc listeners first"
-metadata: 
-  node_type: memory
-  type: reference
-  originSessionId: 4b0bfcd2-a4ed-4b3c-99c2-b3c37ef7c530
----
-
-There are **three** independent touch-listener registrants on the foliate iframe `doc`:
-1. `FoliateViewer.tsx` (~line 326) — passive forwarders that only `postMessage`.
-2. `Annotator.tsx` (~line 332) — non-passive, drive text selection.
-3. **foliate-js's own paginator** (`packages/foliate-js/paginator.js:1034`) — non-passive, **bubble-phase**, registered during `view.open()` (so *before* any app-level `load` handler). It can `preventDefault`, set `#touchScrolled`, `scrollBy`.
-
-Consequence: a bubble-phase app listener registered "before the existing FoliateViewer listeners" **cannot** `stopImmediatePropagation` the paginator — the paginator already ran. Registration order only controls listeners within the same phase, and the paginator's are earlier regardless.
-
-**Fix pattern:** register with `{ capture: true, passive: false }`. Capture-phase listeners on `doc` fire before all bubble-phase listeners when the event target is a descendant, so capture-phase `stopImmediatePropagation()` suppresses paginator + Annotator + FoliateViewer handlers alike. Scrolled mode also needs `preventDefault` from the first armed move (the paginator early-returns on `scrolled`, so native container scroll is what moves content).
-
-Verified end-to-end for the [[brightness-swipe-gesture]] feature (test asserts a bubble-phase paginator stand-in never fires after a capture-phase `stopImmediatePropagation`). Both Codex and a Claude subagent independently confirmed against `paginator.js` during the /autoplan review.

apps/readest-app/.claude/memory/footnote-aside-namespace-order-4438.md

@@ -1,20 +0,0 @@
----
-name: footnote-aside-namespace-order-4438
-description: Footnote aside border line regression — @font-face inlined before @namespace invalidated the namespaced footnote-hiding selector
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 788943e6-fede-4c8f-828c-695ca873f178
----
-
-#4438 (v0.11.4 regression): a stray horizontal line appeared below the footnote/annotation marker because the footnote `<aside epub:type="footnote">` (with the book CSS's `border:3px #333 double`) stopped being hidden.
-
-**Root cause:** PR #4383 (`e8675fb7e`, inline custom @font-face) changed `getStyles` assembly in `src/utils/style.ts` from `${pageLayoutStyles}...` to `${customFontFaces}\n${pageLayoutStyles}...`. The `@namespace epub "..."` declaration lived *inside* `getPageLayoutStyles`. Per the CSS spec a `@namespace` rule is honored ONLY if it precedes every style/`@font-face` rule — a misplaced one is silently ignored. The inlined `@font-face` rules pushed `@namespace` down, invalidating it, so the namespaced selector `aside[epub|type~="footnote"] { display:none }` was dropped and the aside border showed. Only hit users **with custom fonts loaded** (otherwise `customFontFaces` is empty and `@namespace` stayed first).
-
-**Fix:** Hoist `@namespace` to the very front of the assembled stylesheet (`const epubNamespace = '@namespace epub "..."'; return \`${epubNamespace}\n${customFontFaces}\n${pageLayoutStyles}...\``) and remove it from `getPageLayoutStyles`. Custom faces still precede the `--serif`/`--sans-serif` lists, preserving #4383's first-paint intent.
-
-**Gotchas verified the hard way:**
-- `epub:type` is a *namespaced* attribute only when the doc is parsed as XHTML/XML (foliate loads EPUB content as XHTML). Playwright `page.setContent` parses as **HTML**, where `epub:type` is a plain attr and `[epub|type~=...]` never matches — repro must use `data:application/xhtml+xml` via `page.goto`.
-- The existing test `style-get-styles.test.ts` literally asserted the buggy order (`@font-face` before `@namespace`) on the false premise that an @font-face must precede the font-family rules that use it. It must not — @font-face rules are collected regardless of source position; only same-family redefinition cares about order.
-
-Related: [[css-style-fixes]], [[table-dark-mode-tint-4419]] (both in the bug-prone `style.ts`).

apps/readest-app/.claude/memory/gdrive-provider-multipr-status.md

@@ -1,82 +0,0 @@
----
-name: gdrive-provider-multipr-status
-description: "Google Drive file-sync provider — phased multi-PR build status, what shipped in PR1 and what each later PR adds"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 50e2c2b8-ca61-4c33-acae-cd5d2c9aa93f
----
-
-Adding **Google Drive as a second `FileSyncProvider`** for the merged file-sync engine (the WebDAV refactor, PR #4784). Approved plan: `/Users/chrox/.claude/plans/floating-chasing-feather.md`. Research + reuse map: [[gdrive-sync-provider-research]]. Author of the reference (`ratatabananana-bit/Readest-google-drive-mod-patcher`, AGPL-3.0) granted explicit reuse permission; adapted files carry attribution headers.
-
-**Shipped across multiple PRs (decided at the autoplan gate; no BYO client, official iOS-type client only).**
-
-**PR1 — DONE (built, all gates green, committed locally, NOT pushed).** Branch `feat/gdrive-sync-core` (worktree `/Users/chrox/dev/readest-feat-gdrive-sync-core`), commit `1a0065818`. 25 files / ~2.6k lines, ~81 new unit tests, full suite 6377 passing + lint + format clean. Contents under `src/services/sync/providers/gdrive/`:
-- `GoogleDriveProvider.ts` — Drive v3 over `FileSyncProvider`; id-addressed resolution + per-instance id cache; create-then-name upload; real `ensureDir`; `files.list` pagination; Retry-After 429/5xx backoff; per-path folder-creation locks + deterministic dup-collapse (smallest id); stale-id eviction; `mapDriveError` (403 split rate-limit→NETWORK vs permission→AUTH_FAILED). Factory `createGoogleDriveProvider(auth, fetchFn, {sleep?})`; streaming omitted.
-- `auth/` — `pkce`, `parseRedirect` (target + CSRF, takes `expectedRedirectUri`), `reverseDnsRedirect`, `tokenStore` (no client secret), `oauthFlow` (DI).
-- `PersistedDriveAuth.ts` — single-flight refresh + re-check, carries old refresh_token, one save; `accountLabel` via `about.get`.
-- `driveTokenStore.ts` — `TokenPersistence` + `KeychainTokenPersistence` over keyed secure-KV; `createDriveTokenPersistence()` returns null off-Tauri (NO ephemeral fallback for refresh token).
-- `driveRest.ts` — pure builders + pagination + `aboutUrl`.
-- `buildGoogleDriveProvider.ts` (env client id + keychain), `file/providerRegistry.ts` (`createFileSyncProvider`/`getEnabledFileSyncBackends`).
-- Shared `file/providerSemanticContract.ts` test helper run for BOTH WebDAV + Drive.
-- `utils/bridge.ts` — TS wrappers `set/get/clearSecureItem` (`plugin:native-bridge|*_secure_item`).
-
-**DEVIATION from plan:** the native keyed secure-KV implementation (Rust desktop/mobile + Kotlin + Swift + permissions) was DEFERRED out of PR1 — nothing in PR1 calls it (no UI/sync wiring), and 4 languages of un-runnable native code don't belong in a "CI-testable, no-platform" PR. The TS contract exists + is mock-tested. Native impl lands with **PR3 (desktop OAuth)**, which first exercises it and can live-verify.
-
-**PR2 — DONE (foundation only; committed `9ba097ea2`, UNPUSHED, on same `feat/gdrive-sync-core` branch).** Full suite 6403 passing + lint + format clean.
-- `GoogleDriveSettings` type (mirrors WebDAVSettings minus URL/creds/rootPath, +`accountLabel`) in `types/settings.ts` + `SystemSettings.googleDrive`; `DEFAULT_GOOGLE_DRIVE_SETTINGS` in `constants.ts`.
-- `googleDrive.deviceId`/`lastSyncedAt` added to `BACKUP_SETTINGS_BLACKLIST` (backupService.ts) + backup-settings test.
-- `webdavSyncStore`→`store/fileSyncStore.ts`: per-backend progress keyed by kind + GLOBAL library-sync mutex (`beginSync(kind,label)` returns false if another holds lock). Migrated `WebDAVForm` + `IntegrationsPanel`; WebDAV behavior unchanged. `fileSyncStore.test.ts`.
-- **DEFERRED to PR3 (deliberate):** `useWebDAVSync`→`useFileSync` hook generalization + `WebDAVForm`→`FileSyncForm` extraction + visible Drive Integrations row/connect UI. Rationale: until Drive connects (needs OAuth), the multi-provider hook paths can't run and `FileSyncForm` would be a single-use abstraction (violates YAGNI); also the autoplan gates these on a live WebDAV Sync-now check. Do them WITH PR3.
-
-**PR3 — IN PROGRESS (3 commits, all gates green: full suite 6411 passing + rust fmt/clippy/test + lint/format). UNPUSHED on `feat/gdrive-sync-core`.**
-- `ff1ffe717` native keyed secure-KV: `set/get/clear_secure_item` across Rust desktop (keyring keyed by item key) + mobile forward + models/commands/lib/build/default.toml + Kotlin (EncryptedSharedPreferences `readest_secure_items_v1`) + Swift (Keychain, service `com.bilingify.readest.secure-items`). Rust compiles+clippy+fmt clean; permission files regenerated (passphrase preserved).
-- `602f41406` desktop OAuth machinery: `auth/oauthDesktop.ts` (`runDesktopDeepLinkOAuth`, DI, 3 tests) + `src-tauri/src/spawn_fresh_browser.rs` (registry default-browser cold-spawn on Windows / no-op macOS+Linux; winreg Windows-only dep; pure-helper tests; registered `#[cfg(desktop)]`) + `connectGoogleDrive.ts` (`connectGoogleDrive`/`disconnectGoogleDrive`, fail-loud token save, 4 tests). `DRIVE_FILE_SCOPE='https://www.googleapis.com/auth/drive.file'`.
-- `5efbe6b2f` ingress filter: `isGoogleOAuthRedirectUrl` (scheme-prefix match) + filter in `useAppUrlIngress` dispatch so the reverse-DNS redirect never reaches book-import consumers (OAuth runner catches via own listeners). Tested.
-
-**Official client id PROVISIONED:** `209390247301-ctpmep68ppfa56r1b8tr35e4qi4p60kq.apps.googleusercontent.com` (iOS type, no secret, `drive.file`). Baked as default in `getGoogleClientId` (env `NEXT_PUBLIC_GOOGLE_CLIENT_ID` overrides); reverse-DNS scheme `com.googleusercontent.apps.209390247301-ctpmep68ppfa56r1b8tr35e4qi4p60kq` registered in `tauri.conf.json` desktop+mobile deep-link. Commit `7a2ac3671`.
-
-**Drive UI DONE (commit `c657c34f0`):** `FileSyncForm` (shared sync controls extracted from WebDAVForm, parameterized by kind, builds provider via registry; WebDAVForm refactored to use it, behavior unchanged) + `GoogleDriveForm` (OAuth Connect/account/Disconnect + FileSyncForm) + `googleDriveConnect.ts` (assembles env client id + keychain + desktop runner) + IntegrationsPanel "Google Drive" row gated on `appService.isDesktopApp`. Full suite 6412 green.
-
-**Cloud Sync redesign DONE (commit `1a31a8cbd`):** new "Third-party Cloud Sync" Integrations section with a unified "Cloud Sync" sub-page (`CloudSyncForm`) — WebDAV + Google Drive MUTUALLY EXCLUSIVE via `withActiveCloudProvider` (enabling one disables the other). Radio picker (AIPanel pattern) + shared `FileSyncForm`. WebDAVForm/GoogleDriveForm refactored to embeddable panels; Drive has a "configured-but-inactive" state (`accountLabel` present, `enabled=false`) with frictionless "Use Google Drive" re-activate (no re-OAuth); explicit Disconnect clears the keychain token. Temp concurrency probe removed (upload was already concurrency-4, confirmed).
-
-**Reader auto-sync DONE (commit `f5e07e50b`):** `useWebDAVSync`→`useFileSync` — the reader auto-syncs the single ACTIVE provider per-book while reading (pull-on-open, debounced push, cover/file). Async engine build (Drive keychain probe) held in state, pull-on-open waits for it; engine keyed on connection-relevant settings (not lastSyncedAt) to avoid re-probing keychain; deviceId/lastSyncedAt write the active provider slice; events renamed `*-file-sync`. WebDAV reader behavior unchanged.
-
-**Drive feature is functionally complete on desktop:** connect, manual Sync now, auto-sync while reading, exclusive provider switching. Live-verified: connected + synced a 675-book library.
-
-**DESKTOP PR OPENED: readest/readest#4821** (`feat/gdrive-sync-core`, rebased onto origin/main, all gates green incl. rust). Covers provider + OAuth + native KV + redesign (exclusive Third-party Cloud Sync section, inline radio switch) + reader auto-sync + **premium gating** (any paid plan via `isCloudSyncInPlan`; free sees upgrade CTA; reader auto-sync off for free). Rebase needed `git -c protocol.file.allow=always submodule update --init packages/foliate-js` (foliate-js drift, index wanted `6f1a190`).
-
-**PR #4821 review fix (pushed `5769682c5`):** CodeQL flagged `escapeDriveLiteral` (driveRest.ts) for not escaping backslashes — fixed (escape `\`→`\\` FIRST, then `'`→`\'`). Was the only review comment.
-
-**Both branches REBASED onto origin/main `324bb8a36` (was `7e78f80e1`). UNPUSHED, both gates green (lint+format+full suite: mobile 6483, resumable 6486). foliate-js submodule drift on rebase: origin/main now wants `0fa407c4c` (not in local submodule clone whose origin is the main checkout's modules dir); fix `git -C packages/foliate-js fetch https://github.com/readest/foliate-js.git 0fa407c4c... && git -C packages/foliate-js checkout 0fa407c4c...` (the `submodule update --init` shortcut FAILS here — local origin lacks the commit; must fetch from GitHub URL). Current commits: mobile `6728c94f0`(Android)+`8b3dd1cd5`(iOS); resumable `f7a1e5117`.**
-
-**Branch `feat/gdrive-mobile-oauth` (Android+iOS OAuth) — no longer stacked, off main. PR not opened yet.**
-
-**Android OAuth (PR4) DONE (commit `eb8e22081`, was `5583c9b38` pre-rebase).** `auth/oauthAndroid.ts` (`runAndroidOAuth` via existing `authWithCustomTab`, DI, 2 tests) + platform dispatch in `googleDriveConnect` (`osType()==='android'`→Custom Tab, else desktop) + Drive row shown on Android. NATIVE (device-verify pending, no Android toolchain in CI): `NativeBridgePlugin.kt` `handleIntent` resolves `com.googleusercontent.apps.<id>:/oauthredirect` via the same `pendingInvoke` as the Supabase callback; matching BROWSABLE intent-filter added to `gen/android/.../AndroidManifest.xml`.
-
-**iOS OAuth (PR5) DONE (commit `1230fb291`).** `auth/oauthIos.ts` (`runIosOAuth` via `authWithSafari({authUrl, callbackScheme})`; callbackScheme = `deriveReverseDnsRedirectScheme(clientId)` = bare `com.googleusercontent.apps.<id>` — ASWebAuthenticationSession matches on SCHEME not path; DI, 2 tests) + `AuthRequest.callbackScheme?` (nativeAuth.ts; Supabase keeps native `readest` default) + `resolveOAuthRunner` `os==='ios'`→runIos + Drive row on iOS (`isDesktopApp||isAndroidApp||isIOSApp`). `createDriveTokenPersistence` already works on iOS (Keychain via secure-KV). NATIVE (device-verify pending, no iOS toolchain in CI): Swift `auth_with_safari` uses `args.callbackScheme ?? "readest"` (`SafariAuthRequestArgs.callbackScheme: String?`); `Info-ios.plist` CFBundleURLTypes gains the reverse-DNS scheme. macOS Drive uses the desktop deep-link runner (NOT authWithSafari), so no macOS native change. Full suite 6477 green + lint + format + plutil OK.
-
-**Drive streaming upload/download DONE — own branch `feat/gdrive-resumable-upload` off origin/main (commit `0c9cc1a22`, UNPUSHED).** `uploadStream`+`downloadStream` on GoogleDriveProvider so book files stream from/to disk instead of buffering the whole file in the JS heap (buffered marshal of a large book across the WebView↔Rust bridge crashes the renderer on mobile — this unlocks Drive book sync on Android/iOS and flattens heap on desktop too). `driveRest.resumableCreateUrl`/`resumableUpdateUrl`; `uploadStream` opens a Drive resumable session (POST new `{name,parents}` / PATCH existing `{name}`, metadata in initiation so NO reparent follow-up), reads `Location` session URI, PUTs bytes via `tauriUpload`; `downloadStream` GETs `alt=media` to disk via `tauriDownload` + bearer. Attached **Tauri-only** (`isTauriAppPlatform()`); web keeps buffered fallback. Both swallow→`false` per provider contract (engine retries once). REUSES `@tauri-apps/plugin-upload` already shipped for WebDAV — NO new native code. Single-shot streaming PUT (not chunked mid-stream resume) — sufficient for the heap/OOM fix; chunked-resume-on-failure is a further enhancement. Full suite 6484 green + lint + format. **NOTE: changes desktop Drive book sync from buffered → streaming (previously live-verified buffered); device-verify the streaming path on desktop + mobile.**
-
-**ALL PRs MERGED to main/dev (dev @ `c6f2a83d9`).** Worktree `feat/gdrive-*` branches no longer needed; work continues in the MAIN repo `/Users/chrox/dev/readest` on `dev` (tracks `origin/main`; there is NO `origin/dev`).
-- **#4821** desktop Drive cloud sync + premium Third-party Cloud Sync section.
-- **#4824** Drive resumable streaming upload/download.
-- **#4823** mobile OAuth (Android Custom Tab + iOS ASWebAuthenticationSession).
-- **#4827** Android sync fix: retry THROWN transport errors in `withBackoff` (was 429/5xx only); `mapDriveError` classifies transport throws (incl. Tauri plugin's plain `error sending request` Error) as NETWORK. Root cause: Android pooled keep-alive connection to googleapis.com goes stale mid-sync → every files.list after the first batch threw; sync recovered on its own after ~3-4 min (reqwest evicting dead conns). The retry forces a fresh connection so recovery is fast + kills the error spam.
-
-**CODE COMPLETE + MERGED.** REMAINING (human/ops-only): (1) on-device re-verify with #4827 in the build — Android sync should no longer stall ~3-4 min / spam `failed to inspect hash dir`; iOS OAuth sign-in; desktop streaming book-sync re-check; (2) Google consent screen → Production (testing caps 100 users). NOTE: Android build auto-generates a deep-link intent-filter for the gdrive reverse-DNS scheme in `gen/android/.../AndroidManifest.xml` (duplicates the manual `gdrive-oauth` filter) — benign build drift, don't commit.
-
-**Google Drive on WEB via FULL-PAGE REDIRECT OAuth — DONE on branch `feat/gdrive-web-oauth` (was `feat/gdrive-web-gis`; local/unpushed; suite 6516 green).**
-- **GIS popup ABANDONED:** `src/middleware.ts:55` sets `Cross-Origin-Opener-Policy: same-origin` on every web doc (Turso WASM/SharedArrayBuffer needs `crossOriginIsolated`). COOP same-origin SEVERS a cross-origin popup's opener handle → GIS's `popup.closed` poll reads true instantly → `popup_closed` fires while the popup is still open (diagnosed live). Can't relax COOP (breaks Turso); can't scope it (connect happens over Turso routes). So no popup OAuth on web.
-- **Web flow:** full-page redirect (no `window.opener`, works under COOP). `auth/webRedirectFlow.ts` (implicit `response_type=token` — secretless Web client can't code-exchange; CSRF state+returnPath in sessionStorage; parse token from callback fragment) + `auth/webTokenStore.ts` (sessionStorage access token, no refresh token) + `WebDriveAuth.ts` (reads stored token, expired→AUTH_FAILED, `accountLabel` via about.get) + `app/gdrive-callback/page.tsx` (validates state, stores token, `withActiveCloudProvider(settings,'gdrive')`+label via `appService.load/saveSettings`, routes back). `buildGoogleDriveProvider` web branch: `new WebDriveAuth(globalThis.fetch)` (Drive REST CORS-ok; streaming Tauri-only→web buffered). `googleDriveConnect` web: Connect=`beginWebDriveRedirect` (navigates away, never resolves), Disconnect=`clearWebDriveToken`.
-- **Official Web client id BAKED** `209390247301-585tc3dohg4c02588uvah5d32hg6dneq` (`getGoogleWebClientId`, env `NEXT_PUBLIC_GOOGLE_WEB_CLIENT_ID` overrides). **NO auto-refresh** (secretless browser client → no refresh token; Google blocks hidden-iframe silent renewal) → user reconnects per session; true auto-refresh needs a server-side token broker (Worker holds secret+refresh token) — deferred ("A for now").
-- **OPS REMAINING:** add `https://web.readest.com/gdrive-callback` + `http://localhost:3000/gdrive-callback` to the Web client's **Authorized redirect URIs** (JS origins already set). Then live-verify `pnpm dev-web`.
-
-**PR3 REMAINING:**
-- **LIVE VERIFICATION (needs the user — real Google sign-in):** `pnpm tauri dev` → add own Google account as a Test user in the consent screen (Testing mode caps + gates) → Settings → Integrations → Google Drive → Connect → browser → grant → "Connected as <email>" → add book / Sync now → confirm `Readest/books/<hash>/{config.json,cover.png}` in Drive. Windows cold-browser fallback.
-- **Reader-hook auto-sync (deferred):** generalize `useWebDAVSync`→`useFileSync` (per-provider state maps, async Drive provider build in the hook) so Drive auto-syncs per-book while reading like WebDAV. Manual Sync-now already works without it; do after live-verifying the base.
-- Consent screen → Production before GA (testing caps 100 users).
-- PR4 Android OAuth (Custom Tab + manifest scheme), PR5 iOS OAuth (authWithSafari scheme param + Info-ios.plist). Later: Drive resumable upload for `syncBooks` on mobile.
-- Ops/launch blocker: create Google Cloud project (iOS client, `drive.file`) + consent screen to production (testing caps 100 users).
-- PR4 Android OAuth, PR5 iOS OAuth. Later: Drive resumable upload to unlock `syncBooks` on mobile.
-- Ops/launch blocker: create the Google Cloud project (iOS client, `drive.file`) + set consent screen to production (testing caps 100 users).

apps/readest-app/.claude/memory/gdrive-sync-provider-research.md

@@ -1,42 +0,0 @@
----
-name: gdrive-sync-provider-research
-description: Research on the ratatabananana-bit Google Drive mod for building a Drive FileSyncProvider; OAuth approach + reuse map
-metadata: 
-  node_type: memory
-  type: reference
-  originSessionId: 50e2c2b8-ca61-4c33-acae-cd5d2c9aa93f
----
-
-NEXT TASK (research done, not yet built): add **Google Drive as a `FileSyncProvider`** for the merged file-sync engine ([[webdav-filesync-refactor-plan]] / PR #4784). Researched reference: `github.com/ratatabananana-bit/Readest-google-drive-mod-patcher` (AGPL-3.0, same as Readest → can adapt WITH attribution). Reference patch saved at `~/.../scratchpad/gdrive-ref/` (extracted modules under `extracted/`).
-
-**The repo is a PATCHER**, not a fork: the whole impl is one squashed diff `tooling/mod/mod.patch` (13k lines) against Readest v0.11.12. Design/plan docs live in a SIBLING repo `readest-gdrive-sync-mod` (referenced in MOD.md, likely private — not in the patcher).
-
-**Their architecture = REPLACE Readest's native cloud sync with Drive** (library/progress/notes/stats). Two layers:
-- `src/services/cloudprovider/` — REUSABLE: a backend-agnostic provider seam + OAuth. `CloudProvider.ts` (their interface), `GoogleDriveProvider.ts` (Drive v3 REST impl), `FakeCloudProvider.ts`, `buildDriveProvider.ts` (assembly), `googleAuth/*` (the OAuth layer).
-- `src/services/drivesync/` — SKIP for us: their integration with the native-sync data model (driveMerge, statsMerge, DriveSyncClient, DriveBlobStore, jsonl, layout). We REPLACE this with our `FileSyncEngine`.
-
-**KEY: their `CloudProvider` is ~1:1 with our `FileSyncProvider`.** Map: getText↔readText, getBinary↔readBinary, putText/putBinary↔writeText/writeBinary, list↔list, stat↔head, deleteFile↔deleteDir. Their `CloudEntry` even carries `md5` (Drive checksum) — stronger than our size-only HEAD short-circuit. Extra on theirs: `isAuthenticated()`/`accountLabel()` (auth state) + `putBinary` `onProgress`. Missing on theirs: `ensureDir` (Drive auto-creates folders on write).
-
-**Recommended fit for US = Drive as a parallel `FileSyncProvider`** (like WebDAV), NOT replacing native sync. Reuses the whole engine (incremental/concurrency/merge). Build = (1) `createGoogleDriveProvider(settings): FileSyncProvider` adapting their `GoogleDriveProvider` (rename methods, map CloudEntry→FileEntry, head from stat, deleteDir from delete-folder-by-id, ensureDir = no-op since write auto-creates, rootPath='/'), (2) reuse `googleAuth/*` OAuth nearly as-is, (3) token persistence (the ONE big gap — see below), (4) settings UI + provider registry.
-
-**Drive specifics (vs WebDAV path-addressing):**
-- **Drive is ID-addressed, not path-addressed.** Resolve a logical path (`Readest/books/<hash>/config.json`) segment-by-segment via `files.list` (name+parent queries), cache folder/file ids in a `Map<path,id>`. `driveRest.ts` = pure query/URL builders; `GoogleDriveProvider` owns resolver+cache.
-- **`drive.file` scope** = app sees only files it created → Drive root is a safe private namespace (no appdata hidden folder; a visible "Readest" folder). Non-sensitive scope = no Google verification needed (unverified-app warning shows once).
-- **Upload = create-then-name:** `uploadType=media` carries no metadata, so POST bytes to root → PATCH name + reparent (addParents=folder, removeParents=root). Overwrite = media PATCH on the existing id (preserves id/links).
-- Endpoints: metadata `drive/v3/files`, media `upload/drive/v3/files?uploadType=media`. Folder MIME `application/vnd.google-apps.folder`.
-
-**OAuth (the hard part — every gotcha you flagged is CONFIRMED + implemented):**
-- **One iOS-type Google client** (Bundle ID only, NO secret, NO SHA-1, App Check OFF) for BOTH Windows + Android. Redirect = reverse-DNS `com.googleusercontent.apps.<id>:/oauthredirect` (SINGLE slash) + PKCE. Client id derives the scheme (`reverseDnsRedirect.ts`). Client id is committed (not a secret). App Check must stay OFF (Android can't produce iOS attestation → would break everyone).
-- Loopback dead for iOS clients (Google blocked 2022); embedded WebView blocked (`disallowed_useragent`). Reverse-DNS is the only no-SHA native redirect Google accepts.
-- `oauthFlow.ts` — provider-agnostic orchestration, platform mechanics injected (DI, headless-testable). Arms `awaitRedirect` BEFORE `openUrl` (race fix). PKCE + `state` CSRF via `parseRedirect.ts`.
-- **Android** (`oauthAndroid.ts`): Chrome Custom Tab via Readest's EXISTING native bridge `authWithCustomTab` (same as Supabase login) — NOT external browser (keeps Tauri Activity foregrounded so in-flight auth survives memory pressure; redirect resolves via a native Kotlin field that survives WebView reload). Register the client scheme as a BROWSABLE intent-filter (patcher injects into `tauri.conf deep-link.mobile`). MUST filter the OAuth redirect out of Readest's deep-link ingress (`useAppUrlIngress` via `matchesReverseDnsRedirect`) or it triggers a /library reload that kills the flow. `tauri android init` wipes the manifest → restore MANAGE_EXTERNAL_STORAGE etc.
-- **Windows/desktop** (`oauthDesktopDeepLink.ts` + `spawn_fresh_browser.rs`): system browser + self-registered scheme (`deep_link().register_all()`, no installer/admin). Capture via `single-instance` (url=args[1]) + `onOpenUrl`. THE WINDOWS SUBTLETY: a browser process snapshots protocol associations at launch, so a browser already running before scheme-registration silently drops the redirect. Fix: open default browser first; if no redirect in `DEFAULT_FALLBACK_DELAY_MS=25_000`, re-open in a freshly-spawned COLD browser (`spawn_fresh_browser` Rust cmd: resolve default browser from registry UserChoice → if Chromium-family spawn with `--user-data-dir=<isolated>` → else fall back to Edge). Hard deadline `CONNECT_DEADLINE_MS=15min` rejects an abandoned sign-in. Whichever browser returns first wins.
-- `tokenStore.ts` = PKCE token exchange + `refreshAccessToken` (Google omits refresh_token on refresh → keep the old one). `pkce.ts` = PKCE pair + `buildAuthUrl`.
-
-**GAPS / NOT in the reference (we'd build):**
-1. **Token persistence is a stubbed interface** (`TokenPersistence` load/save/clear) — they explicitly left the secret store (Tauri secure storage / Android Keystore) as a later task. WE implement it.
-2. **No resumable/streaming upload** — simple `uploadType=media` buffers the whole file in JS heap (same OOM risk our WebDAV `uploadStream` avoids). For large book files we'd add Drive resumable upload (`uploadType=resumable`); configs/covers are fine buffered. Our engine's streaming is optional (falls back to buffered).
-3. **accountLabel is a placeholder** ('Google Drive'); real email needs a userinfo call.
-4. **iOS/macOS** not covered (Windows + Android only).
-
-**License call:** AGPL→AGPL is compatible. **The author (ratatabananana-bit) granted EXPLICIT permission** (2026-06): "feel free to do whatever you want with the code (it's the AGPL fork - Drive sync + the recently-read shelf)." So we can copy-adapt freely; keep attribution/credit. The OAuth platform glue is the high-value, hard-to-reproduce part → adapt with credit. Note the author also mentions a "recently-read shelf" feature in the same fork (separate, potential bonus).

apps/readest-app/.claude/memory/global-annotation-pageturn-perf-4575.md

@@ -1,19 +0,0 @@
----
-name: global-annotation-pageturn-perf-4575
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 4640857e-9c37-4ec6-890a-8aa20ec3a3f3
----
-
-**#4575** — "after highlighting several main-character names, page turning is very laggy" (Chinese web-novel TXT). Root cause = the **global highlight** feature (highlight-all-occurrences, `note.global`), NOT plain highlights. The `progress` effect in `Annotator.tsx` (`for (const a of annotationIndex.globals) expandAllRenderedSections(view, a)`) re-fans-out EVERY global note across EVERY rendered section on EVERY page turn. Each pass: TreeWalker over the section DOM (`findTextRanges` in `globalAnnotations.ts`) + `view.getCFI(index, range)` per occurrence (~0.2ms each, the dominant cost) + `overlayer.add` which removes+recreates an SVG and calls `getRects` (forces layout). Overlays already exist after pass 1 → pure waste.
-
-**Profiled live** (dev-web + claude-in-chrome, real `<foliate-view>`): 6 names / 226 occurrences across 2 rendered chapters = **~25–45ms synchronous main-thread per page turn** on desktop (×3–5 on mobile = the lag). Leads 姜窈(73×) 驰厉(66×) per 2 chapters.
-
-**Fix (PR branch `fix/global-annot-pageturn-4575`, commit f1404c6b1):** module-level `WeakMap<Document, Map<noteId, signature>>` `expandedByDoc` in `globalAnnotations.ts`. `expandGlobalAnnotation` skips when `docMemo.get(note.id) === signature`; records after expanding (even 0 matches). `signature = updatedAt:style:color:text`. `removeGlobalAnnotationOverlays` clears the memo entry. Turns 2..N → ~0ms; one-time cost stays at section-render (`onCreateOverlay`). 5 unit tests in `src/__tests__/utils/global-annotations.test.ts`.
-
-**Correctness invariant:** `doc` & `overlayer` are created/destroyed together per section content-record, and `getContents()` returns STABLE doc/overlayer refs across separate calls (verified). So "same doc ⟺ overlays still present" — a re-rendered section gets a fresh `doc` → memo miss → re-expand; never wrongly skips.
-
-**Secondary complaints in the issue (NOT fixed here):** slow TXT import (`txt.ts` parse, "2MB should be instant"), slow TOC/notes open. Separate concerns.
-
-**Repro recipe — import a GBK TXT into dev-web without the native picker:** copy the .txt into `public/`, then in-browser `fetch('/file.txt')` → `arrayBuffer` → `new File([buf], '原名.txt')` → `DataTransfer` → dispatch a synthetic `drop` `DragEvent` (with `Object.defineProperty(ev,'dataTransfer',{value:dt})`) on `.library-page`. Raw bytes preserved → app's encoding detection handles GBK. Books at `/Users/chrox/Documents/books/issues/4575/`. See [[tts-sync-chrome-verification]] for the live-foliate-view profiling pattern.

apps/readest-app/.claude/memory/grimmory-native-sync.md

@@ -1,26 +0,0 @@
----
-name: grimmory-native-sync
-description: Grimmory (Booklore fork) sync API surface + CORS analysis for adding native grimmory sync to Readest
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: ef2f9371-2968-4f81-abe4-a9349547542b
----
-
-Goal: add **native grimmory sync** to Readest (vs the current OPDS+KOReader-compat detour, which causes 3-way KOReader↔Kobo↔grimmory desync — see discussion grimmory-tools/discussions/1417). Grimmory repo at `/Users/chrox/dev/grimmory` (Java/Spring backend, package `org.booklore`).
-
-**Native API (use this, not KOSync):** JWT bearer. `POST /api/v1/auth/login` `{username,password}` → `{accessToken,refreshToken,expires}` (2h/30d); `POST /api/v1/auth/refresh`. Progress: `POST /api/v1/books/progress` `{bookId, fileProgress: BookFileProgress{bookFileId, progressPercent 0-100, positionData (CFI for EPUB), positionHref, ttsPositionCfi}, dateFinished}`; `GET /api/v1/books` to list — **the Book DTO does NOT expose the file hash** (no native hash lookup endpoint; match by metadata, see below). Annotations `/api/v1/annotations/**`, bookmarks `/api/v1/bookmarks/**`, download `/api/v1/books/{id}/download` (Range OK), cover `/api/v1/media/{id}/cover`. KOReader-compat path exists at `/api/koreader/**` (X-Auth-User + X-Auth-Key=md5(pw)) but is the thing we're replacing.
-
-**CORS (`SecurityConfig.java`): per-filter-chain only — NO global CorsFilter/addCorsMappings.** Policy (`:340-368`): origins default `*` (env `ALLOWED_ORIGINS`, uses `setAllowedOriginPatterns` so `*`+credentials valid); methods all; **allowed-headers is a FIXED whitelist** = `Authorization, Cache-Control, Content-Type, Range, If-None-Match, If-Modified-Since` (NOT `*`, and **excludes X-Auth-User/X-Auth-Key**); allowCredentials true. Chains WITH `.cors()`: jwtApi (order10: `/api/**` minus whitelist → books/progress/annotations/bookmarks/reading-sessions/koreader-users), bookDownload(8), epub/audiobook/custom-font/ws(5-9). Chains WITHOUT `.cors()`: opds(1), komga(2), **koreader(3)**, kobo(3), **media/cover(4)**, **catch-all static(11)**. CRITICAL GAP: `/api/v1/auth/login` + `/auth/refresh` are whitelisted OUT of order10's matcher (`:265-289`) so they hit order11 catch-all = **no CORS** → cross-origin browser login fails (invisible to grimmory's own SPA, served same-origin from `classpath:/static/`).
-
-**What it means for Readest:** Tauri desktop/mobile = CORS irrelevant (`@tauri-apps/plugin-http` is native, all endpoints work incl. login). Readest **web build** = JWT data endpoints work cross-origin once token obtained, but **login + koreader need a server-side proxy** (same pattern as existing `/api/kosync`, `/api/opds/proxy`) or same-origin reverse proxy.
-
-**Readest extension points (template = KOSync):** new `src/services/grimmory/GrimmoryClient.ts` (connect/getProgress/updateProgress mirroring `KOSyncClient.ts`), `src/app/reader/hooks/useGrimmorySync.ts` (mirror `useKOSync.ts`), `GrimmorySettings` in `src/types/settings.ts`, `GrimmoryForm.tsx` wired into `IntegrationsPanel.tsx`. Progress mapping: Readest `BookProgress.location` (CFI) ↔ grimmory `BookFileProgress.positionData`; grimmory has `EpubCfiService` for CFI↔XPointer. Related: [[kosync-cfi-spine-resolution]], [[kosync-connect-false-positive-4692]].
-
-**STATUS: NOT shipped.** A full vertical slice was built on 2026-06-23 (GrimmoryClient + useGrimmorySync hook + `/api/grimmory` proxy + GrimmoryForm/IntegrationsPanel + settings/types; metadata-match identity cached in BookConfig; native `/api/v1/books/progress`; tests+lint green) then **REVERTED at the maintainer's request ("not ready yet")**. Working tree fully restored (all grimmory files deleted, the 7 edited shared files reverted; lint + test green). Re-attempt later — the design below + the two findings below are the distilled learnings. Reverted because the native-progress identity story was judged immature; the more robust paths (OPDS acquisition capture, or mirroring the official koplugin) hadn't been built yet.
-
-**FINDING A — how the OFFICIAL koplugin (`github.com/grimmory-tools/grimmory.koplugin`) maps identifiers (it does NOT use `/api/v1/books/progress`).** Local SQLite `book(book_path, partial_md5, grimmory_id)` stores BOTH ids per file. TWO paths: (1) native `grimmory_id` (= book.id) for sessions/downloads/shelves, resolved by **ISBN13/ISBN10/ISBN/ASIN only** (`doc_metadata.lua isBook` — NOT title/author), persisted via `repository.upsertBook(path, book.id)`; sessions → `POST /api/v1/reading-sessions` keyed by grimmory_id. (2) reading **PROGRESS via the KOReader-compat endpoint** `GET/PUT /api/koreader/syncs/progress[/{partialMD5}]`, keyed by KOReader's own `util.partialMD5(book_path)` (NOT grimmory_id), with creds auto-provisioned from native `GET/PUT /api/v1/koreader-users/me` (`getKoreaderCredentials` → `md5(secret)` → X-Auth-User/X-Auth-Key). ⇒ The proven progress path reuses our existing KOSync XPointer/partial-MD5 machinery against `/api/koreader/...`, not the native progress API. Caveat: backend `FileFingerprint.generateHash` samples i=-1 at `1024L<<-2` → Java overflow to offset **0**, vs KOReader LuaJIT `bit.lshift(1024,-2)` → offset **256**; first block MAY differ ⇒ partial-MD5 progress-by-hash could silently mismatch — VERIFY (hash one real downloaded file both ways) before relying.
-
-**FINDING B — OPDS acquisition-time capture (the chosen "best match", not yet built).** Grimmory OPDS fingerprints (`OpdsFeedService.java`): every `<id>` is `urn:booklore:*` (root `urn:booklore:root`, books `urn:booklore:book:{bookId}`); feed `<title>Booklore Catalog`; self/start link `/api/v1/opds`. The book acquisition link encodes BOTH ids: `<link href="/api/v1/opds/{bookId}/download?fileId={fileId}" rel="http://opds-spec.org/acquisition">`. So at OPDS download (`src/app/opds/page.tsx` ~line 505 has `url`; already persists sourceUrl via `upsertOPDSSourceMapping`) parse `bookId` (path) + `fileId` (query); corroborate via `urn:booklore:` entry id OR same-origin with configured grimmory serverUrl; write the ids into config. Authoritative, no metadata guessing — best identity strategy for grimmory-sourced books.
-
-Identity options ranked (native path): (1) OPDS acquisition capture [authoritative]; (2) cached ids; (3) ISBN/ASIN exact; (4) gated title+author (require format + fileSizeKb match, abstain on ambiguity — wrong match corrupts another book's progress). `fileSizeKb` IS exposed on BookFile (size corroborator); hash is NOT.

apps/readest-app/.claude/memory/hardcover-progress-edition-id-4792.md

@@ -1,21 +0,0 @@
----
-name: hardcover-progress-edition-id-4792
-description: Hardcover progress sync parse-failed — edition_id falls back to book_id; invalid edition rejected by Hasura Action
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 6273b46d-b22d-4d48-9295-7420b251a197
----
-
-Issue #4792 (v0.11.12) — FIXED in PR #4794 (branch `fix/hardcover-progress-edition-id`). "Hardcover sync fails completely despite successful API key auth." Auth (`GetUserId`) works; progress push fails with:
-`GraphQL Errors: [{"message":"parsing Hasura.GraphQL.Execute.Action.Types.ActionWebhookErrorResponse failed, key \"message\" not found","extensions":{"code":"parse-failed"}}]`
-
-**Root cause (verified live in Chrome, account chrox, book "Crime and Punishment"):** `HardcoverClient.pushProgress` → `MUTATION_UPDATE_READ` (`update_user_book_read`) sent `edition_id: 713309`, which is the **book_id**, not a real edition id. `update_user_book_read`/`insert_user_book_read` are Hardcover **Hasura Actions**; an invalid edition makes the Action handler throw and return a non-conforming error body, which Hasura surfaces as the generic `parse-failed` (`ActionWebhookErrorResponse` missing `message`). HTTP status is 200 — the error is GraphQL-level only.
-
-**Why edition_id == book_id:** title-search path in `fetchBookContext` (`HardcoverClient.ts`). `QUERY_SEARCH_BOOK` (`per_page:1`, returns raw `results`) does **not** select `featured_edition_id` — confirmed the hit `document` has no such key. So `searchBookByTitle` does `editionId = featured_edition_id ?? bookId` → always `bookId`. Then `QUERY_GET_BOOK_USER_DATA` only resolves a real edition via `selectedEdition` (the user_book's / read's `edition`); here both were `null` (user added the book with no specific edition), so `editionId` stays `bookId`. Broad impact: any no-ISBN (title-matched) book whose Hardcover library entry has no edition selected sends `edition_id = book_id`.
-
-**Fix shipped (PR #4794):** `BookContext.editionId` is now `number | null`; `searchBookByTitle` drops the `?? bookId` fallback (null when no `featured_edition_id`); `$edition_id` made nullable (`Int`) in `MUTATION_INSERT_READ`/`MUTATION_UPDATE_READ`/`MUTATION_INSERT_JOURNAL`; `insert_user_book` omits `edition_id` when null. Verified live: book id → `parse-failed`; real edition id → `error:null`; `edition_id:null` → `error:null` and is a no-op (does NOT clear an existing edition).
-
-**NOT a recent Readest regression:** the buggy `editionId = featured_edition_id ?? bookId` fallback + `edition_id: context.editionId` in the read mutations exist unchanged since the original feature #3724 (2026-04-03). It surfaces now because auto-sync (#4614, 2026-06-16, shipped v0.11.10/v0.11.12) made progress-push run automatically on every page turn (debounced) and via the BookMenu "Hardcover Sync → Push Progress". Possibly compounded by Hardcover tightening server-side edition validation. Secondary: title search also mis-matches (e.g. matched a Harold Bloom study guide, not Dostoevsky's novel) — separate match-quality concern.
-
-Files: `src/services/hardcover/HardcoverClient.ts` (`fetchBookContext` ~306-426, `searchBookByTitle` ~286-289, `pushProgress` ~499-536), `src/services/hardcover/hardcover-graphql.ts` (`QUERY_SEARCH_BOOK`, `MUTATION_UPDATE_READ`/`MUTATION_INSERT_READ` ~131-155). Proxy: `src/app/api/hardcover/graphql/route.ts` forwards client `authorization` header.

apps/readest-app/.claude/memory/i18n-extract-prunes-keys.md

@@ -1,36 +0,0 @@
----
-name: i18n-extract-prunes-keys
-description: "pnpm i18n:extract (removeUnusedKeys) deletes valid keys not statically in the branch; don't commit that churn"
-metadata: 
-  node_type: memory
-  type: feedback
-  originSessionId: afe50e44-d394-4301-bd81-1368df66f90b
----
-
-`pnpm run i18n:extract` (i18next-scanner, `i18next-scanner.config.cjs` has
-`removeUnusedKeys: true`) can DELETE ~30+ valid-looking keys from every non-`en`
-locale on a feature branch — keys whose source usage isn't statically present in
-the current branch (e.g. `"Sync History"`, `"downloaded {{n}} book(s)"`,
-`"Match Whole Words"`). The extract diff then shows huge churn (~1000 +/- lines)
-unrelated to your change.
-
-**Why:** the committed locales can be ahead of the branch's source (strings from
-features not yet on this base, or built dynamically/in non-scanned modules), and
-`removeUnusedKeys` strips anything the scanner can't find. `en/translation.json`
-is a tiny key-as-content file (~70 lines, only plural/proper-noun overrides), so
-new keys never land there anyway — it stays out of the diff.
-
-**How to apply:** for a feature that adds a few strings, do NOT commit the
-scanner's deletions into an unrelated PR.
-1. Run `pnpm run i18n:extract` (optional — only confirms which keys are new).
-2. `git checkout -- apps/readest-app/public/locales` to drop ALL the churn.
-3. Add ONLY your new keys manually to each locale in `i18n-langs.json` with real
-   translations. The files are exactly `JSON.stringify(obj, null, 2) + "\n"`, so
-   a Node script that `JSON.parse`s, appends new keys (insertion order preserved),
-   and rewrites that way yields a zero-extra-diff result. Skip `en` (key-as-content).
-
-Match each locale's existing terminology (grep the file for a related key, e.g.
-`"Export Annotations"` / `"Annotations"`, before translating). Verify with
-`grep -rn '"<Your Key>"' apps/readest-app/public/locales | wc -l` == number of locales.
-
-Related: [[feedback_en_plurals_manual]].

apps/readest-app/.claude/memory/iframe-cross-realm-instanceof.md

@@ -1,25 +0,0 @@
----
-name: iframe-cross-realm-instanceof
-description: "App-bundle code handling foliate iframe DOM must not use `instanceof Element/HTMLElement` — cross-realm, always false"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 2e8d274e-a4da-4d63-8afb-d7a600d560b2
----
-
-Reader content lives in foliate iframes, each with its **own JS realm**. App-bundle
-code (e.g. `src/utils/style.ts`, `iframeEventHandlers.ts`) runs in the **top window
-realm**, so its `Element`/`HTMLElement` constructors differ from the iframe's.
-
-`someIframeEl instanceof Element` (top-realm `Element`) is **always `false`** — verified:
-`Element === iframeWin.Element` is false. So any guard like `if (!(target instanceof Element)) return`
-silently drops every real iframe element. Functions still pass jsdom unit tests (single realm)
-yet are dead in the running app.
-
-**Use duck-typing instead**: `if (!target || !('closest' in target)) return;` then
-`(target as Element).closest(...)`. For node-type checks use `node.nodeType === Node.ELEMENT_NODE`
-(numeric constant, realm-safe) or check `classList`/`closest` presence.
-
-Seen in PR #4391 (wide-table horizontal scroll): the touch `findWrapper` and `applyTableStyle`'s
-re-entrancy guard both used `instanceof`, so the touch routing never fired and the dedupe guard
-never tripped. Related: [[foliate-touch-listener-capture-phase]].

apps/readest-app/.claude/memory/iframe-double-click-word-select.md

@@ -1,51 +0,0 @@
----
-name: iframe-double-click-word-select
-description: Double-click / touch double-tap on a word selects it and fires the instant action or annotation toolbar
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: bac4ae5d-047f-4b4f-8a04-b239beb4d7d7
----
-
-Double-tap (touch) / double-click (mouse) on a word now selects that word — like
-a long-press — then runs the configured instant quick action, or raises the
-annotation toolbar if none is set. Verified live on Xiaomi 12 (Android).
-
-**The gap:** `iframe-double-click` was posted by `handleClick`
-(`src/app/reader/utils/iframeEventHandlers.ts`, gated on `!doubleClickDisabled`)
-but had **no consumer** — a touch double-tap did nothing (Android has no native
-double-tap word-select; desktop double-click already selects natively via the
-`handlePointerUp` path).
-
-**Impl (3 files):**
-- `src/utils/sel.ts`: `getWordRangeAt(node, offset)` expands a caret to the
-  word-like segment via `Intl.Segmenter` (CJK + Latin), `[start,end]` inclusive
-  so a boundary caret still selects the adjacent word; `getWordRangeFromPoint(doc,x,y)`
-  resolves the caret (`caretPositionFromPoint`/`caretRangeFromPoint`) then delegates.
-- `useTextSelector.ts`: `handleDoubleClick(doc, index, x, y)` selects the word and
-  routes through the existing `makeSelection` (guarded so the programmatic
-  `selectionchange` echo is ignored). **Guard `if (isValidSelection(sel)) return`**
-  — on desktop the browser already selected the word natively (flows through
-  `handlePointerUp`), so synthesize ONLY when nothing is selected (touch double-tap).
-  No `isUpToPopup` latch: a double-tap is two taps both consumed by double-click
-  detection, so no trailing single-click follows that would dismiss the popup.
-- `Annotator.tsx`: window `message` listener for `iframe-double-click` resolves the
-  visible section doc/index like `handleNativeTouch` (`renderer.getContents()` +
-  `primaryIndex`), then sets **`pointerDownTimeRef.current = 0`** before calling
-  `handleDoubleClick` so the deliberate double-tap bypasses `handleQuickAction`'s
-  `quickActionMinHoldMs` (300ms) long-press gate (mouse already uses 0). Coords:
-  `clientX/clientY` from the iframe click are already section-doc-relative, exactly
-  what caretFromPoint wants — no window↔frame mapping (unlike `rangeFromAnchorToPoint`).
-
-The branch decision (instant action vs toolbar) reuses the existing Annotator
-`selection` effect: `enableAnnotationQuickActions && annotationQuickAction &&
-isTextSelected.current ? handleQuickAction() : handleShowAnnotPopup()`. Default
-config has `annotationQuickAction: null` → toolbar.
-
-**Tests:** unit `sel.test.ts` (getWordRangeAt/FromPoint), `useTextSelector-doubleClick.test.ts`
-(selection routing + desktop guard); e2e `double-click.android.test.ts` + `doubleTap`
-helper in `helpers/adb.ts` (two `input tap` in one shell, < 250ms apart). Live CDP
-verify: toolbar branch (`.popup-container.selection-popup`) and instant-action
-branch (set quick action to Dictionary via header dropdown → `.popup-container.select-text`,
-toolbar absent). See [[dblclick-drag-pageturn-4524]], [[instant-highlight-tap-paginate]],
-[[tap-to-open-image-table-4600]].

apps/readest-app/.claude/memory/image-zoom-trackpad-flicker-4742.md

@@ -1,16 +0,0 @@
----
-name: image-zoom-trackpad-flicker-4742
-description: "Trackpad pinch-zoom flickered the image viewer; macOS pinch = ctrl+wheel stream, disable CSS transition during continuous gestures"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: affbfa14-0152-4d69-8fce-f7e0b9ee97a3
----
-
-ImageViewer (`src/app/reader/components/ImageViewer.tsx`) flickered when zooming an open image with a MacBook trackpad pinch (#4742, PR #4748).
-
-**Root cause:** on macOS a trackpad pinch-to-zoom is delivered to the WebView as a rapid stream of `wheel` events with `ctrlKey: true` (NOT touch events), so it flows through `handleWheel`. The zoomed `<img>` kept its `transition: transform 0.05s ease-out` whenever `isDragging` was false. Pinch wheel events fire faster than 50ms apart, so each event restarted the in-flight transition from its interpolated mid-point — the transform constantly lagged and caught up = visible flicker. Same root cause as the #4451 pan flicker, which only fixed the pan path and (via `isDragging` set in `onTouchStart`) the touch-pinch path; the wheel-zoom path was the only continuous gesture left with the transition on. That's why touch pinch on iPhone was smooth but trackpad pinch flickered.
-
-**Fix:** added an `isWheelZooming` state set on each `handleWheel` event and cleared on a 200ms debounce (wheel has no explicit gesture-end). Transition is `isDragging || isWheelZooming ? 'none' : 'transform 0.05s ease-out'`. Discrete zoom (buttons, double-click, keyboard) keeps the smoothing.
-
-**General pattern:** never run a CSS `transition` on a transform that's being updated by a high-frequency continuous input stream (drag, touch pinch, trackpad/`ctrl+wheel` pinch) — the interrupted-transition restart flickers. Gate the transition off for the duration of the gesture. Maintainer couldn't repro on macOS 15.6.1 (WebKit) while reporter hit it on macOS 26.5.1 / WebKit 605.1.15; the fix is version-independent. Related: [[instant-highlight-tap-paginate]].

apps/readest-app/.claude/memory/in-place-delete-wiped-originals.md

@@ -1,18 +0,0 @@
----
-name: in-place-delete-wiped-originals
-description: "Deleting a \"Read books in place\" book from Readest used to permanently delete the user's original source file; fixed (PR #4696) to never touch external sources"
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: 432bbb95-47b4-4d9c-825b-528168e2cfb7
----
-
-User report (v0.11.12 Windows): imported a folder via "Import From Directory" with **Read books in place**, later deleted the books in-app, and Readest **permanently deleted the original local files** (not even sent to Recycle Bin). Files were unrecoverable; cloud sync hadn't uploaded them yet ("Book File Not Uploaded").
-
-**Root cause:** `deleteBook` in `src/services/cloudService.ts`. For `local`/`both`/`purge`, it called `resolveBookContentSource` (`src/services/bookContent.ts`) and, when `source.kind === 'external'` (i.e. `book.filePath` set, base `'None'` — the user's own file from an in-place or transient import), unconditionally `fs.removeFile(source.path, source.base)`. `book.filePath` is set in `bookService.ts importBook` whenever `transient || inPlace`.
-
-**The trap:** this was NOT an accidental bug — it was **deliberately coded AND tested**. `cloud-service.test.ts` had a whole `in-place (book.filePath set)` describe block asserting the source file IS removed, with a comment rationalizing it as "symmetric with deleting Books/<hash>/<title>.epub for a normal book." Don't assume tested == intended; the maintainer reversed the decision.
-
-**Fix (PR #4696):** never `removeFile` an `external` source. Only `managed` sources (our Books/<hash>/ copy) and app-generated sidecars (cover.png, and the whole Books/<hash>/ dir on `purge`) are Readest's to delete. Removed the `external` branch entirely; flipped the in-place tests to assert the source is preserved (cover sidecar still removed on `both`, sidecar dir still wiped on `purge`). Also fixed the misleading JSDoc in `ImportFromFolderDialog.tsx` (`readInPlace`) that documented the destructive behavior as intended.
-
-Out of scope but noted in the support thread: deletion flow lacks a warning/disclaimer, and delete doesn't use the OS Recycle Bin. See [[bug-patterns]].

apps/readest-app/.claude/memory/inline-block-column-overflow.md

@@ -1,18 +0,0 @@
----
-name: inline-block-column-overflow
-description: Foliate paginator fix — atomic-inline (inline-block) boxes too tall to fragment clip content in paginated mode
-metadata: 
-  node_type: memory
-  type: project
-  originSessionId: f0c35f7b-d4ff-4275-9f13-7019b0e167d9
----
-
-Bug: a chapter's content jumps straight to its "Reference materials", silently skipping a large middle (deep-dive/wrap-up). Repro book: "System Design Interview Vol.2" (System Design EPUB), Chapter 8 `OEBPS/c554.xhtml`, reported "at page 346".
-
-Root cause: the EPUB's own CSS wraps the whole chapter body in a `<div>` with `display: inline-block` (`.class_s5mz1`). Atomic inline-level boxes (inline-block / inline-flex / inline-grid / inline-table) **cannot fragment across CSS columns**, so in paginated (columnized) mode the 7700px-tall box overflows the page vertically and every column past the first is clipped → "1 page left in chapter" while most of the chapter is unreachable. Direct `goTo({index})` and forward `next()` both still RENDER the section (engine traverses by content), so the symptom only manifests as clipped/unreachable pages + bogus page counts; scrolled mode is unaffected (vertical overflow is normal there).
-
-Diagnosis tell: in column mode `documentElement.scrollHeight >> clientHeight` (e.g. 7768 vs 632); late headings stack vertically at one far-right column-left offset instead of spreading across columns.
-
-Fix: `packages/foliate-js/paginator.js` → `#demoteUnfragmentableBoxes(availableHeight)`, called from `columnize()` after `setImageSize` (column-mode only). Guarded fast-path: returns immediately unless `scrollHeight > clientHeight + 1`. When overflowing, scans `body.querySelectorAll('*')`, and for any element whose computed display is atomic-inline AND `getBoundingClientRect().height > availableHeight`, demotes to the fragmentable equivalent (inline-block→block, inline-flex→flex, inline-grid→grid, inline-table→table) via `setStylesImportant`. Idempotent (demoted elements no longer match), regression-free (short legit inline-blocks like side-by-side figures untouched — they're never page-tall). Mirrors the existing `setImageSize` over-tall-image clamp and the `p { display: block }` rule in `style.ts` ("epubs set insane inline-block for p").
-
-Test: `src/__tests__/document/paginator-inline-block-overflow.browser.test.ts` + fixture `repro-inline-block-overflow.epub` (one chapter wrapped in `.wrap{display:inline-block}`, 50 paras + TAIL_MARKER). Asserts `scrollHeight <= clientHeight+2`, wrap display `block`, tail heading in a later column within page height. Needs real layout → browser test (jsdom has no layout). Dev server (Next/Turbopack) picks up the workspace foliate-js edit on reload. Related: [[paginator-gutter-bleed-asymmetry-4394]].