feat: add native review editor desktop blocks

feat: migrate epub review editor into readest
release: version 0.11.18 (#5003 )
2026-07-09 00:50:58 +08:00 · 2026-07-08 21:26:40 +08:00 · 2026-07-07 20:17:35 +02:00 · 2026-07-07 19:47:26 +02:00 · 2026-07-08 02:31:01 +09:00 · 2026-07-07 18:01:18 +02:00
1285 changed files with 134100 additions and 10700 deletions
@@ -0,0 +1,131 @@
+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@1bcf9fb12cf4aa7d266a90ae39939e61372fe520 # 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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.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
@@ -61,7 +61,7 @@ jobs:
        # 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        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`
@@ -71,7 +71,7 @@ jobs:

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
-        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
@@ -100,6 +100,6 @@ jobs:
          exit 1

      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
        with:
          category: '/language:${{matrix.language}}'
@@ -39,7 +39,7 @@ jobs:
          platform=${{ matrix.platform }}
          echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"

-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          submodules: recursive

@@ -61,7 +61,7 @@ jobs:

      - name: Build and push by digest
        id: build
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: ./Dockerfile
@@ -0,0 +1,512 @@
+# 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 }}
+    # Backstop only — must stay ABOVE setup time + the per-step timeouts below,
+    # because a job-level timeout reports `cancelled` and skips assemble-manifest.
+    timeout-minutes: 75
+    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@1bcf9fb12cf4aa7d266a90ae39939e61372fe520 # 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
+          echo "SENTRY_DSN=${{ secrets.SENTRY_DSN }}" >> .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
+        timeout-minutes: 55
+        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
+
+      # The truly-portable AppImage bundler downloads quick-sharun.sh from
+      # Anylinux-AppImages@main ONLY when it is not already in the tauri tools
+      # cache. An upstream strace-mode change (2026-06-29) made bundling launch
+      # the app under Xvfb and hang forever, timing out the Linux legs (#4906).
+      # Seed the cache with the last known-good revision so the bundler never
+      # fetches the moving main-branch script.
+      - name: pin quick-sharun.sh for AppImage bundling (Linux)
+        if: matrix.config.release == 'linux'
+        run: |
+          set -euo pipefail
+          cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/tauri"
+          mkdir -p "$cache_dir"
+          curl -fsSL --retry 3 -o "$cache_dir/quick-sharun.sh" \
+            "https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/b3a9e985cdedf7efa81d172f182cd13983743147/useful-tools/quick-sharun.sh"
+          chmod +x "$cache_dir/quick-sharun.sh"
+
+      - name: build desktop bundles
+        if: matrix.config.release != 'android'
+        shell: bash
+        # A hung build must fail the STEP (step timeout -> job failure), not hit
+        # the job-level timeout: job timeouts report `cancelled`, which the
+        # assemble-manifest guard treats as run cancellation and skips promoting
+        # latest.json for ALL platforms (#4906).
+        timeout-minutes: 45
+        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
+        timeout-minutes: 30
+        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."
@@ -14,19 +14,19 @@ jobs:
      SCCACHE_GHA_ENABLED: 'true'
      RUSTC_WRAPPER: sccache
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        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@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1
        with:
          toolchain: stable
          override: true
          components: rustfmt, clippy
      - name: Cache apt packages
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: /var/cache/apt/archives
          key: apt-rust-lint-${{ runner.os }}
@@ -40,16 +40,19 @@ jobs:
      - 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

  build_web_app:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          submodules: 'true'

      - name: setup pnpm
-        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6

      - name: setup node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
@@ -57,30 +60,18 @@ jobs:
          node-version: 24
          cache: pnpm

-      # Turbopack persists its build cache here (turbopackFileSystemCacheForBuild).
-      # The key is deterministic (no commit SHA) so every PR restores the same
-      # entry — in practice the one `main` last saved, which is the only cache
-      # sibling PRs can all see.
-      - name: cache Turbopack build cache
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
-        with:
-          path: apps/readest-app/.next/cache
-          key: turbo-build-web-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-          restore-keys: |
-            turbo-build-web-${{ runner.os }}-
-
      - name: install Dependencies
        working-directory: apps/readest-app
        run: |
          pnpm install --frozen-lockfile --prefer-offline && pnpm setup-vendors

-      - name: install LuaJIT (for koplugin lint)
-        run: sudo apt-get update && sudo apt-get install -y luajit
-
      - name: run format check
        run: |
          pnpm format:check || (pnpm format && git diff && exit 1)

+      # 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
        working-directory: apps/readest-app
        run: |
@@ -93,7 +84,7 @@ jobs:

      - name: cache playwright browsers
        id: playwright-cache
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
@@ -120,15 +111,23 @@ jobs:
          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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          submodules: 'true'

      - name: setup pnpm
-        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6

      - name: setup node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
@@ -141,16 +140,91 @@ jobs:
        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@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.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
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        if: steps.changes.outputs.koplugin == 'true'
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: /var/cache/apt/archives
-          key: apt-test-web-${{ runner.os }}
+          key: apt-test-koplugin-${{ runner.os }}

-      - name: install LuaJIT + busted (for koplugin tests)
+      - name: install LuaJIT + busted (for koplugin lint + tests)
+        if: steps.changes.outputs.koplugin == 'true'
        run: |
          sudo apt-get update
-          # luajit  — pnpm test:lua
+          # 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,
@@ -160,27 +234,13 @@ jobs:
          sudo luarocks --lua-version=5.1 install busted
          sudo luarocks --lua-version=5.1 install lsqlite3complete

-      - name: cache playwright browsers
-        id: playwright-cache
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: install playwright browsers
+      - name: lint koplugin
+        if: steps.changes.outputs.koplugin == 'true'
        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 tests
-        working-directory: apps/readest-app
-        run: pnpm test:pr:web
+        run: pnpm lint:lua

      - name: run koplugin tests
+        if: steps.changes.outputs.koplugin == 'true'
        working-directory: apps/readest-app
        run: pnpm test:lua

@@ -190,12 +250,12 @@ jobs:
      SCCACHE_GHA_ENABLED: 'true'
      RUSTC_WRAPPER: sccache
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          submodules: 'true'

      - name: setup pnpm
-        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6

      - name: setup node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
@@ -206,7 +266,7 @@ jobs:
      # 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@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: apps/readest-app/.next/dev/cache
          key: turbo-dev-tauri-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
@@ -222,17 +282,32 @@ jobs:
        uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10

      - name: install Rust toolchain
-        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1
+        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # 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:
-          key: tauri-cargo
+          # 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@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: /var/cache/apt/archives
          key: apt-tauri-${{ runner.os }}
@@ -19,7 +19,7 @@ jobs:
      release_version: ${{ steps.get-release-notes.outputs.release_version }}

    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
      - name: setup node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
      - name: get version
@@ -89,7 +89,7 @@ jobs:
      contents: write
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: create KOReader plugin zip
        env:
@@ -118,10 +118,41 @@ jobs:
          echo "Uploading ${plugin_zip} to GitHub release"
          gh release upload ${{ needs.get-release.outputs.release_tag }} ${plugin_zip} --clobber

+  build-calibre-plugin:
+    needs: get-release
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: create calibre plugin zip
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          version=${{ needs.get-release.outputs.release_version }}
+
+          # Stamp PLUGIN_VERSION in __init__.py with the release version
+          # (from apps/readest-app/package.json, mirroring the koplugin's
+          # _meta.lua stamp above); the committed value is a dev placeholder.
+          version_tuple=$(echo "${version}" | awk -F. '{printf "(%d, %d, %d)", $1, $2, $3}')
+          perl -i -pe "s/^PLUGIN_VERSION = \(\d+, \d+, \d+\)/PLUGIN_VERSION = ${version_tuple}/" \
+            apps/readest-calibre-plugin/__init__.py
+
+          make -C apps/readest-calibre-plugin zip
+          plugin_zip="apps/readest-calibre-plugin/dist/Readest-${version}.calibre-plugin.zip"
+
+          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:
@@ -156,13 +187,13 @@ jobs:
    runs-on: ${{ matrix.config.os }}
    timeout-minutes: 60
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0

      - name: initialize git submodules
        run: git submodule update --init --recursive

      - name: setup pnpm
-        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6

      - name: setup node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
@@ -172,7 +203,7 @@ jobs:

      - name: setup Java (for Android build only)
        if: matrix.config.release == 'android'
-        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
+        uses: actions/setup-java@1bcf9fb12cf4aa7d266a90ae39939e61372fe520 # v5
        with:
          distribution: 'zulu'
          java-version: '17'
@@ -225,6 +256,7 @@ 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
+          echo "SENTRY_DSN=${{ secrets.SENTRY_DSN }}" >> .env.local
          cp .env.local apps/readest-app/.env.local

      - name: build and upload Android apks
@@ -267,13 +299,32 @@ jobs:
          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'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          cd apps/readest-app/
-          curl -sL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json
+          # 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"
@@ -297,7 +348,24 @@ jobs:
        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
+      # The truly-portable AppImage bundler downloads quick-sharun.sh from
+      # Anylinux-AppImages@main ONLY when it is not already in the tauri tools
+      # cache. An upstream strace-mode change (2026-06-29) made bundling launch
+      # the app under Xvfb and hang forever (#4906). Seed the cache with the
+      # last known-good revision so the bundler never fetches the moving
+      # main-branch script. Keep in sync with nightly.yml.
+      - name: pin quick-sharun.sh for AppImage bundling (Linux)
+        if: matrix.config.release == 'linux'
+        run: |
+          set -euo pipefail
+          cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/tauri"
+          mkdir -p "$cache_dir"
+          curl -fsSL --retry 3 -o "$cache_dir/quick-sharun.sh" \
+            "https://raw.githubusercontent.com/pkgforge-dev/Anylinux-AppImages/b3a9e985cdedf7efa81d172f182cd13983743147/useful-tools/quick-sharun.sh"
+          chmod +x "$cache_dir/quick-sharun.sh"
+
+      - uses: tauri-apps/tauri-action@1deb371b0cd8bd54025b384f1cd735e725c4060f # v1.0.0
+        id: tauri
        if: matrix.config.release != 'android'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -321,6 +389,16 @@ jobs:
          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 }}
@@ -373,13 +451,33 @@ jobs:
          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: |
-          curl -sL https://github.com/readest/readest/releases/latest/download/latest.json -o latest.json
+          # 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 }}
@@ -34,7 +34,7 @@ jobs:

    steps:
      - name: "Checkout code"
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

@@ -73,6 +73,6 @@ jobs:
      # 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@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4.36.0
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
        with:
          sarif_file: results.sarif
@@ -14,7 +14,8 @@ on:
        required: true
        type: string

-permissions: read-all
+permissions:
+  contents: read

 jobs:
  upload-to-r2:
@@ -11,7 +11,7 @@ jobs:
    permissions:
      contents: read
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          submodules: 'true'
      - uses: amondnet/vercel-action@de09aeac2ace6599ec9b11ef87558759a496bac4 # v42
@@ -26,6 +26,7 @@ docker/.env
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+readest-dev.log

 # local env files
 .env*.local
@@ -20,8 +20,8 @@ Basically you need to install or update the following development tools:
 - **Rust** and **Cargo** for Tauri development

 ```bash
-nvm install v22
-nvm use v22
+nvm install v24
+nvm use v24
 npm install -g pnpm
 rustup update
 ```
@@ -40,3 +40,7 @@ rust-version = "1.77.2"
 [patch.crates-io]
 tauri = { path = "packages/tauri/crates/tauri" }
 tauri-plugin-fs = { path = "packages/tauri-plugins/plugins/fs" }
+# Xcode 26.2 (Swift 6.2) broke upstream swift-rs 1.0.7's per-swiftc target
+# override; the vendored copy cross-compiles via `--triple`/`--sdk` instead.
+# Upstream is unmaintained (last release 2024). See packages/swift-rs.
+swift-rs = { path = "packages/swift-rs" }
@@ -45,15 +45,27 @@ COPY --from=dependencies /app/apps/readest-app/public/vendor /app/apps/readest-a
 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 PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-RUN corepack enable
-RUN corepack prepare pnpm@11.1.1 --activate
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME=0.0.0.0
 WORKDIR /app
-COPY --from=build /app /app
-WORKDIR /app/apps/readest-app
-ENTRYPOINT ["pnpm", "start-web", "-H", "0.0.0.0"]
+# 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"]
@@ -29,6 +29,7 @@
  <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> •
@@ -114,6 +115,12 @@ Stay tuned for continuous improvements and updates! Contributions and suggestion
 - 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]**
+
 ## Requirements

 - **Node.js** and **pnpm** for Next.js development
@@ -295,15 +302,7 @@ Readest is open-source, and contributions are welcome! Feel free to open issues,

 ## Support

-If Readest has been useful to you, consider supporting its development. You can [become a sponsor on GitHub](https://github.com/sponsors/readest), [donate via Stripe](https://donate.stripe.com/4gMcN5aZdcE52kW3TFgjC01), or [donate with crypto](https://donate.readest.com). Your contribution helps us squash bugs faster, improve performance, and keep building great features.
-
-### Sponsors
-
-<p align="center">
-  <a title="Browser testing via TestMu AI" href="https://www.testmuai.com/?utm_medium=sponsor&utm_source=readest" target="_blank">
-    <img src="https://raw.githubusercontent.com/readest/readest/refs/heads/main/data/sponsors/testmu-ai-logo.png" style="vertical-align: middle;" width="250" />
-  </a>
-</p>
+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

@@ -334,8 +333,8 @@ 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/github/license/readest/readest?color=teal
-[badge-release]: https://img.shields.io/github/release/readest/readest?color=green
+[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
@@ -350,6 +349,7 @@ We would also like to thank the [Web Chinese Fonts Plan](https://chinese-font.ne
 [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
@@ -1,59 +1,139 @@
 # Readest Project Memory

-## Key Reference Documents
- [Bug Fixing Patterns](bug-patterns.md) - Common bug categories, root causes, and fix strategies
- [CSS & Style Fixes](css-style-fixes.md) - EPUB CSS override patterns and the style.ts pipeline
- [TTS Fixes](tts-fixes.md) - Text-to-Speech architecture and bug patterns
- [Layout & UI Fixes](layout-ui-fixes.md) - Safe insets, z-index, platform-specific UI issues
- [Platform Compat Fixes](platform-compat-fixes.md) - Android, iOS, Linux, macOS platform-specific bugs
- [Annotator & Reader Fixes](annotator-reader-fixes.md) - Highlight, selection, accessibility bugs
-
-## Paginator Scroll Knowledge
- [Issue #4112 scroll-anchoring](issue-4112-scroll-anchoring.md) — RESOLVED (PR #4349). Scroll-anchoring suppressed at scrollTop 0 when prepending a section in scrolled mode; fix patterns (prepend compensation, eager backward preload, no-blank nav) + test & dev-server gotchas
- [Reading ruler line/column-aware](reading-ruler-line-aware.md) — ruler snaps to real lines; multi-column band spans one column; Range.getClientRects() returns tall block boxes that must be dropped; iframe frame-offset mapping; synthetic-key throttling
- [TOC expand + auto-scroll](toc-expand-and-autoscroll.md) — #4059 collapse-by-default policy in `tocTree.ts`; pinned-sidebar mounts before progress → dynamic expansion breaks scroll-to-current via (1) spurious onScroll clearing pending and (2) Virtuoso scrollToIndex landing short after row growth (re-assert on rAF)
- [Swipe page-turn bg flash](paginator-swipe-bg-flash.md) — white↔black flash on swipe+animation only; `#background` was static screen-space and didn't track content during drag/snap; fix = sliding per-view full-bleed segments (`computeBackgroundSegments`) rebuilt on scroll + per-rAF synced to the view transform during snap
-
+## 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) · [Annotator & Reader](annotator-reader-fixes.md)
+## Safety & Security
+- [In-place delete wiped originals](in-place-delete-wiped-originals.md) never `fs.removeFile` `external` · [Backup zip Windows paths #4703](backup-windows-zip-paths-4703.md) normalize `\` · [download_file scope Android #4639](download-file-scope-android-regression.md)
+- [Security advisories 2026-06](security-advisories-web-2026-06.md) 4 GHSA #4638; SSRF guard broke dev-LAN OPDS, dev-only exemption 2026-07 PR#5002
+## Paginator & Scroll
+- Reading ruler: [line-aware](reading-ruler-line-aware.md) frame-offset map; [vertical-rl backwards #4865](reading-ruler-vertical-rtl-4865.md)
+- [Vertical-rl horizontal pagination (#624)](vertical-rl-horizontal-pagination-624.md) — horizontal inputs + two-phase slide; rtl gated `!vertical`
+- [Slide/curl turn styles via VT (#555)](page-turn-styles-viewtransitions-555.md) — VT turns gated on nested-VT-groups support (iOS 18 WebKit crashes despite having the API); Tauri fallback = `CapturedPageTurn` capture pipeline (WebGL mesh curl + flat canvas slide, full-gridcell capture, instant nav = drop `animated`); MERGED #4940 (2026-07-05), verified live mac/iOS/Android (mobile = JPEG capped 2x, PNG was 1.5s/turn); Win/Linux capture still open
+  - [Captured turn ignored instant-highlight hold](captured-turn-instant-highlight-scrolllock.md) — captured slide/curl swipe path (app interceptor, `no-swipe` set) didn't honor `renderer.scrollLocked`; fix = foliate `get scrollLocked()` + gate `useCapturedTurn` move on it (push/VT-slide already gated); PR#5000 + foliate#51
+- TOC: [expand + auto-scroll](toc-expand-and-autoscroll.md); [current-position row](toc-current-position-row.md); [table heading clip #4439](toc-table-heading-clip-4439.md); [BooknoteView auto-scroll #4352](booknote-view-autoscroll-4352.md)
+- Paginated bg: [swipe flash](paginator-swipe-bg-flash.md); [texture occlusion #4399](paginated-texture-occlusion-4399.md); [gutter bleed #4394](paginator-gutter-bleed-asymmetry-4394.md); [bg-replace reflow #4785](pageturn-bg-replace-reflow-4785.md)
+- [Inline-block column overflow](inline-block-column-overflow.md) `#demoteUnfragmentableBoxes`
+- FXL/PDF: [fit-width scroll reset #4683](fixed-layout-paginated-scroll-reset-4683.md); [PDF spread seam #4587](pdf-spread-canvas-seam-4587.md); [spine seam #4857](fxl-spread-spine-seam-4857.md); [portrait auto-spread off-center #4984](fxl-portrait-autospread-offcenter-4984.md) MERGED PR#4992+foliate#50 lone page kept one-sided auto margin -> stranded + taps turned page; `computeSpreadInlineMargins`
+- Scrolled: [PDF wheel double #4727](pdf-scroll-mode-wheel-double-4727.md); [header title center #4436](scrolled-header-title-center-4436.md); [Duokan fullscreen cover](duokan-fullscreen-cover-scroll.md)
 ## Critical Files (Most Bug-Prone)
- `src/utils/style.ts` - Central EPUB CSS transformation hub (14+ bug fixes)
- `packages/foliate-js/paginator.js` - Page layout, image sizing, backgrounds
- `src/services/tts/TTSController.ts` - TTS state machine, section tracking
- `src/hooks/useSafeAreaInsets.ts` - Safe area inset management
- `src/app/reader/components/FoliateViewer.tsx` - Reader view orchestration
- `src/app/reader/components/annotator/Annotator.tsx` - Annotation lifecycle
-
+- `src/utils/style.ts` EPUB CSS hub · `packages/foliate-js/paginator.js` · `src/services/tts/TTSController.ts`
+- `src/hooks/useSafeAreaInsets.ts` · `src/app/reader/components/FoliateViewer.tsx` · `.../annotator/Annotator.tsx`
 ## Sync Notes
- [KOSync CFI spine resolution](kosync-cfi-spine-resolution.md) — convert via the CFI's own spine (`getXPointerFromCFI`/`getCFIFromXPointer`), never `new XCFI(primaryDoc, primaryIndex)`; primaryIndex lags during scroll → spine-mismatch throw
- [Empty-start CFI sync bug](empty-start-cfi-sync.md) — `epubcfi(/6/24!/4,,/20/1:58)` (empty-start range) from the cfi-inert skip-link transitional window; jumps to wrong section end; `isMalformedLocationCfi` → discard the synced value in `useProgressSync` (NOT the local open path); foliate fix doesn't repair already-synced values
-
-## Feature Notes
- [Manage Cache + iOS container layout](manage-cache-ios-layout.md) — `'Cache'` base = `Library/Caches/<bundle>` only (not all of Caches); iOS `Documents/Inbox` cleared too; WebKit cache + tmp out of reach; never touch App Support
- [D-pad Navigation](dpad-navigation.md) — Android TV remote / keyboard arrow navigation design, key files, and pitfalls
- [Cloudflare Workers WebSocket](cloudflare-workers-websocket.md) — use fetch() Upgrade pattern (not `ws` npm); CF delivers binary frames as Blob (must serialize async decodes)
- [Share-a-Book Feature (in progress)](share-feature.md) — locked decisions for the /s/{token} share-link feature; plan at ~/.claude/plans/ok-we-will-learn-cosmic-acorn.md
- [readest.koplugin i18n](koplugin-i18n.md) — gettext loader at `apps/readest.koplugin/i18n.lua`, `.po` catalog at `locales/<i18next-code>/translation.po`, extract/apply scripts in `scripts/`
-
-## Patterns
- [Virtuoso + OverlayScrollbars](virtuoso_overlayscrollbars.md) — useOverlayScrollbars hook integration for overlay scrollbars on mobile webviews
- [Design system → DESIGN.md](feedback_design_system_doc.md) — codify recurring UI/UX rules in `apps/readest-app/DESIGN.md`; never `pl/pr/ml/mr/text-left/text-right` (RTL); §5 boxed list anatomy has uniform `min-h-14` rows and chromeless controls
-
-## Architecture Notes
- foliate-js is a git submodule at `packages/foliate-js/`
- Multiview paginator: loads adjacent sections in background, multiple View/Overlayer instances per book
- Style overrides: `getLayoutStyles()` (always), `getColorStyles()` (when overriding color)
- `transformStylesheet()` does regex-based EPUB CSS rewriting at load time
- TTS uses independent section tracking (`#ttsSectionIndex`) decoupled from view
- Safe area insets flow: Native plugin -> useSafeAreaInsets hook -> component styles
- Dropdown menus use `DropdownContext` (not blur-based) for screen reader compat
- [Foliate touch-listener capture phase](foliate-touch-listener-capture-phase.md) — to suppress reader gestures from the app, use `{capture:true}`; the paginator registers bubble-phase doc listeners first (during `view.open()`)
-
-## Workflow
- [Test file filter](feedback_test_file_filter.md) — use `pnpm test <path>` without `--` to run a single file
- [Always rebase before PR](feedback_pr_rebase.md) — rebase onto origin/main before creating PRs
- [New branch per PR](feedback_pr_new_branch.md) — always create a fresh branch from main for each new PR/issue
- [Upgrade gstack locally](feedback_gstack_upgrade.md) — always upgrade from the project's .claude/skills/gstack, not global
- [No lookbehind regex](feedback_no_lookbehind_regex.md) — never use `(?<=)` or `(?<!)` in JS/TS; build check rejects them
- [Use worktree](feedback_use_worktree.md) — never `git worktree add` directly; always `pnpm worktree:new` before PR review, issue fix, or feature work
- [en/translation.json holds ONLY plural variants + proper nouns](feedback_en_plurals_manual.md) — non-plural strings stay out (defaultValue: key is the en source); plural strings (`_('...', { count })`) need hand-added `_one`/`_other` entries or the singular renders as "1 days"
- [Never push on every change](feedback_dont_push_every_change.md) — hold pushes during active bug iteration; commit locally only until user confirms or work hits a clean done-state
- [No test seams in production code](feedback_no_test_seams_in_prod.md) — production must never import or call `__reset*ForTests`; cross-module test resets belong in the test file's beforeEach/afterEach
+- [Cloud Sync provider selection #4959/#4380](cloud-sync-provider-selection-plan.md) MERGED #4971+#4973+#4975+#4976: derived provider, exclusive routing, syncBooks auto-enable, fleet probe, chooser; i18n pass + live verify pending
+- [Grimmory native sync](grimmory-native-sync.md) Booklore-fork REVERTED
+- KOSync: [CFI spine resolution](kosync-cfi-spine-resolution.md); [connect() false-positive #4692](kosync-connect-false-positive-4692.md)
+- [Empty-start CFI sync](empty-start-cfi-sync.md) · [Custom fonts vanish #4410](custom-fonts-reincarnation-4410.md) CRDT remove-wins
+- koplugin: [note deletion](koplugin-note-deletion-sync.md) tombstone; [stats #4666](koplugin-stats-sync.md); [bulk download #4751](koplugin-bulk-download-4751.md); [dup book rows #4861](koplugin-stats-duplicate-book-rows-4861.md)
+- [Statusless re-pin #4677](sync-statusless-book-rebump-4677.md) · [pull cursor synced_at #4678](sync-synced-at-cursor-4678.md)
+- [koplugin library stale #4934](koplugin-library-stale-synced-cursor-4934.md) pull cursor updated_at→synced_at + split push watermark + v2→v3 heal migration
+- WebDAV: [metadata #4756](webdav-metadata-sync-4756.md) LWW; [group membership #4942](webdav-group-membership-sync-4942.md) mergeBookMetadata dropped groupId/groupName; [credentials #4810](webdav-credential-sync-4810.md); [connect nullified #4780](webdav-connect-nullified-4780.md) stale closure
+- [WebDAV deletion + upload-after-enable (#4860/#4856)](webdav-deletion-and-upload-after-enable-4860-4856.md) edit-wins LWW + tombstone union
+- File sync: [refactor #4784](webdav-filesync-refactor-plan.md) `FileSyncEngine`; [third-party auto-sync #4835](third-party-library-autosync-4835.md)
+- [Transfer Queue clear not persisted](transfer-queue-clear-persistence.md) hook mutated store directly, skipped `persistQueue()`; route clears through `transferManager`
+- [Multi-window settings clobber (#4580)](multiwindow-settings-clobber-4580.md)
+- Google Drive: [research](gdrive-sync-provider-research.md); [multi-PR status](gdrive-provider-multipr-status.md); [full walk every sync](gdrive-fullwalk-every-sync-no-source-cursor.md) no-source books never recorded in uploadedHashes + focus refires pullLibrary
+- [S3/R2 provider](s3-r2-sync-provider.md) third backend, aws4fetch SigV4 path-style, full slice on dev uncommitted; live R2 verify pending
+- [Hardcover edition_id (#4792)](hardcover-progress-edition-id-4792.md)
+## Build, Testing & CI
+- [Nightly quick-sharun hang #4906](nightly-quick-sharun-hang-4906.md) pin via cache pre-seed + step timeouts
+- [format:check separate gate](verify-format-check-gate.md) · [Worktree rebase submodule drift](worktree-rebase-submodule-drift.md)
+- Android CDP: [e2e lane](android-cdp-e2e-lane.md) `pnpm test:android`; [WebView profiling](cdp-android-webview-profiling.md); [double-tap gesture](android-e2e-doubletap-cdp-gesture.md)
+- [Tauri Rust↔JS parser parity](tauri-parser-parity-tests.md)
+- TTS tests: [browser e2e harness](tts-browser-e2e-harness.md); [paragraph+RSVP sync #3235](tts-sync-paragraph-rsvp-3235.md) TTS-is-clock
+- [fastlane App Store](fastlane-apple-appstore-submission.md) `APPLE_API_KEY_PATH` out of build env
+- [Turbopack cache OOM (#4619)](turbopack-build-cache-oom-docker-standalone.md)
+- [Deps override workflow](deps-security-overrides-workflow.md) `pnpm-workspace.yaml`
+- [Xcode 26.2 broke iOS builds (swift-rs)](xcode26-swiftrs-ios-build-broken.md) — phantom `Bundle.main`/`privacy:` errors; vendored `packages/swift-rs` `--triple`/`--sdk`; Package.swift platforms floor now enforced
+- [pdfjs vendor wasm](pdfjs-vendor-wasm-decoders.md) copy `wasm/*`
+- [CI/PR delivery + push keepalive](ci-pr-delivery-and-push.md)
+## Platform Compat
+- Android: [hyphen selection #1553](android-hyphen-selection-bounds-1553.md); [NativeFile vs RemoteFile I/O](android-nativefile-remotefile-io.md)
+- [Window-state sanitizer #4398](window-state-sanitize-4398.md) · [Android themed icon #4733](android-themed-icon-4733.md)
+- [Open-with intent #4521](android-open-with-intent-flow.md) · [dict lookup hijack #4559](dict-lookup-browser-hijack-4559.md)
+- [Large-PDF OOM range flood (#3470)](pdf-oom-range-flood-3470.md) MAX_CONCURRENT_RANGES=6
+- [Black screen external cache (#4853)](android-black-screen-external-cache-4853.md) FIXED PR#4889; drop `$CACHE` grants
+- [macOS 26 Tahoe close→black window (#4875)](macos26-tahoe-close-black-screen-4875.md) `minimize()` not `hide()`
+- [Linux app invisible after backup (#3682)](linux-transparent-window-invisible-3682.md) FIXED PR#4904 opaque window
+- [Apple OAuth expired + deeplink swallowed (#4881)](oauth-deeplink-error-swallowed-4881.md)
+- [Annotation link ignored when reader open #4887](deeplink-drop-running-macos-4887.md) `open-book-in-reader` event
+- [iOS auto-brightness locks (#4885)](ios-brightness-lock-background-4885.md) brightness GLOBAL; release on bg
+- [iOS share .txt stuck #4917](ios-share-txt-stuck-supportstext.md) drop SupportsText in `project.yml` (xcodegen src)
+- [Updater disable non-AppImage (#4874)](updater-disable-nonappimage-linux-4874.md)
+- [Fullscreen no-op Phosh (#4034)](fullscreen-maximized-phosh-4034.md) drop `isMaximized` branch
+## Reader Features & UI
+- [Android Auto TTS #3919/PR#4907](android-auto-tts-3919.md) MERGED; CarPlay blocked on entitlement
+- Widgets: [mobile reading #1602/PR#4842](mobile-reading-widgets.md); [iOS App Group stripped PR#4891](ios-widget-appgroup-stripped-appstore.md); [cover bright right-edge line](ios-widget-cover-bright-edge-line.md) fractional resize → round target to whole px
+- PDF: [scrolled lag #4795](pdf-scroll-lag-preload-4795.md); [scrolled pinch-zoom #4817](scrolled-pdf-pinch-zoom-4817.md); [pinch vs two-finger scroll #4858](pinch-vs-twofinger-scroll-4858.md); [text selection misplaced w/ OS font scale #4480](pdf-text-selection-fontscale-4480.md) OS font-scale inflates text-layer glyph size not positions; divide `--text-scale-factor` (font-size lever) by detected scale, NOT `--total-scale-factor`
+- [Search modes #4560](search-modes-4560-and-spoiler-bound-bug.md)
+- [OPDS groups carousel #4750](opds-groups-carousel-4750.md) · [WebDAV browser sort+search #4724](webdav-browse-sort-search-4724.md)
+- [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); [delete orphan #4773](instant-highlight-delete-orphan-4773.md); [empty leak #4791](empty-highlight-leak-on-annotate-cancel-4791.md)
+- Selection: [keyboard adjust #4728](keyboard-selection-adjust-4728.md); [cross-page auto-turn #4741](cross-page-selection-autoturn-4741.md)
+- Click/tap: [double-click word select](iframe-double-click-word-select.md); [dblclick-drag #4524](dblclick-drag-pageturn-4524.md); [tap open image/table #4600](tap-to-open-image-table-4600.md)
+- [Annotator onLoad listener leak (#4735)](annotator-onload-listener-leak-paragraph-mode.md)
+- Paragraph mode: [toggle/resume #4717](paragraph-mode-toggle-resume-4717.md); [accidental exit #4474](paragraph-mode-accidental-exit-4474.md)
+- [#4584 tap-death](issue-4584-tap-death-investigation.md) UNFIXED; likely WebView-148
+- [PDF/CBZ Contrast view-menu](pdf-cbz-contrast-view-menu.md) ONE `filter:`
+- [Header/footer over light PDF in dark (#4901)](pdf-header-footer-contrast-blend-4901.md) `mix-blend-difference`, FIXED light anchor
+- [iOS instant-dict double popup](ios-instant-dict-double-popup.md) once-per-gesture latch
+- Dict: [popup font size #4443](dict-popup-font-size-4443.md); [lemmatization #4574](dict-lemmatization-4574.md); [popup speak button #4876](dict-popup-tts-speak-4876.md) standalone wordPronouncer, Edge-direct + dedicated WebAudio ctx
+- Word Lens: [inline gloss](wordlens-feature.md) CFI-safe ruby; [en-en](wordlens-en-en.md)
+- [Stripe highest-active plan (#4694)](stripe-plan-highest-active-4694.md)
+- [Save image to gallery (#4680)](save-image-to-gallery-android.md) MediaStore
+- [Webtoon Mode (#3647)](webtoon-mode-3647.md)
+- [Middle-click autoscroll #4951](middle-click-autoscroll-4951.md) Autoscroller RAF core; `containerPosition +=`; armed-books preventDefault
+- [Auto Scroll teleprompter #4998](auto-scroll-teleprompter-4998.md) MERGED PR#4999 PacedScroller + useAutoScroll + gridcell-centered pill; scrolled-only; tap=pause via iframe-single-click consume
+- [Biometric app-lock #4645](biometric-app-lock-4645.md) · [Reference Pages #4542](reference-pages-672-4542.md) · [e-ink refresh page-turner #4687](eink-screen-refresh-pageturner-4687.md)
+- [Share intent + toolbar (#4014)](annotation-share-toolbar-4014.md)
+- Customize Toolbar: [global serializeConfig #4760](customize-toolbar-global-serializeconfig.md); [e-ink black bar #4839](customize-toolbar-eink-black-bar-4839.md)
+- [Edge TTS Web Audio engine (#3851)](edge-tts-webaudio-engine.md) gapless WebAudioPlayer + WSOLA
+- [Background TTS sessions PR#4941](tts-background-session-decoupling.md) — hash-keyed session manager, detach/attach, NowPlayingBar; header X routes `onCloseBook` NOT `onGoToLibrary`
+- [TTS player redesign](tts-player-redesign.md) mini-player + Dialog sheet replaces icon/popup/TTSBar; MERGED #4996; open: isPlaying glyph desync at section transitions
+- [Android bg TTS media session fix](android-bg-tts-media-session-fix.md) — #4941/#4931 regression: `startService()` dies backgrounded → in-process instance calls; always request POST_NOTIFICATIONS; + lock-screen duration scrubber + `onSeekTo` (Edge-only)
+- Native TTS: [iOS #4676](native-ios-tts-4676.md) pause==stop; [offline halt #4613](native-tts-offline-autoadvance-4613.md)
+- Edge TTS: [word highlight #4017](edge-tts-word-highlighting-4017.md); [drift](tts-word-highlight-singletextnode-drift.md)
+- TTS UX: [highlight granularity](tts-highlight-granularity-setting.md); [start-from-selection](tts-start-from-selection.md); [reuse session](tts-reuse-session-mode-entry.md)
+- RSVP: [control-bar REVERT](rsvp-control-bar-overlap-revert.md); [font #4519](rsvp-font-settings-4519.md); [RTL word #4630](rsvp-rtl-word-display-4630.md)
+- [Overlay z-index scale](zindex-overlay-scale.md) RSVP 100 → app-lock
+- [Global annotation page-turn lag (#4575)](global-annotation-pageturn-perf-4575.md)
+- [Overlayer splitRange text nodes](overlayer-splitrange-textnodes.md)
+- [Android image callout freeze](android-image-callout-freeze.md) `.no-context-menu` ANCESTOR
+- [Inline-img vertical-align (#4866)](inline-img-vertical-align-4866.md) gated on computed valign
+- [Table dark-mode tint #4419](table-dark-mode-tint-4419.md) · [footnote aside border #4438](footnote-aside-namespace-order-4438.md)
+- Proofread: [enhancements #4700](proofread-enhancements-4700.md); [per-book CRDT #4781](proofread-per-book-crdt-sync.md); [edit Find + toggle #4859](proofread-edit-toggle-4859.md)
+- [Russian NBSP (#4769)](russian-hanging-prepositions-nbsp-4769.md)
+- OPDS: [Firefox strict-XML #4479](opds-firefox-strict-xml-4479.md); [JSON search #4502](opds2-json-search-4502.md); [HTML desc #4503](opds-html-description-4503.md); [self-link #4749](opds-self-link-metadata-4749.md); [popular dedup #4782](opds-popular-catalog-dedup-4782.md); [auto-download subdir crawl #4272](opds-autodownload-subdir-crawl-4272.md) bounded BFS, never crawl newest-feed catalogs; [preemptive Basic 400s digest Calibre](opds-preemptive-basic-digest-400.md) bare-retry on 400 PR#5002; [auto-download TLS #4988](opds-autodownload-tls-skipssl-4988.md) skipSslVerification parity PR#5002
+- [D-pad Navigation](dpad-navigation.md)
+- [koplugin cover upload (#4374)](koplugin-cover-upload.md)
+- [koplugin Library slow open #4954](koplugin-library-open-mosaic-cache-4954.md) group mosaics recomposed every paint; PR#4974 availability-keyed cache + async compose + cache nil result
+- [Calibre plugin push #4863](calibre-plugin-push-4863.md) OAuth localhost relay
+- [Calibre custom columns #4811](calibre-custom-columns-4811.md) `metadata.calibreColumns`
+## Library Fixes
+- [Book action platform surfaces](book-actions-platform-surfaces.md) · [menu append race #4389](tauri-menu-append-race-4389.md)
+- TXT: [author recognition #4390](txt-author-recognition-4390.md); [chapter measure-word FP #4658](txt-chapter-measure-word-4658.md)
+- [Cover stale (in-place mutation)](cover-stale-inplace-mutation-memo.md)
+- [Series/author back no-op (#4437)](series-folder-back-noop-4437.md)
+- [Library/reader separate texture #4743](library-reader-separate-texture-4743.md) · [list view series overflow #4796](list-view-series-overflow-4796.md)
+- [Recently-read shelf (#3797)](recent-read-shelf-3797.md)
+- [Auto-import watched folders (#3889)](auto-import-watched-folders-3889.md) per-folder opt-in
+## Architecture & Patterns
+- foliate-js submodule at `packages/foliate-js/`; multiview paginator preloads adjacent sections
+- [Turso "concurrent use forbidden"](turso-concurrent-use-forbidden.md) `op_lock` async mutex
+- Markdown: [.md support #774](markdown-md-support-774.md); [resume position #4862](markdown-resume-position-4862.md)
+- Style: `getLayoutStyles()` always, `getColorStyles()` when overriding; `transformStylesheet()` rewrites EPUB CSS
+- TTS `#ttsSectionIndex`; insets: native plugin → useSafeAreaInsets → styles; Dropdowns `DropdownContext`
+- Stale settings closure: persist `useSettingsStore.getState().settings` ([#4780](webdav-connect-nullified-4780.md))
+- [Page margins not live #4898](page-margin-live-update-4898.md) in-place mutation froze memo
+- [Foliate touch-listener capture phase](foliate-touch-listener-capture-phase.md)
+- [iframe cross-realm instanceof](iframe-cross-realm-instanceof.md) duck-type `'closest'`
+- [Virtuoso + OverlayScrollbars](virtuoso_overlayscrollbars.md)
+- [Design system → DESIGN.md](feedback_design_system_doc.md) never `pl/pr/ml/mr` (RTL)
+## Workflow & Feedback
+- [Commit messages English-only](feedback-commit-message-english-only.md) no CJK, no em/en dashes
+- PR flow: [rebase onto origin/main](feedback_pr_rebase.md); [fresh branch per PR](feedback_pr_new_branch.md); [always `pnpm worktree:new`](feedback_use_worktree.md); [commit locally, don't push until confirmed](feedback_dont_push_every_change.md)
+- [Test file filter](feedback_test_file_filter.md) `pnpm test <path>` no `--`
+- [No test seams in prod](feedback_no_test_seams_in_prod.md) · [no lookbehind regex](feedback_no_lookbehind_regex.md)
+- i18n: [en plurals manual](feedback_en_plurals_manual.md); [i18n:extract prunes keys](i18n-extract-prunes-keys.md)
+- [Dependabot transitive fixes](dependabot-pnpm-overrides.md) `pnpm-workspace.yaml` `overrides:`
+- [Upgrade gstack locally](feedback_gstack_upgrade.md)
@@ -0,0 +1,26 @@
+---
+name: android-bg-tts-media-session-fix
+description: Android background TTS regression - startService() dies backgrounded; use in-process service calls; + lock-screen scrubber/seek
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 052bb3f3-27fe-4eb0-95c3-699a3122083a
+---
+
+Branch `fix/android-bg-tts-media-session` (worktree `/Users/chrox/dev/readest-fix-android-bg-tts-media-session`), 2026-07-07. **PR readest/readest#4994 MERGED** (2026-07-07; worktree + local branch cleaned up. rebased onto origin/main; foliate-js submodule re-synced to f6dced2 after rebase per [[worktree-rebase-submodule-drift]]). 5 commits: 15817fc4b in-process IPC, 04e4b4fe6 duration scrubber+seek, 67c22b72b FGS hardening+diagnostic logs, 27e224bcc keepAppInForeground removal (the real fix), a8643ec12 Edge edge-fade click fix. Verified on-device (Xiaomi/MIUI/Android 15). Diagnostic Log.d traces left in 67c22b72b (offered to strip).
+
+**Regression (commit 1, `fix(android): keep background TTS media controls alive when backgrounded`):** after #4941 (session decoupling) + #4931 (Edge WebAudio engine), Android background TTS lost the lock-screen control and audio died when backgrounded. Logs: `Not allowed to start service Intent { act=UPDATE_PLAYBACK_STATE ... MediaPlaybackService }: app is in background`.
+
+Root cause: `NativeTTSPlugin.update_media_session_state`/`update_media_session_metadata` pushed updates to the already-running foreground service via `activity.startService(intent)`. Android 8+ (BSSR) rejects `Context.startService()` from the background unless an active foreground service exempts the app; each per-sentence update threw, so the FGS notification stopped refreshing (lock-screen control went stale) and the audio route was lost. **Fix pattern: never `startService()` to talk to a running service - call the live instance in-process.** `MediaPlaybackService` already had the pattern: static `@Volatile instance` + `requestDeactivation()` posting to it on the main thread. Added companion `pushMetadata`/`pushPlaybackState` (update statics, post to `instance` via `Handler(Looper.getMainLooper())`) + private instance `applyMetadata`/`applyPlaybackState`; removed the dead `UPDATE_METADATA`/`UPDATE_PLAYBACK_STATE` intent branches + the now-unused `serviceScope`/`kotlinx.coroutines.*`. `startForeground()` to *update* an already-foregrounded service is allowed from background (unlike `Context.startForegroundService()` to *start* one).
+
+Secondary: #4941 dropped the `keepAppInForeground`/notification titles from `TTSMediaBridge.bind()`'s `setActive({active:true})`. `keepAppInForeground` gated `requestPostNotificationPermission()` in `mediaSession.ts`, and it defaults false (`alwaysInForeground` in constants.ts), so POST_NOTIFICATIONS was never requested. Fix: `setActive` requests it on EVERY activation (no-op once decided), not gated on the setting - else the FGS media notification (= the lock-screen control) is silently suppressed on Android 13+.
+
+**Feature (commit 2, `feat(android): show section duration and enable seek on the TTS media session`):** user asked to show estimated section duration + seek from the media session. JS half was already there - `ttsMediaBridge.#updatePositionState` already sends `{playing, position, duration}` (ms) every mark, and `mediaSession.ts` already listens for a `media-session-seek` event -> `handlers['seekto']` -> `controller.seekToTime(pos/1000)`. Native side never used them. Added: `METADATA_KEY_DURATION` in the session metadata (Android reads scrubber length from METADATA, thumb from PlaybackState), `ACTION_SEEK_TO` in `setActions`, and `SessionCallback.onSeekTo(pos)` -> `pluginEventTrigger("media-session-seek", {position})` + optimistic thumb move. Bare play/pause updates omit position/duration, so `pushPlaybackState(playing, position: Long?, duration: Long?)` preserves last-known statics (else scrubber snaps to 0 on pause). **Section timeline is Edge/WebAudio ONLY** (`TTSController` comment "position/duration/seek (Edge client only)"; `getPlaybackInfo()` returns null for native TextToSpeech) - native TTS leaves duration 0 so no scrubber appears, which is correct.
+
+**On-device (Xiaomi/MIUI, targetSdk 36) round 1 FAILED - two findings:** (1) tested APK was STALE - logcat still showed `startService(act=UPDATE_METADATA/UPDATE_PLAYBACK_STATE)` which the fix removes, so the fix wasn't built in (likely built from main tree, not the worktree). (2) Deeper root cause the IPC fix does NOT touch: `W/ActivityManager: Stopping service due to app idle: ...MediaPlaybackService` = the service was NEVER promoted to a foreground service (FGS services aren't idle-stopped; readest uid never appears in FGS-type logs). Also MIUI hostile: uid 10186 (SecurityCenter) repeatedly sets readest `post_notification` appop to `ignore`; `Force stopping service`. Audio plays via WebView (`org.chromium.content.browser.AudioFocusDelegate` holds focus), and the service ExoPlayer also requests AUDIOFOCUS_GAIN - possible focus-steal conflict (unconfirmed).
+
+**Commit 3 (`fix(android): harden TTS foreground-service promotion + add diagnostics`):** `showNotification` now uses `ServiceCompat.startForeground(this, id, notif, ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK)` (explicit type, targetSdk 34+) wrapped in try/catch+Log. `setActive` (mediaSession.ts) decoupled: POST_NOTIFICATIONS request in its own try/catch so a throw/hang can't abort `set_media_session_active` (the FGS start). Trace logs added: `set_media_session_active: startForegroundService` (plugin), `activateSession (wasActive=)`, `startForeground ok`/`failed`. Next device run: build FROM the worktree + `adb uninstall com.bilingify.readest` first; set MIUI Autostart ON + battery No-restrictions + lock in recents; grep logcat for those tags to see where the FGS path breaks. If `startForeground ok` but audio still dies backgrounded -> WebAudio AudioContext suspension (test native voice: survives = confirms WebView issue).
+
+**ACTUAL ROOT CAUSE found round 3 (WebView console `[INFO:CONSOLE]` via `adb logcat` chromium tag):** `Failed to set media session active state: invalid args payload for command set_media_session_active: missing field keepAppInForeground`. The Rust `SetMediaSessionActiveRequest` (models.rs) had `keep_app_in_foreground: bool` as a REQUIRED serde field (all other fields `Option`); #4941's `ttsMediaBridge.bind()` sends `setActive({active:true})` without it, so **Tauri rejected the invoke at the serde layer before the command ran** -> `set_media_session_active` never executed -> FGS never started -> no notification + Android 15 `AS.AudioService: AudioHardening background playback would be muted` killed background audio. Every earlier fix (in-process IPC, FGS hardening, POST_NOTIFICATIONS decouple) was downstream of this and couldn't help because the command never ran. Diagnostic trap: native tags (MediaPlaybackService/NativeTTSPlugin) were absent from logcat because the service was never touched; the answer was only in the WebView JS console (grep logcat for `CONSOLE`). Commit 4 (`fix(android): drop required keepAppInForeground so the TTS service starts`, 27e224bcc): removed `keepAppInForeground` ENTIRELY (dead everywhere - no platform read it; FGS always starts, POST_NOTIFICATIONS now unconditional) from Rust/Kotlin/iOS/TS payloads per user request ("default true"). Follow-up commit 0b8843012 also removed the now-dead `alwaysInForeground` setting + its Android "Background Read Aloud" library-menu toggle (settings.ts/constants.ts/SettingsMenu.tsx + tests) and pruned the i18n key across 33 locales via `pnpm i18n:extract`. **Lesson: on a failed Tauri mobile command, capture the WebView console (logcat `CONSOLE` tag) FIRST - serde arg-rejection surfaces only there, not in native logs.**
+
+Verified: `pnpm test` (7022 pass), `pnpm lint` clean, `cargo check/fmt/clippy -p tauri-plugin-native-tts` clean. **Kotlin NOT compiled/device-verified** - worktree `src-tauri/gen/android` lacks `tauri.settings.gradle` so the plugin's `app.tauri.plugin.*` deps don't resolve standalone; needs `pnpm tauri android` on a real Android 13+/14 device (logcat: foreground -> background -> lock screen). Related: [[tts-background-session-decoupling]], [[edge-tts-webaudio-engine]], [[native-ios-tts-4676]].
@@ -0,0 +1,21 @@
+---
+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).
@@ -0,0 +1,56 @@
+---
+name: android-e2e-doubletap-cdp-gesture
+description: Nightly Android E2E double-tap test failed since
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: eafe11ed-faac-4406-957d-1674353f081c
+---
+
+Nightly `Android E2E (CDP)` failed every night from 2026-06-28 (first night after
+PR #4846 merged) with `timed out waiting for selection of "..." (last: null)` in
+`double-click.android.test.ts`. The test never passed on CI. Fixed 2026-07-04 —
+harness-only, no app code changed.
+
+**Two stacked root causes:**
+
+1. **PRIMARY — feature is opt-in on mobile.** `DEFAULT_MOBILE_VIEW_SETTINGS`
+   ships `disableDoubleClick: true` (double-click detection delays single-tap
+   page turns by the 250ms disambiguation window, so mobile opts out).
+   `handleClick` (iframeEventHandlers.ts) then posts `iframe-single-click`
+   IMMEDIATELY and never arms the double-click window — the #4846 double-tap
+   word selection is deliberately "gated by the user's double-click setting"
+   (Annotator comment). The e2e assumed default config → could never pass on a
+   fresh device. Diagnostic signature: `iframe-single-click` ~20ms after click
+   (window disabled) vs ~250ms after (window armed, no second click).
+2. **SECONDARY — adb double-tap can't hit the window.** The old helper ran
+   `input tap x y && input tap x y`; each `input` invocation spawns a fresh
+   app_process JVM (measured 0.9–1.05s each, 28s cold). Warm fast host ≈130ms
+   click gap (passes), loaded CI emulator >250ms (always fails).
+
+**Fix (all in `src/__tests__/android/`):**
+- `reader.ts patchGlobalViewSettings(patch)` — force-stop app, read/patch
+  `settings.json` `globalViewSettings` via `adb shell run-as` (debug builds
+  only; file lives at the app data dir ROOT, not files/), write back via
+  base64 pipe, return previous values for restore in afterAll. Missing
+  settings.json is fine: `loadSettings` deep-merges partial file over defaults.
+- `cdp.ts CdpPage.doubleTap(cssX, cssY)` — ONE
+  `Input.synthesizeTapGesture {tapCount: 2, duration: 20, gestureSourceType: 'touch'}`;
+  renderer-internal timing gives ~200ms click gap on a busy emulator. TWO
+  sequential synthesizeTapGesture commands are too slow (~535ms gap — each
+  resolves long after its gesture). Raw `Input.dispatchTouchEvent` delivers
+  touch events but does NOT reliably synthesize clicks on Android WebView.
+- Word finder requires `range.getClientRects().length === 1`: a
+  hyphenated/wrapped word's bounding rect spans two lines, so its center taps
+  between lines and selects the neighboring word (saw `'party' !== 'sensation'`).
+- `dismissSelection` picks a mid-column tap spot (0.78H or 0.25H) that the
+  `.selection-popup` doesn't cover — a blind 0.78H tap can press a toolbar
+  button when the selection sits low.
+
+**Other gotchas:** headless emulator display sleeps → adb `input` no-ops while
+CDP input still works (`input keyevent KEYCODE_WAKEUP`); a leaked single-click
+(broken double-tap) toggles header or opens the media viewer, contaminating the
+session; local repro = `pnpm tauri android build --debug --target aarch64` +
+`adb install -r` + `pnpm test:android`.
+
+Related: [[android-cdp-e2e-lane]], [[iframe-double-click-word-select]]
@@ -0,0 +1,30 @@
+---
+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, "&shy;" 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).
@@ -0,0 +1,31 @@
+---
+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.
@@ -0,0 +1,27 @@
+---
+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]].
@@ -0,0 +1,26 @@
+---
+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`.
@@ -0,0 +1,14 @@
+---
+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.
@@ -0,0 +1,52 @@
+---
+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]].
@@ -0,0 +1,64 @@
+---
+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.
@@ -0,0 +1,25 @@
+---
+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]].
@@ -0,0 +1,51 @@
+---
+name: auto-scroll-teleprompter-4998
+description: "Auto Scroll teleprompter mode (#4998, PR#4999): PacedScroller core, useAutoScroll hook, control pill centered on gridcell, scrolled-mode-only View menu toggle"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 129a72a3-6d52-4f4c-a499-972c0055b4e3
+---
+
+Auto Scroll reading mode (#4998), PR #4999 MERGED 2026-07-08 (merge
+f8ad47a41); worktree and local branch cleaned up.
+Teleprompter scrolling for scrolled mode only, toggled from the View menu
+(Shift+A, `onToggleAutoScroll`), dispatches `autoscroll-toggle` events.
+
+Key structure:
+- `PacedScroller` added to `src/app/reader/utils/autoscroller.ts` alongside the
+  middle-click `Autoscroller` ([[middle-click-autoscroll-4951]]): constant
+  velocity, whole-pixel emission + fractional carry, injected raf/now for
+  tests, `PACED_SCROLL_MAX_FRAME_MS` dt clamp (background tab resume). A
+  scrollBy callback may stop() the scroller mid-tick; #tick re-checks active
+  before re-arming (test covers it).
+- `useAutoScroll(bookKey, viewRef)` in reader/hooks, mounted in FoliateViewer:
+  scrolls `renderer.containerPosition += sign * delta`; sign = -1 when
+  `renderer.scrollProp === 'scrollLeft'` (scrolled+vertical), matching foliate
+  paginator.js `offset = -offset` for scrolled vertical (vertical-lr is a known
+  upstream FIXME). Manual wheel/drag composes with the paced steps by design
+  (no pause-on-wheel). Tap pause/resume consumes `iframe-single-click` via
+  eventDispatcher.onSync (same swallow mechanism as middle-click). Stall
+  detection: containerPosition unchanged ≥800ms → `view.next()` (hops sections
+  under noContinuousScroll) or stop + 'End of book' toast when
+  `renderer.atEnd`. Session state mirrored to readerStore
+  `viewState.autoScrollEnabled` (new setter) for the ViewMenu checkmark;
+  session never persisted, speed IS: `autoScrollSpeed` percent in BookLayout
+  (default 100 = 20 px/s base, 25-500 step 25, constants in
+  services/constants.ts).
+- `AutoScrollControl` pill reuses the ParagraphBar chassis but positioned
+  `absolute` (NOT `fixed`): maintainer explicitly wants it centered on the
+  book's gridcell, not the viewport — pinned sidebar pushes the reading column
+  off window center. (ParagraphBar's #4474 comment argues the opposite for
+  paragraph mode; the two are intentionally different.) Fades after 2.5s while
+  scrolling, wakes on mousemove/pause, hidden while hoveredBookKey shows bars.
+- Adding a field to readerStore ViewState breaks two test fixtures that build
+  ViewState literals (reader-store.test.ts, tts-auto-advance.browser.test.tsx).
+- i18n: 6 new keys (Auto Scroll, Toggle Auto Scroll, Slower, Faster, Exit Auto
+  Scroll, End of book) hand-translated across all 33 locales following each
+  locale's existing Scrolled Mode / RSVP Slower-Faster terminology; scanner
+  extraction only touched trailing commas (no pruning this time).
+
+Verified live in dev-web with claude-in-chrome (localhost:3001): 20 px/s at
+100%, menu gating, pill geometry (pillCenterX == gridcell center != viewport
+center).
@@ -0,0 +1,16 @@
+---
+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]].
@@ -0,0 +1,17 @@
+---
+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).
@@ -0,0 +1,14 @@
+---
+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.
@@ -0,0 +1,48 @@
+---
+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.
@@ -0,0 +1,24 @@
+---
+name: calibre-custom-columns-4811
+description: "Surface Calibre custom columns from OPF user metadata (#4811) - parse formats, calibreColumns field, details UI, library search"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 7f74fc26-9614-4fe3-987b-66c8ce412523
+---
+
+Feature #4811 SHIPPED (app PR #4939 merged 2026-07-05 as `ec45a08`; foliate-js#47 merged as `8485e93`): surface Calibre custom columns embedded in EPUB OPFs. Worktree and branches cleaned up.
+
+**Calibre OPF encodings (verified against calibre source opf2.py/opf3.py):**
+- OPF2: one `<meta name="calibre:user_metadata:#label" content="{json}"/>` per column; label must start with `#`
+- OPF3: a single `<meta property="calibre:user_metadata">{"#label": {...}}</meta>` (raw property attr always literally `calibre:user_metadata`; the `calibre:` prefix maps to `https://calibre-ebook.com` but foliate's URL-resolution concatenates without `:` so match the RAW attr, not the resolved one). Calibre prefers OPF3 over OPF2 when both present (`read_user_metadata3 || read_user_metadata2`).
+- Value in `#value#` (array for multi-value), series index in `#extra#`; datetimes wrapped `{"__class__": "datetime.datetime", "__value__": "<ISO>"}`, unset date = `0101-01-01`; embedded files carry EVERY library column so empty values (null/''/[]/rating 0/undefined-date) must be dropped at parse time.
+
+**Where things live:**
+- Parser: `getCalibreUserMetadata` in foliate-js `epub.js`, attached AFTER `tidy()` (tidy would collapse single-element value arrays) as `metadata.calibreColumns` `[{label, name, datatype, value, extra?}]`
+- Type: `CalibreCustomColumn` in `src/libs/document.ts`; `BookMetadata.calibreColumns`
+- Formatter: `formatCalibreColumnValue` in `src/utils/book.ts` (rating → ★ half-stars /2, series → `Name [idx]`, bool → ✓/✗, comments → strip tags, datetime → formatDate)
+- UI: extra grid cells in `BookDetailView.tsx` Metadata section after Identifier (column names are user content, NOT i18n keys)
+- Search: `getCalibreColumnsText` in `src/app/library/utils/libraryUtils.ts` `createBookFilter` (both regex and substring branches)
+
+**Why safe:** metaHash dedupe uses only title/authors/identifiers; metadata editor spreads `{...metadata}` so the field survives edits; import assigns `loadedBook.metadata` as-is. Calibre plugin pushes already embed user metadata via calibre `set_metadata`, so plugin-pushed books get columns through the same OPF parse (the plugin's flat `customColumns` wire field is a DIFFERENT shape and stays unused). E2E-verified on the real sample (Elena Sabe, OPF3, 11 columns → 7 shown, search "CT1" filters). Related: [[calibre-plugin-push-4863]].
@@ -0,0 +1,23 @@
+---
+name: calibre-plugin-push-4863
+description: "readest-calibre-plugin (#4863) pushes calibre books+metadata to Readest cloud; key protocol facts (OAuth localhost relay, /sync explicit-null carry-over)"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 5d4d83a0-0aee-4200-852f-555df5243bed
+---
+
+`apps/readest-calibre-plugin/` implements #4863: calibre GUI plugin pushing selected books + metadata into the Readest cloud, modeled on BookFusion's plugin. MERGED to main via PR #4918 (2026-07-04, merge 6b403d019); packaged in releases as `Readest-<version>.calibre-plugin.zip` by release.yml's `build-calibre-plugin` job.
+
+Design decisions and hard-won protocol facts:
+- **Identity**: `Book.hash` = partial MD5 (KOReader algorithm; JS `1024 << -2` wraps to 0, so offsets are 0, 1024, 4096, ... 1024<<20). metaHash = `md5(NFC("title|authors,|ids,"))`, preferred id scheme uuid > calibre > isbn; Python impl verified byte-identical to `js-md5` output.
+- **OPF embedding + uuid dedup** (v2, per maintainer request): metadata IS embedded into a temp copy at upload (`calibre.ebooks.metadata.meta.set_metadata` — deterministic for EPUB, writes custom columns as `calibre:user_metadata`). Dedup keys: calibre uuid in row `metadata.identifier` (survives byte changes) + `metadata.calibreSourceHash` = raw library-file partialMD5 (change detection, no local state; v1 rows fall back to `book_hash` which equals the raw hash). File changed → replace flow: upload new blob, push new row (carry-over) + tombstone old in one /sync POST, best-effort delete old cloud files. Metadata-only edit → row update, no re-upload (embedded OPF goes stale until next file upload).
+- **POST /sync explicit-nulls absent fields** (transformBookToDB) — updates must carry over `uploadedAt`, `groupId/Name`, `progress`, `readingStatus*`, `coverHash` from the pulled server row (`wire.py::merge_for_push`); same lesson as koplugin syncbooks.lua.
+- **Upload key** `Readest/Books/{hash}/{hash}.{ext}`; app's `{title}.{ext}` downloads resolve via download.ts hash+extension fallback. cover.png stores *original* bytes (app never converts formats, bookService.ts:568), so calibre's cover.jpg bytes upload as-is; coverHash = partialMD5 of those bytes.
+- **OAuth from a non-app client works**: `{supabase}/auth/v1/authorize?provider=X&redirect_to=http://localhost:PORT` is whitelisted (readest-app's Flatpak/custom-OAuth production path uses it). Tokens arrive in the URL *fragment*; serve a page whose JS relays `location.hash` to `/callback?...` (tauri-plugin-oauth trick). Implemented in `oauth.py`.
+- Pure modules (`api.py`, `wire.py`, `oauth.py`) are calibre-free; `make test` runs 56 unittests; `make zip` builds; smoke-test inside calibre with `calibre-debug -c` after `from calibre.customize.ui import find_plugin` (initializes the `calibre_plugins` namespace).
+
+- **Release packaging** (PR #4918): `build-calibre-plugin` job in release.yml mirrors the koplugin job; perl-stamps `PLUGIN_VERSION` from readest-app package.json, `make zip` → `Readest-<version>.calibre-plugin.zip` release asset. Committed version stays the (0, 1, 0) dev placeholder.
+- **Pushing workflow files**: gh's OAuth token lacks `workflow` scope (HTTPS push of .github/workflows/* rejected); SSH push works (transient hangs — retry with ConnectTimeout/ServerAliveInterval).
+
+Related: [[koplugin-cover-upload]], [[grimmory-native-sync]], [[ci-pr-delivery-and-push]]
@@ -0,0 +1,43 @@
+---
+name: captured-turn-instant-highlight-scrolllock
+description: Captured slide/curl page turns ignored the instant-highlight still-hold gate; fixed by honoring renderer.scrollLocked like the push paginator
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 871c7b42-61c0-44e7-a1d6-8edb35d80300
+---
+
+Instant Highlight's 300ms still-hold gate ([[instant-highlight-tap-paginate]])
+worked in **push** mode but NOT in **slide/curl** — a swipe after the hold turned
+the page (with the slide/curl effect) instead of extending the highlight.
+
+**Root cause: two independent swipe paths.** foliate's native `#onTouchMove`
+(paginator.js) bows out at `if (this.hasAttribute('no-swipe')) return` (~2149),
+THEN checks `if (this.#scrollLocked) return` (~2162), THEN the `#layeredTurn` VT
+drag (~2179). So:
+- **push** (no turn-style, no no-swipe) → native swipe, honors `#scrollLocked`. ✅
+- **VT-layered slide** (`turn-style='slide'`, no no-swipe; engines with nested VT
+  groups) → native swipe → layered turn, still AFTER the scrollLocked check. ✅
+- **captured curl (always) / captured slide (Tauri w/o full VT support)** →
+  `applyPageTurnAttributes` sets `no-swipe`, so native swipe returns early and the
+  APP-side captured-turn touch interceptor in `useCapturedTurn.ts` (priority 5,
+  driven by `iframe-touchmove` → `dispatchTouchInterceptors`) is the swipe handler.
+  It began a drag on any >15px horizontal move WITHOUT checking scrollLocked. ❌
+
+`useTextSelector.startInstantAnnotating` sets `view.renderer.scrollLocked = true`
+when the hold engages. The captured interceptor is a parallel reimplementation of
+swipe-to-turn and must honor the same lock independently.
+
+**Fix (app PR readest#5000 + foliate readest/foliate-js#51, tests:
+`useCapturedTurn-scrollLock.test.ts`):**
+1. foliate `paginator.js`: add `get scrollLocked()` — it was setter-only, so JS
+   couldn't read it back (app `src/types/view.ts` already declared it a readable
+   boolean). foliate PR #51 MERGED (squash → `ba57ec8` on foliate main); app
+   #5000 bumps the submodule pointer to `ba57ec8` (mergeable, awaiting merge).
+2. `useCapturedTurn.ts` touch interceptor, `move` phase, before starting a drag
+   (`!state` branch): `if (currentView.renderer.scrollLocked) return false;`.
+
+**Why the `!state` branch is sufficient:** a captured drag needs >15px horizontal
+travel, but `maybeCancelInstantHoldOnMove` cancels the hold at >10px — so a drag
+can never already be in progress when instant annotation engages; no need to gate
+an in-flight drag. See [[page-turn-styles-viewtransitions-555]].
@@ -0,0 +1,20 @@
+---
+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.
@@ -0,0 +1,26 @@
+---
+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]].
@@ -0,0 +1,32 @@
+---
+name: cloud-sync-provider-selection-plan
+description: "APPROVED /autoplan-reviewed plan making third-party sync (WebDAV/Drive) a first-class selectable provider; quota scoped to Readest Cloud (#4959/#4380)"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: c0549d91-7f40-46a8-b110-628964be195b
+---
+
+Plan APPROVED 2026-07-06 after full /autoplan review (CEO+Design+Eng dual voices, 43 logged decisions). Plan file: `~/.claude/plans/research-on-https-github-com-readest-rea-velvet-meteor.md` (contains registries, UI state matrix, eng hardening, coverage diagram, 26 tasks). CEO doc: `~/.gstack/projects/unknown/ceo-plans/2026-07-06-cloud-sync-provider-selection.md`.
+
+**Architecture:** policy layer over TWO engines (native DB-sync + FileSyncEngine) — Readest Cloud is NOT wrapped in FileSyncProvider (would regress server merges #4634/#4544/#4678). New `src/services/sync/cloudSyncProvider.ts`: pure `getCloudSyncProvider(settings)` derived from `webdav/googleDrive.enabled` (device-local) + separate `resolveCloudSyncGate(settings, plan)` w/ cached plan accessor (isCloudSyncAllowed needs async JWT — can't be settings-pure). Guard trips → PAUSED state + prompt, never silent readest fallback. Native gating = one branch in `syncCategories.isSyncCategoryEnabled` (book/progress/note); binary gating = `transferManager.queueUpload` returns null. Account channels (settings/stats/replicas/translations/Send) always native.
+
+**Sequence (user-ruled at gate):** PR1 quota decouple (#4959 hotfix: gate + quota-403 no-retry + BATCH toast dedupe — spam is N-books×1-toast after retries, verified transferManager.ts:376/395) → PR1.5 file-engine parity (tags+readingStatus in mergeBookConfig/mergeBookMetadata+wire, BEFORE gating) → PR2 exclusive gating + mixed-fleet detection → PR3 chooser UI.
+
+**Gate rulings:** UC3 = `syncBooks` AUTO-ENABLES on third-party selection (closes books-backed-up-nowhere hole; opt-out shows warning). UC1 = derived/device-local kept + read-only `/api/sync?since=providerSelectedAt&limit=1` probe → one-time "another device still syncs" banner + Sentry provider tag. UC2 = parity before gating. Switch-back = new-imports-only auto-upload (NO 675-book burst); metadata rows DO re-push (intended).
+
+**PR1 IMPLEMENTED (2026-07-06):** commit `f6e5d7740` on branch `fix/cloud-sync-quota-decouple` (worktree `/Users/chrox/dev/readest-fix-cloud-sync-quota-decouple`), 22 files, LOCAL ONLY (not pushed, per confirm-before-push). Full suite 6900 pass + lint clean; new suites: `cloudSyncProvider.test.ts` (18), `transfer-manager-gating.test.ts` (19). i18n extraction deliberately SKIPPED in this PR (scanner pruned ~1350 live translations, e.g. "Read Aloud" — run the dedicated /i18n pass later; new strings fall back to English keys). Deviations from plan, all sound: paused toast centralized in `handleBookUpload` (both manual surfaces route through it); useTransferQueue default-param hazard fixed by the manager-level settings barrier instead of signature churn; migration passes the settings snapshot into `runMigrations(lastVersion, settings)` and mutates in place because `Settings.loadSettings` re-reads disk (subclass post-save would clobber an independent save). **SERIES FULLY MERGED (2026-07-07): #4971 (PR1 quota) + #4973 (PR1.5 parity) + #4975 (PR2 exclusive routing, closes #4380) + #4976 (PR3 chooser UI).** Worktrees removed, local branches deleted. **LIVE-VERIFY BUG FOUND+FIXED = #4981 OPEN** (`3a0af54dd`, fix/file-sync-auth-abort): expired Drive web token → engine swallowed AUTH_FAILED on index pull → remoteIndex=null read as FIRST SYNC → attempted 682-book re-upload march; latent hazard: null index skips the peers-tombstone union in the final re-push (#4860 class — transient pull failure could resurrect deletions). Fix: unreadable index (throw) aborts (404→null stays first-sync); terminal AUTH_FAILED latch stops runPool + skips index push + rethrows; web auto-sync preflights hasValidWebDriveToken. KEY ENGINE INVARIANT going forward: FileSyncError AUTH_FAILED is terminal — rethrow, never aggregate.
+
+**i18n PASS = #4980 OPEN** (`237953cc2`, fix/cloud-sync-i18n, worktree `readest-fix-cloud-sync-i18n`): 22 strings x 33 locales + CLDR plural forms + en `_one`/`_other`, appended WITHOUT the scanner (removeUnusedKeys would prune live keys), additions-only diff. REMAINING: live verification checklist (real WebDAV 192.168.2.3:6065: exclusive e2e, syncBooks auto-enable on connect, fleet banner, switch-back no-burst, two-window switch), TODOS.md follow-ups (Sentry Rust tag, server quota error code, download-all-before-switch, library sync indicator, account chip, stats/viewSettings parity, Manage-Sync binary-gating mismatch). Note: GitHub reports 5 dependabot vulns on default branch (1 high) — pre-existing.
+
+**PR3 contents:** activation moved to `src/services/sync/cloudSyncActivation.ts` (accepts 'readest'; component cloudSync.ts is a re-export shim); pure status matrix `cloudSyncStatus.ts` (getReadestCloudRowStatus/getThirdPartyRowStatus, fully tested — paused renders on the THIRD-PARTY row, not Readest row as plan sketch had it); Cloud Sync section (Readest-first radio rows, scope subtitle, role=radiogroup); Readest Cloud inline sub-page (Quota + NavigationRow to Account, never navigateToProfile from the row); premium branch keeps Readest row; capability Tips both directions in webdav/gdrive sub-pages; FileSyncForm Upload Book Files relabel; SyncCategoriesSection 'Managed by {{provider}}' description swap (toggles stay live).
+
+**REMAINING (user/ops):** push 2 branch stacks + open PRs (PR1.5 independent; PR2/3 stacked on PR1); dedicated /i18n pass for ~20 new strings (extraction pruning hazard — run /i18n which handles it); live verification per plan (real WebDAV 192.168.2.3:6065: exclusive mode e2e, syncBooks auto-enable, fleet banner, switch-back no-burst); TODOS.md follow-ups (Sentry Rust tag, quota error code, etc.). Discard uncommitted TODOS.md duplicate in main checkout.
+
+**PR2 IMPLEMENTED (2026-07-06):** commit `95fd33f0a` on `feat/cloud-sync-exclusive-gating`, STACKED on PR1 in the same worktree (`/Users/chrox/dev/readest-fix-cloud-sync-quota-decouple`), 27 files +869/-99, LOCAL ONLY. Full suite 6923 pass + lint clean. Contents: syncCategories provider gate (book/progress/note, runtime override, user toggles persist); `persistActiveCloudProvider` single write path (chooser + both connect/disconnect flows + gdrive OAuth callback which had bypassed broadcast); minimal switch-only broadcast (`{enabled, providerSelectedAt}` — never credentials/cursors); **found+fixed PR1 integration bug: buildWebDAVConnectSettings pre-set `enabled:true` so fresh-connect never triggered the syncBooks auto-flip — builder is now activation-agnostic**; fileSyncStore `lastError` + `fleetNoticeShown`; `runActiveFileLibrarySync()` shared runner (menu tap + pull-to-refresh + BackupWindow all route via pullLibrary's provider branch — fixes "undefined book(s) synced"); SettingsMenu "Synced via {{provider}}" + quota caption + Auto-Upload hidden (also command palette `action.autoUpload` filtered, BookItem badge, TransferQueuePanel Upload All); mixed-fleet read-only probe (`pullChanges(providerSelectedAt,'books',...,1)` in useBooksSync's throttled interval, once-per-session toast); `providerSelectedAt` in both provider types + backup blacklist. Sentry cloudSyncProvider tag DEFERRED to TODOS (tagging is Rust-mediated via set_webview_info pattern — needs src-tauri command).
+
+**PR1.5 IMPLEMENTED (2026-07-06):** commit `f19fc6fa1` on `feat/file-sync-metadata-parity` (worktree `/Users/chrox/dev/readest-feat-file-sync-metadata-parity`, branched off origin/main independent of PR1), 4 files +253/-26, LOCAL ONLY. Full suite 6869 pass + lint clean. KEY FINDING: library.json already serializes FULL Book objects — tags/readingStatus were on the wire all along; the drop was `mergeBookMetadata`'s overlay (same gap as #4942 groups) + the reconcile predicate not firing on status-only changes. Fix: tags join the metadata LWW subset (raw assignment, removals propagate); readingStatus merges on its own `readingStatusUpdatedAt` clock (client mirror of #4634); new `shouldApplyRemoteBookMetadata` predicate (either clock) replaces `isRemoteBookMetadataNewer` in the engine reconcile filter (the old predicate stays exported). NO wire changes needed. PR2 stacks on PR1 (needs cloudSyncProvider.ts) — merge PR1 first or stack branches.
+
+**Key traps found in review:** `BACKUP_SETTINGS_BLACKLIST` does NOT exclude enabled flags/webdav.deviceId (plan text was wrong; PR1 adds deviceId/lastSyncedAt to blacklist); settings broadcast must carry ONLY `{enabled}` (password would leak; routine lastSyncedAt writes could revert a switch via slice LWW); Drive OAuth callback writes via appService.saveSettings bypassing broadcast → centralize `activateCloudProvider()`; `useTransferQueue()` DEFAULT params (`libraryLoaded=true`) in SettingsMenu/TransferQueuePanel are the real unguarded init path (barrier = `settings.version`); cancelled needs structured `cancelReason` + queue schemaVersion (`retryAllFailed` resurrects cancelled rows today; failed-includes-cancelled copy-pasted in 5 places); fileSyncStore is process-local — durable lastSyncedAt lives in provider settings.
+
+See [[webdav-filesync-refactor-plan]] · [[gdrive-provider-multipr-status]].
@@ -0,0 +1,47 @@
+---
+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.
@@ -0,0 +1,20 @@
+---
+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]].
@@ -0,0 +1,57 @@
+---
+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).
@@ -0,0 +1,27 @@
+---
+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.)
@@ -0,0 +1,14 @@
+---
+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]].
@@ -0,0 +1,48 @@
+---
+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.
@@ -0,0 +1,73 @@
+---
+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).
@@ -0,0 +1,47 @@
+---
+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]].
@@ -0,0 +1,21 @@
+---
+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]].
@@ -0,0 +1,24 @@
+---
+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]].
@@ -0,0 +1,45 @@
+---
+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).
@@ -0,0 +1,45 @@
+---
+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).
@@ -0,0 +1,22 @@
+---
+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]].
@@ -0,0 +1,17 @@
+---
+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]].
@@ -0,0 +1,45 @@
+---
+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]].
@@ -0,0 +1,46 @@
+---
+name: dict-popup-tts-speak-4876
+description: "Dictionary popup speaker button pronounces the headword via Edge TTS (#4876), with a standalone pronouncer that bypasses TTSController"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 98d0ef1c-84c2-4a16-85a0-0abad0010923
+---
+
+Issue #4876: add a "speak" button to the dictionary popup so a looked-up word
+can be pronounced. Implemented on branch `feat/dict-popup-tts` (commit
+f2acafb4b, 2026-07-06). Button-only (no auto-speak); speaker icon sits inline
+left of the headword in the shared `DictionaryResultsHeader`, so it covers both
+the desktop `DictionaryPopup` and mobile `DictionarySheet`.
+
+Key file: `src/services/tts/wordPronouncer.ts` — a standalone single-word
+pronouncer, deliberately independent of the reader's `TTSController`:
+- **Speak ASAP**: never calls `EdgeTTSClient.init()` (which wastes a round trip
+  synthesizing "test"). Calls `EdgeSpeechTTS.createAudioData()` directly; its
+  static LRU MP3 cache makes repeat words instant.
+- **Dedicated Web Audio context** (`new WebAudioPlayer(() => new AudioContext())`,
+  NOT the module-shared context the reader uses) so pronouncing a word can never
+  resume/suspend or overlap an active read-aloud session. One extra AudioContext,
+  fine under WebKit's ~4 cap.
+- **Gesture warmup**: `warmWordAudio()` must be called synchronously in the click
+  handler (the hook's `speakWord` does this) because `pronounceWord` resumes the
+  context only after a network await, outside WebKit's autoplay gesture window.
+- **Engine order**: Edge wss -> Edge https proxy (`fetchWithAuth`, throws "Not
+  authenticated" when logged out) -> platform fallback. Fallback reuses the
+  existing `WebSpeechClient` (desktop/web) / `NativeTTSClient` (mobile app)
+  standalone via `genSSMLRaw(word)` + `setPrimaryLang(lang)`; the SSML default
+  `xml:lang="en"` is overridden by `parseSSMLMarks(ssml, primaryLang)`.
+- `requestToken` guards staleness so a superseded in-flight synth bails.
+
+Hook: `useDictionaryResults` gained `isSpeaking` + `speakWord`; cancels on word
+change / unmount. Voice pick = `TTSUtils.getPreferredVoice('edge-tts', lang)`
+then first `isSameLang` match then `en-US-AriaNeural`.
+
+Tests: `src/__tests__/services/tts/wordPronouncer.test.ts` (Edge-first / fallback
+contract; jsdom has no AudioContext so `getPlayer()` returns null unless
+`globalThis.AudioContext` is stubbed + `WebAudioPlayer` mocked). Speak-button
+wiring test added to `DictionarySheet.test.tsx` (mocks the pronouncer module).
+
+NOT verified live: real audio playback + iOS gesture warmup (not unit-testable).
+Related: [[edge-tts-webaudio-engine]] (the WebAudio refactor that replaced the old
+blob-URL `createAudio` with `createAudioData`), [[ios-instant-dict-double-popup]].
@@ -0,0 +1,22 @@
+---
+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`.
@@ -0,0 +1,21 @@
+---
+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]].
@@ -0,0 +1,26 @@
+---
+name: edge-tts-webaudio-engine
+description: "Edge TTS Web Audio refactor (#3851/#2033) — gapless engine, WSOLA rate, section timeline + scrubber; branch feat/edge-tts-webaudio; release gates and design invariants"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 97e57af9-5961-4c92-a63e-4582178bf798
+---
+
+Branch `feat/edge-tts-webaudio` (worktree `/Users/chrox/dev/readest-feat-edge-tts-webaudio`, built 2026-07-04, NOT pushed) replaces Edge TTS per-sentence `<audio>` playback with a Web Audio pipeline: fetch MP3 at rate 1.0 (unchanged LRU + new in-flight dedup in `edgeTTS.ts`) → decode → `pcm.ts` silence trim → `timeStretch.ts` in-house WSOLA (pitch-preserved client rate, cache never refetches on rate change) → `WebAudioPlayer.ts` gapless scheduling. `SectionTimeline.ts` (measured > per-voice cps EMA in localStorage `readest-tts-voice-cps` > script defaults) powers a TTSPanel scrubber + media-session position/seekto. foliate-js fork branch `feat/tts-get-sentences` adds `getSentences` — fork PR must merge BEFORE the readest PR (submodule pin).
+
+**Why:** #3851 first-word clipping cause is a HYPOTHESIS (Android reporter reproduced with BT off); treat as falsifiable experiment. #2033 gaps = element restarts + ~300ms Edge trailing silence.
+
+**Load-bearing invariants (don't regress):**
+- AudioContext is a module-level singleton, never closed — a fresh TTSController per tts-speak calls `stop()` not `shutdown()`, and WebKit caps ~4 live contexts (leak = permanent silence).
+- Marks dispatch at AUDIBLE time (player chunk-start via onended, background-safe), never at fetch — else foliate's `#lastMark` runs ahead and prev/next/resume break.
+- `endSession` fires session-end synchronously when nothing is unfinished — zero-chunk sessions (Edge outage) must not wedge controls in "playing".
+- `ensureSharedAudioContext()` is called in the tts-speak gesture path BEFORE any await (WebKit autoplay window); `unblockAudio` silent element runs on ALL platforms (desktop Chromium media keys need a playing HTMLMediaElement).
+- `abortSession` never suspends the context (warm output stream IS the #3851 fix); only user pause suspends.
+- Word boundaries stay in original untrimmed media time; `getChunkPosition()` returns trim-relative clamped seconds; timeline sums TRIMMED durations.
+- Inter-sentence CLICKS/POPS = the silence trim (`findSpeechBounds`) cuts at an amplitude threshold (0.005), NOT a zero crossing, so each buffer edge is a non-zero sample; the source steps to/from silence → click. NOT WSOLA (no-op at rate 1.0, cross-fades internal splices). Fix (commit a8643ec12, branch fix/android-bg-tts-media-session): `applyEdgeFade` in `pcm.ts` ramps ~3ms at both ends of the buffer's OWN copy (`buffer.getChannelData(0)` after `createMonoBuffer`) — never the `trimmed` subarray view (rate 1.0 aliases the decoded buffer). Trim + gap kept. Removing the trim instead would work (WSOLA DOES scale silence, so gaps stay rate-scaled) but doubles each gap to Edge's tail+lead silence.
+- `POPUP_HEIGHT` in TTSControl.tsx is fixed and non-scrolling — grows to 200 only when a timeline-capable client is active.
+
+**Follow-up decided (2026-07-04, not yet planned): background TTS decoupling.** App-level TTSSessionManager owns the controller; reader hook becomes attach/detach. Matrix chrox chose: close book = keep playing (headless via `section.createDocument()`); reopen SAME book = seamless reattach (adopt session + `redispatchPosition()` + CFI re-anchoring — the highlighter already re-anchors ranges through CFIs, so cross-doc ranges are safe; swap text supply to rendered doc lazily at next section boundary); open a DIFFERENT book = TTS STOPS (not "keeps playing while browsing"); explicit stop / sleep timer = stops. Fiddly bit: `getCFI` without a rendered view. Recorded in branch TODOS.md.
+
+**How to apply:** Release gates before closing the issues (in plan Verification): WSOLA A/B listening test 0.2x-3x EN+CJK, Linux WebKitGTK decode (GStreamer), reporter-hardware beta (Soundcore Q20i iOS / Galaxy S22U screen-off), iOS lock-screen + interruption QA, e-ink `[data-eink] .range` fill check (NO eink range rule exists in globals.css), RTL slider direction. Plan + 35-decision audit trail: worktree `.agents/plans/2026-07-03-edge-tts-webaudio.md` (gitignored, local). i18n keys added ('This chapter', 'Chapter progress', 'Failed to seek', '{{elapsed}} of {{total}}') need the /i18n pass. Deferred follow-ups in TODOS.md incl. provider-agnostic local-TTS hedge ([[grimmory-native-sync]] unrelated).
@@ -0,0 +1,23 @@
+---
+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]]
@@ -0,0 +1,30 @@
+---
+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.
@@ -0,0 +1,46 @@
+---
+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]].
@@ -0,0 +1,30 @@
+# EPUB review editor migration
+
+Date: 2026-07-08
+
+This fork includes a desktop migration of the Chinese/Japanese EPUB review editor into Readest.
+
+Current shape:
+- Bundled sidecar lives at `apps/readest-app/tools/epub-review-editor`.
+- Readest route is `/review-editor`.
+- Library menu entry is `Settings Menu -> Advanced Settings -> EPUB 审校器`.
+- Dev launcher API is `POST /api/review-editor/launch`.
+- Desktop launcher command is `launch_epub_review_editor`.
+- Dev script is `pnpm epub-reviewer:dev`.
+- Default runtime data is `apps/readest-app/epub_review_sessions/`; it is ignored by git. Override with `READEST_REVIEW_ROOT`.
+- The automatic launcher now works in Tauri desktop through the Rust command and keeps local `dev-web` as a fallback.
+- `/review-editor` is the desktop feature-block page for both 校对 and 翻译. It now uses native React blocks as the main work surface and calls the local sidecar APIs directly.
+- Readest EPUB bookshelf context menus can open the reviewer in 校对 or 翻译 mode. The native file path is handed to the Tauri command, which creates/reuses a sidecar session and returns `sessionId`; the Readest page should use `session_id`, not keep `epub_path` in the URL.
+- The old `static/index.html` UI remains bundled only as standalone/debug fallback. Do not treat an iframe of the old UI as the desktop migration acceptance path.
+
+Important boundary:
+- This is not a full native rewrite yet. The migrated tool still uses the proven Flask backend from the previous long-term translation project.
+- The production desktop path still depends on local Python/venv/pip as a temporary sidecar runtime. Next step should package a controlled runtime or convert the hot APIs to native Rust/Tauri commands.
+- Do not remove existing review-editor behavior while migrating: bookshelf, upload, bilingual review, glossary editing, GPT retranslate, full-book AI translation, soft delete, duplicate translation layer prevention, ruby preservation.
+- If `/review-editor` shows `ERR_BLOCKED_BY_RESPONSE`, check both sides of cross-origin isolation: the Readest route keeps COEP `require-corp`, and the sidecar response should include local `frame-ancestors`, `Cross-Origin-Embedder-Policy: require-corp`, and `Cross-Origin-Resource-Policy: cross-origin`.
+- If React blocks cannot fetch the sidecar, check restricted CORS in `server.py`; allowed origins are local Readest dev and Tauri origins only.
+
+Next recommended steps:
+1. Package the Python sidecar/runtime or replace it with native Tauri commands so desktop users do not need a system Python installation.
+2. Add a launch token / origin guard for the loopback sidecar API before wider distribution.
+3. Gradually port long-tail review-editor surfaces into React: glossary editing, full bookshelf classification UI, richer chapter navigation, and reading-position restore.
@@ -0,0 +1,18 @@
+---
+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`).
@@ -0,0 +1,14 @@
+---
+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".
@@ -0,0 +1,40 @@
+---
+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.
@@ -0,0 +1,20 @@
+---
+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`).
@@ -0,0 +1,37 @@
+---
+name: fxl-portrait-autospread-offcenter-4984
+description: PDF/FXL auto-spread in portrait rendered the lone page off-center and made taps turn pages
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: f24a5890-de13-4767-bb33-97621f332e44
+---
+
+Issue #4984: in fixed-layout (PDF) `spread='auto'` + portrait viewport, the page
+was shoved into one half of the screen ("weirdly separate") and almost every tap
+turned the page instead of opening the menu.
+
+Root cause (verified in Chrome): `FixedLayout.#render` in
+`packages/foliate-js/fixed-layout.js` already hides the non-target page in
+portrait (`if (portrait && frame !== target) display:none`) and scales the shown
+page as a single page, BUT it kept the spread-centering one-sided inline margin —
+left page `marginInlineStart:auto`, right page `marginInlineEnd:auto`. With no
+partner page to meet at the spine, that auto margin stranded the lone page in one
+half of the viewport whenever it was narrower than the viewport (any zoom < 100%,
+e.g. the issue's 50% zoom; or a page whose fit-scaled width < viewport width).
+The off-center page then sat over a page-turn tap zone (tap zones are
+view-relative: center 0.375-0.625 = menu, else turn — see `usePagination.ts`), so
+taps turned the page. Symptom 2 was a consequence of symptom 1.
+
+Fix MERGED (readest PR#4992 + foliate-js PR#50 squash -> foliate main f6dced2, readest submodule bumped to it): added pure `computeSpreadInlineMargins(portrait)`; in portrait
+both inline margins are `auto` (centered), in landscape one-sided (pages meet at
+spine). It sets BOTH margins explicitly (opposite side cleared to '') because
+frames are re-styled in place on rotation (ResizeObserver -> `#render`, no
+`#respread`), so a stale `auto` would otherwise linger. NOT fixed by forcing
+`spread='none'` in portrait — that duplicates the existing portrait-single-page
+path, needs app-layer orientation swapping + `#respread` (cache clear + re-nav),
+and overrides the user's chosen setting.
+
+Test: `src/__tests__/document/fixed-layout-portrait-single-page.test.ts`. Related:
+[[fxl-spread-spine-seam-4857]] shares this render branch;
+[[pdf-text-selection-fontscale-4480]].
@@ -0,0 +1,29 @@
+---
+name: gdrive-fullwalk-every-sync-no-source-cursor
+description: Google Drive file sync re-probes all 646 books every run (focus/Sync Now) because uploadedHashes never records no-source books; plus supabase focus events re-fire pullLibrary
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 894e0d6d-ce01-402b-8f2d-0f0670986a88
+---
+
+Diagnosed 2026-07-07 (web dev, valid Drive session). "Uploading N / 646" on every tab refocus and every Sync Now = full per-book Drive probe sweep (`files?q=name='<title>.epub' and '<hashdir>' in parents`, ~1 req/book), no actual byte re-upload.
+
+Two compounding causes:
+
+1. **File cursor never records books absent from this device.** #4856's `uploadedHashes` in library.json is only added on `uploaded` or `remote-matches` (needs local bytes for size compare) in `FileSyncEngine.syncLibrary` push loop (engine.ts ~line 806-815). On web, non-downloaded books → `loadBookFile` null → `no-source` → NOT recorded even though the HEAD probe already proved the remote file exists. So `needsFilePush` stays true for all 646 forever → O(library) every run. Toggle test: Upload Book Files off → 15 reqs (config cursor `isLocalNewer` works); on → 646.
+   Fix v1 (record remote-present no-source books, commit 900af1df1 on dev) proved INSUFFICIENT: Drive API inspection showed 654/690 hash dirs hold only cover.png+config.json, NO book file (only 36 files ever uploaded) — so there was nothing to record and the probe storm persisted.
+   Fix v2 (the real fix, on dev 2026-07-07, initially uncommitted): reorder `pushBookFile` to resolve the LOCAL source before any remote probe (`probeRemoteHead` closure, lazy); `no-source` now costs zero requests and the `remoteExists` plumbing from v1 was removed again. Test: 'spends no remote request on a no-source book' in engine-sync-paths.test.ts. The 654 books stay in booksToPush (progress counter still shows them) but the sweep is network-free. Their files land on Drive only when a device that HAS the bytes (desktop) syncs with Upload Book Files on; that device records the hashes and everyone skips thereafter.
+   Worktree was discarded per user; work continues directly on the bare repo dev branch (dev server localhost:3000 runs from there).
+
+Round 5 (dev, uncommitted): Tauri plugin:fs|exists storm (5726 IPC/sync) killed by making the LIBRARY ROW the ground truth for local file presence in `needsFilePush`: gate `hasLocalFile(b) = !!(b.downloadedAt || b.filePath)` (import/download/delete all stamp downloadedAt; mergeBookMetadata keeps it device-local, verified) + session-scoped `noSourceVerdicts` WeakMap (provider-keyed, updatedAt-keyed) that suppresses re-probes of DRIFTED rows (row claims file, fs disagrees). Per user decision: NO automatic row-correction — Full Sync is the single split-brain healer (bypasses gate + memo + uploadedHashes and audits the real fs). Incremental sync with clean state = zero local and zero remote per-book probes. Harness in engine-sync-paths.test.ts: row-gate test, drifted-row memo tests, fullSync bypass; #4856 fixtures stamped downloadedAt.
+
+Round 4 (dev, uncommitted): per-book cloud buttons (Book Details + bookshelf + open-non-local-book) route to the selected provider instead of the gated Readest Cloud queue ("Uploads to Readest Cloud are paused..." toast). `FileSyncEngine.downloadBookFile` (hash-dir listing resolves filename; stream on Tauri, buffered on web; cover+config best-effort) + `runActiveFileBookUpload/Download` in runLibrarySync.ts (stamps downloadedAt; caller persists via updateBook + toasts, existing transferMessages i18n keys). Reader hint parity same day: `remoteProgressApplied` in useFileSync dispatches 'Reading Progress Synced' hint on applied remote position. NOT done: provider path has no transfer-queue/progress UI; uploadedAt not stamped (means Readest-Cloud backup; provider uploaded-state could later key off index uploadedHashes).
+
+Round 2 optimizations (dev, uncommitted as of 2026-07-07 03:10): provider memoized per connection key in `createFileSyncProvider` (warm Drive idCache across reader hook / library auto-sync / Sync Now; `resetFileSyncProviderCache()` called on Drive connect/disconnect); `writeBinary` PATCHes cached id without files.list lookup (404 evict+fallback); dev-only request diagnostics `[gdrive] op ...` / `[gdrive] #n ...` in GoogleDriveProvider.
+Remaining per-run budget after round 2 (no-change run ~11 req, ~550 kB): index GET 269 kB + index PATCH 269 kB every run; books/ listing 40 kB; ~8 file-less orphan hash dirs (in neither index nor library) re-listed by discovery every run.
+Round 3 (dev, uncommitted, all TDD in engine-sync-paths.test.ts): (1) etag short-circuit — `remoteIndexCache` WeakMap keyed on the memoized provider in engine.ts; head(library.json) etag (Drive md5/WebDAV ETag) vs cached → reuse structuredClone'd index, skip GET + ENTIRE discovery scan (peer changes always rewrite library.json; legacy no-index uploads still found on session-first run + fullSync); cache dropped after own push. (2) no-op push skip — `indexDirty` check (syncedHashes/failures/uploadedHashes-set/emptyDirs-set/any local row absent-or-newer-or-tombstone-mismatched vs remote index); skipping also keeps peers' etags stable (a restamped copy would defeat fleet-wide change detection). (3) `emptyDirs` optional index field (wire.ts) — file-less candidate dirs recorded once, skipped by discovery unless uploadedHashes says the file arrived or fullSync; pruned only against a listing that ran. Idle run = 1 stat request; local-change run = stat + config pull/push + index PATCH (no GET, no discovery). engine-deletion-sync 'preserves remote tombstone' test updated to force a dirty run.
+
+2. **Every tab focus re-runs the library file sync.** supabase-js emits SIGNED_IN/TOKEN_REFRESHED on visibilitychange; `AuthContext.syncSession` does `setUser(newObject)` each time → `pullLibrary` (deps include `user`) recreated → `useBooksSync` effect `[user, useSyncInited, libraryLoaded, pullLibrary]` refires → `runActiveFileLibrarySync` (third-party provider path). Fix would be: key on `user?.id` / latch the initial pull. User decided 2026-07-07 to LEAVE THIS AS IS ("sync on focus is fine now that runs are O(changed)") — only cause 1 was fixed.
+
+Related: #4981 fixed the adjacent expired-token variant (aborting instead of marching with remoteIndex=null). Web Drive token is sessionStorage-scoped (tab-local, no refresh). See [[cloud-sync-provider-selection-plan]], [[webdav-filesync-refactor-plan]].
@@ -0,0 +1,82 @@
+---
+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).
@@ -0,0 +1,42 @@
+---
+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).
@@ -0,0 +1,19 @@
+---
+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.
@@ -0,0 +1,26 @@
+---
+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.
@@ -0,0 +1,21 @@
+---
+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.
@@ -0,0 +1,36 @@
+---
+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]].
@@ -0,0 +1,25 @@
+---
+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]].
@@ -0,0 +1,51 @@
+---
+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]].
@@ -0,0 +1,16 @@
+---
+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]].
@@ -0,0 +1,18 @@
+---
+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]].
@@ -0,0 +1,18 @@
+---
+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]].
@@ -0,0 +1,50 @@
+---
+name: instant-highlight-delete-orphan-4773
+description: Deleting a just-made highlight leaves the overlay drawn (gone only after reopen); a stale memoized annotationIndex re-draws it
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 3a58d242-3867-414c-869a-95a23714b361
+---
+
+#4773 (Android, instant highlight): highlight a word, delete it "within a very
+short time" → the mark stays painted on the page, vanishing only after reopening
+the book. Booknote IS soft-deleted (`deletedAt` set, gone on reopen) but the
+**overlay was re-drawn after removal** → orphan.
+
+**Root cause — stale memoized index re-draws a deleted annotation.**
+`Annotator.tsx` re-applies per-location annotations on every relocate via the
+memoized `annotationIndex` (`useMemo(buildAnnotationIndex(config.booknotes), [config.booknotes])`)
+→ `selectLocationAnnotations(index, location)` → `view.addAnnotation(a)`.
+`buildAnnotationIndex` filters `deletedAt` at BUILD time, but
+`selectLocationAnnotations` trusted that and did NOT re-check. The delete
+(`handleHighlight(false)`) stamps `existing.deletedAt = Date.now()` **in place**
+on the same booknote object that's still sitting in the index bucket, and
+removes the overlay (`addAnnotation(existing, true)`). If the re-apply effect
+scheduled from the popup-open render flushes AFTER the delete (the "very short
+time" window — passive effects deferred on Android WebView under rapid taps),
+`selectLocationAnnotations` returns the now-deleted object from the pre-deletion
+snapshot and `addAnnotation` re-draws it → overlay orphaned. Annotator does NOT
+re-render on booknote changes (subscribes only to the stable `getConfig` fn), so
+the memo stays stale until some other state change recomputes it.
+
+NOT instant-specific in the data layer — instant highlight (`useInstantAnnotation`)
+just makes it easy to hit (no popup friction, fast gesture). Delete + re-apply
+(where the fix lives) is shared with normal highlights. `onCreateOverlay` reads
+`getConfig` FRESH so it's safe; FoliateViewer onLoad re-draw only fires on
+section load (not a quick delete).
+
+**Fix:** re-check `deletedAt` at the READ site, not just at index build:
+- `selectLocationAnnotations` (annotationIndex.ts): `if (item.deletedAt) continue;`
+  before classifying — covers both the annotations and notes lists.
+- The sibling `annotationIndex.globals` loop in the Annotator re-apply effect:
+  `if (annotation.deletedAt) continue;` before `expandAllRenderedSections` (same
+  stale-snapshot hazard for global highlights).
+
+Test: `src/__tests__/utils/annotation-index.test.ts` — build index with a styled
+note, then `highlight.deletedAt = 123` in place, assert `selectLocationAnnotations`
+returns `{ annotations: [], notes: [] }` (red before fix). Verified on Xiaomi 13
+Pro (fuxi, WebView) via the CDP lane: real create→delete→immediate-relocate over
+4 iterations left overlay count 6→7→6 each time (no orphan); overlay-count metric
+proven non-blind by a stray-overlay sanity probe. See [[android-cdp-e2e-lane]].
+Related: [[instant-highlight-tap-paginate]], [[global-annotation-pageturn-perf-4575]].
@@ -0,0 +1,43 @@
+---
+name: instant-highlight-tap-paginate
+description: Instant Highlight quick action swallowed tap/swipe-to-paginate on Android; fixed with a 300ms still-hold gate
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: d92c120f-6272-4366-92b8-e2d8f32dfd52
+---
+
+After the 2026-06-19 update, Android users reported tap-to-paginate failing in
+paginated mode: tapping TEXT didn't turn the page, only tapping the empty side
+MARGINS worked. Trigger = **Instant Highlight** quick action enabled (3rd toolbar
+icon / highlighter; setting = `enableAnnotationQuickActions && annotationQuickAction === 'highlight'`).
+
+**Root cause:** `useTextSelector.handlePointerDown` called `ev.preventDefault()` +
+`startInstantAnnotating()` on EVERY pointer-down over selectable text. The
+`preventDefault` suppressed the native click that drives tap-to-paginate (iframe
+`handleClick` → `iframe-single-click` → usePagination). Margins worked only because
+`handleInstantAnnotationPointerDown`→`isSelectableContent` returns false there.
+The synthetic-mousedown fallback in `handlePointerUp` is dead on Android because the
+native-touch `touchend` calls `handlePointerUp(doc, index)` with NO `ev` (Annotator.tsx
+`handleNativeTouch`), and `if (isInstantAnnotating.current && ev)` skips.
+
+**Fix (PR/commit on `dev`):** gate instant-highlight engagement behind a still hold
+for touch/pen — `INSTANT_HOLD_MS = 300`, `INSTANT_HOLD_MOVE_PX = 10` in useTextSelector.ts.
+- `armInstantHold` (touch/pen) records the press, starts a 300ms timer, does NOT
+  preventDefault. A tap releases first (`handlePointerUp`/`handlePointerCancel` →
+  `cancelInstantHold`) → native click → paginate. A swipe moves first
+  (`maybeCancelInstantHoldOnMove`, called in BOTH `handlePointerMove` and
+  `handleNativeTouchMove`, compares window-coord `pointerPos` vs `instantHoldStartWindow`)
+  → native swipe → paginate. Only a still hold fires the timer → `startInstantAnnotating`.
+- Mouse path unchanged (immediate `preventDefault` + start) — click vs. press-drag is
+  already unambiguous; matches the existing "mouse shouldn't be time-gated" stance.
+- Refactor: `startInstantAnnotating(target, startPoint)` / `stopInstantAnnotating()` no
+  longer take `ev`; the down `target` is stored in `instantAnnotationTarget` so the exact
+  element gets `user-select` restored (pointerup target may differ after the finger moves).
+
+Two parallel instant-highlight mechanisms share the same enable flag: (1) the
+`useInstantAnnotation` live drag-to-highlight (this fix), and (2) the
+quick-action-on-selection deferred path (`beginGesture`/`deferredQuickActionRef`/
+`pointerDownTimeRef` in Annotator.tsx) which ALREADY long-press-gates touch on
+iOS/desktop but not Android. Test: `useTextSelector-instantHold.test.ts`. See
+[[keyboard-selection-adjust-4728]] for the adjacent `isPointerDown`/`handleSelectionchange` logic.
@@ -0,0 +1,18 @@
+---
+name: ios-instant-dict-double-popup
+description: iOS instant system-dictionary fired 2-3× per long-press + tap-to-deselect re-opened it + Word Lens ignored system dict; deferredAction once-per-gesture latch + long-press-hold gate
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 1c09f918-0b1d-4f75-b1c6-8cef5eb73d60
+---
+
+Three related instant-dictionary bugs fixed together (dev branch, 2026-06-18). Core: the **instant quick action** (Annotator effect `[selection,bookKey]` → `handleQuickAction`) fired per `selectionchange`, and **iOS emits MULTIPLE `selectionchange` for one long-press** (user log showed 3; Android emits 1). Each fire → `handleDictionary` (system path) → `invokeSystemDictionary` → native `show_lookup_popover` which drills to the top-most presented VC and stacks another `UIReferenceLibraryViewController` → 2-3 sheets. Android never hit it because it **defers the action to `touchend`** (coalesces); iOS fired immediately.
+
+**Fix 1 (double/triple sheet)** — `src/app/reader/utils/deferredAction.ts`: added a `fired` latch so `runOrDeferAction`/`flushDeferredAction` run the action **at most once per gesture**; `beginGesture(state)` (clears pending + re-arms) called at gesture start — Android **native** `touchstart` (replaced `cancelDeferredAction`) and a NEW **non-Android DOM `pointerdown`** listener in `Annotator.tsx` (gated `!isAndroidApp`; Android keeps its native path).
+
+**Fix 2 (tap-to-deselect re-opened dict ~1/3)** — after dismissing the sheet iOS leaves the word selected; the reselection is safe (latch still set, no WebView pointerdown from the modal swipe), but tapping outside to deselect IS a pointerdown → `beginGesture` re-armed the latch, then a racy `selectionchange` re-reported the lingering word before collapse → re-fired. Fix = `isLongPressHold(pointerDownTime, now, 300ms)` gate in `handleQuickAction` (gated `!isAndroidApp`): only fire from a long-press hold (iOS selection appears ~500ms after pointerdown; tap-stray fires ~tens of ms). Touch pointerdown time recorded in the non-Android listener; **mouse records 0 → bypasses the gate** (desktop selects on pointerup).
+
+**Fix 3 (Word Lens ignored system dict)** — Annotator effect `wantWordLensDict` branch hardcoded `setShowDictionaryPopup(true)`; changed to call `handleDictionary()` (which checks `isSystemDictionaryEnabled` → `invokeSystemDictionary`, else in-app popup), same as the toolbar/instant paths. See [[wordlens-feature]].
+
+Verified on Xiaomi 13 Pro via CDP+adb (`src/__tests__/android/helpers/*`): real system-dict path on Android = `ACTION_PROCESS_TEXT`→Eudic; instant dict fired once/long-press + re-armed gesture 2; gloss tap → `handleDictionary system=true`+`invokeSystemDictionary os=android`. iOS confirmed by user. Gotchas: `longPressWord` waits for a persistent selection → times out in instant-action mode (the action dismisses the selection); count fires via a `console.info` hook read over CDP `evaluate` instead. `openFixtureBook`'s >200-char gate fails when the fixture's saved progress lands on the sparse feedbooks end-page → connect to the already-open reader instead.
@@ -0,0 +1,18 @@
+---
+name: ios-share-txt-stuck-supportstext
+description: iOS sharing a .txt to Readest hung the share sheet; Share Extension NSExtensionActivationSupportsText captured plain-text files
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 445ce295-90f6-4ed2-8227-e25b1e0a876d
+---
+
+Sharing a `.txt` file to Readest via the iOS share sheet got **stuck**, while EPUB/PDF worked. Root cause: the **Share Extension** (article-URL clipper, added #4256/#4267) wrongly activated for `.txt`. FIXED, **PR #4917 merged** (`fix/ios-share-txt-stuck`).
+
+- `ShareViewController.swift` only ever extracts an `http(s)` URL. Its activation rule (`project.yml`) had `NSExtensionActivationSupportsWebURLWithMaxCount: 1` **and `NSExtensionActivationSupportsText: true`**.
+- A `.txt` is UTI `public.plain-text`, which **conforms to `public.text`** → satisfies `SupportsText` → the URL-only clipper activates for a file it can't handle → sheet hangs (for a file-backed provider `loadItem(public.plain-text)` returns a file `URL`, so `loadText`'s `as? String`/`as? Data` both fail → no URL → neither completes nor cleanly cancels).
+- EPUB (`org.idpf.epub-container`) / PDF (`com.adobe.pdf`) conform to neither text nor web-URL, so they never match the extension and take the **main app** `CFBundleDocumentTypes` "Copy to Readest" open-in-place path (`Readest_iOS/Info.plist`), which imports via `useOpenWithBooks.ts` → `importBook` (format-agnostic; txt→epub via `TxtToEpubConverter`). `.txt` is ALSO declared there, so it imports fine once the extension stops stealing it.
+
+**Fix (option A):** remove `NSExtensionActivationSupportsText: true`; keep web-URL only. Safari/Chrome "share page" still sends `public.url`, so article clipping is preserved. Only regression: sharing a raw text *selection* containing a link no longer triggers the extension (minor).
+
+**Source-of-truth gotcha:** `src-tauri/gen/apple/project.yml` is the **xcodegen** source; Tauri's iOS CLI runs `xcodegen` at build time (`tauri-cli/src/mobile/ios/project.rs`) and REGENERATES each target's `Info.plist` from it. The committed `ShareExtension/Info.plist` is a generated artifact marked **`skip-worktree`** (`git ls-files -v` → `S`) — local edits to it are invisible to git and it stays stale at HEAD. So: fix `project.yml` ONLY; a test asserting on the committed plist would pass locally but FAIL on a fresh CI checkout. Regression test lives at `src/__tests__/ios/share-extension-activation-rule.test.ts` (asserts on `project.yml`, strips `#` comments first since the warning comment names the key). Test precedent: `src/__tests__/android/*declarations*.test.ts` read native config via `resolve(process.cwd(), 'src-tauri/...')`.
@@ -0,0 +1,20 @@
+---
+name: ios-widget-cover-bright-edge-line
+description: iOS reading widget cover sometimes had a bright hairline at the right edge from fractional resize; round target to whole pixels
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: fc6acdd3-a3d1-4823-a5c4-7fe75686fc93
+---
+
+iOS reading-widget book covers sometimes showed a **bright hairline along the right edge** (Android widget never did). Fixed in PR #4950, `src-tauri/plugins/tauri-plugin-native-bridge/ios/Sources/ReadingWidgetWriter.swift` `writeThumbnail`.
+
+**Root cause:** the downsample target was fractional:
+`CGSize(width: image.size.width * scale, height: image.size.height * scale)` with `scale = 240 / longEdge`. For portrait covers the height (longEdge) lands on a whole pixel but the width is fractional. `UIGraphicsImageRenderer` allocates a **whole-pixel** buffer (rounds the size up), while `image.draw(in:)` fills only the exact fractional rect — so when the fractional width rounds *up*, the rightmost pixel column is only partially covered → **semi-transparent** (e.g. alpha 225 instead of 255). `jpegData` has no alpha, so that column flattens to a visible bright line. Intermittent ("sometimes") because it only bites when the fractional part rounds up; portrait-specific because width is the fractional edge.
+
+**Fix:** round both dimensions to whole pixels so draw-rect == pixel-buffer and every edge pixel is fully covered:
+`CGSize(width: (image.size.width * scale).rounded(), height: (image.size.height * scale).rounded())`.
+
+Verified with a faithful CoreGraphics repro (same rasterization as UIKit): `453x680` cover gave edge alpha `225` before, `255` after; all sizes `255` after. Android ([[mobile-reading-widgets]] `ReadingWidgetStore.kt`) is immune because it scales to a fixed integer 240x360 and center-crops.
+
+No checked-in Swift test: the plugin `Package.swift` has no wired test target and the code is UIKit-only.
@@ -0,0 +1,48 @@
+---
+name: issue-4584-tap-death-investigation
+description: "#4584 single-taps-dead-after-picture-zoom: isPopuped self-heals (red herring), likely WebView-148-specific, plus Android emulator/CDP gesture-verification gotchas"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: a41b6cab-c0f3-4740-a4c0-61a10b68fc09
+---
+
+#4584 (Android): after using picture zoom (long-press image → ImageViewer → close),
+single taps stop registering until app restart while long-press keeps working. OP on
+Android 16 / WebView 148. **NOT root-caused / NOT fixed.** PR #4600 only adds single-tap
+as a second way into the viewer (see [[tap-to-open-image-table-4600]]); it does not fix
+the tap-death.
+
+**Red herring — don't "fix" `isPopuped`.** An adversarial analysis pointed at
+`useTextSelector.ts` `handleSingleClick`'s `isPopuped` branch consuming a tap without
+resetting the flag (unlike its `isTextSelected`/`isUpToPopup` siblings). But it
+**self-heals**: the branch calls `handleDismissPopup()` → `showingPopup` false →
+`handleShowPopup(false)` → `isPopuped` false after 500ms. And the uncancelled 500ms
+timer in `handleShowPopup` always converges `isPopuped` to the FINAL `showingPopup`
+(timers are same-delay FIFO), so it can't strand `isPopuped=true` with `showingPopup=false`.
+Net effect is at most a one-tap glitch, NOT permanent. Resetting it in the branch is
+harmless but does NOT explain #4584.
+
+Likely **WebView-148-specific**: the OP reproduces; the maintainer's Xiaomi and the
+Pixel_9_Pro emulator (WebView **133**) do NOT. A stronger unverified permanent-death
+candidate is `isInstantAnnotating`/`scrollLocked` getting stuck when the ImageViewer
+overlay swallows the `pointerup` (needs instant-annotation enabled).
+
+**Android emulator gesture-verification gotchas (this machine):**
+- Host-GPU `Pixel_9_Pro` AVD CRASHES on rapid pinch (Vulkan `bad_function_call`); a
+  re-launch can hang at Vulkan init. `-gpu swiftshader_indirect` boots reliably but is
+  too slow for the WebView reader → repeated "Input dispatching timed out for
+  FocusEvent" ANRs under automation. **That ANR is an EMULATOR ARTIFACT, not app code**
+  (JS stays responsive; CPU runs native arm64 on Apple Silicon, only the GPU is
+  swiftshader; CPU profile of page-turns is light; full-screen backdrop-blur made zero
+  frame-time difference).
+- CDP `Input.dispatchTouchEvent` CANNOT trigger the WebView's native text-SELECTION
+  gesture, so the annotation popup never appears (blocks reproducing selection-driven
+  bugs). It also leaves `screenX=0`, so `handlePageFlip` treats every synthetic tap as
+  left/`prev()` (no-op at page 1 → navigate mid-book to test page-turns via relocate).
+- Native `adb shell input tap` does NOT reach the WebView's click pipeline.
+- Long-press via CDP only works if you HOLD the touch on one open connection and poll
+  (a touchStart→sleep→touchEnd across separate `node` invocations releases too early).
+- Drive the live on-device WebView: `adb forward tcp:9222 localabstract:webview_devtools_remote_<pid>`
+  + a `ws` CDP client; the debug APK exposes the socket. VIEW-intent a pushed EPUB via its
+  MediaStore `content://.../<id>` to import it.
@@ -0,0 +1,22 @@
+---
+name: keyboard-selection-adjust-4728
+description: "After a reader text selection, keystrokes land in the PARENT (container focus), not the iframe — fix Shift/Ctrl/Alt+Arrow selection refine in useBookShortcuts"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 9ebaeccc-0436-4c7b-a81e-1a4aa3de64dd
+---
+
+#4728: standard desktop selection shortcuts — `Shift+←/→` refine selection by character, `Ctrl/Alt(Option)+Shift+←/→` by word — implemented in the **parent** shortcut system, not the iframe.
+
+**Critical gotcha (cost a full redesign):** after a text selection, `Annotator.handleShowAnnotPopup` calls `containerRef.current?.focus()` on desktop, so `document.activeElement` is a **parent-document DIV**, not the book iframe. Real OS keystrokes therefore go to the parent `window` → `useShortcuts` (native keydown path) → page-turn shortcuts (`shift+ArrowRight`=`onGoNext`/`onGoForward`). A fix inside the iframe `handleKeydown` is **bypassed** for real keystrokes — it only fires if focus is in the iframe (e.g. quick-actions config). JS-dispatched `KeyboardEvent`s into the iframe doc DO hit the iframe handler, so they falsely "pass" — only a **real OS key** (`computer.key`) reveals the parent-focus path. Always verify with a real keystroke, not a synthetic dispatch.
+
+**Fix shape:**
+- `utils/sel.ts`: pure `getKeyboardSelectionAdjustment(KeyModifiers)` → `{direction:'left'|'right', granularity:'character'|'word'}|null` (Shift=char, Ctrl||Alt=word, metaKey→null so native Cmd+Shift line-select survives; 'left'/'right' visual dir for RTL). `extendSelectionFromContents(contents, ev, extend)` walks `view.renderer.getContents()` (`{doc}[]`), finds the non-collapsed `doc.defaultView.getSelection()`, and (if `extend`) `sel.modify('extend', dir, gran)`; returns whether a selection was found.
+- `helpers/shortcuts.ts`: new `onAdjustTextSelection` (section 'Selection') with keys `shift+Arrow{Left,Right}` + `ctrl/alt+shift+Arrow{...}`.
+- `useBookShortcuts.ts`: `adjustTextSelection` wired **first** in the `useShortcuts` actions map so it intercepts before `onGoNext/Prev/...`. Native keydown (parent focus) → extend ourselves; forwarded iframe-keydown MessageEvent (iframe already extended natively) → `extend:false`, just report presence to suppress nav. Returns true ⇒ `processKeyEvent` stops ⇒ no page turn.
+- `useTextSelector.handleSelectionchange`: desktop normally defers to pointerup; relaxed the gate to `!isAndroid && !isTouchInput && isPointerDown.current` (new `isPointerDown` ref set in pointerdown, cleared in pointerup/cancel) so a keyboard-driven `selectionchange` (no pointer drag) refreshes the popup/range. This realm-agnostic gate refreshes for BOTH the parent-modify and native-iframe-modify paths.
+
+**Selection.modify test artifact:** in browser-lane tests build the starting selection with `setBaseAndExtent` (or collapse+extend), NOT `addRange` — `addRange` leaves the selection directionless so backward `modify('extend','left'/'backward')` silently no-ops; `setBaseAndExtent` establishes anchor/focus like a real mouse drag.
+
+Verified live on Chrome with real keystrokes (Alice EPUB, scrolled mode): `Shift+→` "Queen"→"Queen." no turn; `Opt+Shift+→` "two"→"two miles" (word); popup follows; no selection ⇒ `Shift+→` still scrolls (nav preserved). Paginated auto-scroll-to-follow when extending past the page edge is NOT wired (foliate's `isKeyboardSelecting` scrollToAnchor only fires for iframe-focus keydowns; parent-focus has none) — minor known limitation. See [[layout-ui-fixes]].
@@ -0,0 +1,19 @@
+---
+name: koplugin-bulk-download-4751
+description: "koplugin Library \"Download all books\" bulk download — entry point, candidate query, and the sync/async coroutine bridge"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: b474b24d-cfa5-4f32-b6f2-d6a35f27cadd
+---
+
+Issue #4751: bulk "download all" for the readest.koplugin Library view (parity with Readest web/desktop "download all"). Branch `feat/koplugin-bulk-download-4751`, PR #4765 (base main).
+
+- Entry point: view-menu Actions section in `library/libraryviewmenu.lua` → calls `require("library.librarywidget").downloadAll()` (no args; reads `M._opts`/`M._store` like `M.refresh()`).
+- Candidate set: new `LibraryStore:listCloudOnlyBooks()` = `cloud_present=1 AND local_present=0 AND deleted_at IS NULL AND uploaded_at IS NOT NULL` (phantom records with no uploaded file are excluded, same as `listBooks`). Whole library, ignores active search/group. Test-first in `librarystore_spec.lua`.
+- Orchestration `M.downloadAll()`: sequential reuse of `syncbooks.downloadBook`, inside `Trapper:wrap`. Progress + cancel via `Trapper:info("Downloading %1 of %2…")` — it yields to UIManager, so a tap queued during the previous (blocking) download is processed at the book boundary and raises Trapper's Abort/Continue confirm (returns false → cancel). Skip per-book failures, count them, show a summary toast. Only `Trapper:clear()` when NOT cancelled (abort path already closed the widget).
+- **Sync/async cb bridge** (the non-obvious bit): `downloadBook`'s callback fires exactly once but may be synchronous (token fresh) OR async (after token refresh). In the cb, resume the coroutine only `if coroutine.status(co) == "suspended"`; capture result + a `finished` flag, and only `coroutine.yield()` `if not finished`. This avoids "resume non-suspended coroutine" errors in the sync case and correctly awaits in the async case. Reusable for any callback-style KOReader API awaited inside a Trapper coroutine.
+- i18n: 6 new `_()` strings, `T(_("… %1 …"), ...)` interpolation (`local T = require("ffi/util").template`). Ran `node scripts/extract-i18n.js`; translated all 33 locales via [[i18n-koplugin]] flow. Verify: placeholders `%1/%2/%3` preserved (no `%s/%d`), `…` U+2026 kept.
+- Note: the per-book long-press sheet already had a "Download All" (cover+file for ONE book) — left as-is; distinct from the new bulk "Download all books".
+
+Gates: `pnpm lint:lua` + `pnpm test:lua` (see [[verify-format-check-gate]] / verification.md). No JS/TS/Rust changes.
@@ -0,0 +1,18 @@
+---
+name: koplugin-cover-upload
+description: "koplugin cover system — where local/cloud covers come from, and the"
+metadata: 
+  node_type: memory
+  type: reference
+  originSessionId: 95cdff70-ce2c-4077-82a8-922f9578a22f
+---
+
+readest.koplugin cover handling (in `apps/readest.koplugin/library/`):
+
+- **Local book covers** come from coverbrowser.koplugin's `BookInfoManager` (a hard dependency). `coverprovider.get_local_cover(file_path)` returns `BIM:getBookInfo(file_path, true).cover_bb` (a downscaled thumbnail bb) and kicks off background extraction on a miss.
+- **Native-resolution cover** for a file (no open doc needed): `require("apps/filemanager/filemanagerbookinfo"):getCoverImage(nil, file_path)` — opens+closes the doc itself, honors KOReader custom covers, returns a blitbuffer. Same `(nil, file)` call form `calibre.koplugin` uses. Write it to PNG with `bb:writeToFile(path, "png")` (pcall-wrapped internally) then `bb:free()`.
+- **Cloud covers** are downloaded to `DataStorage:getSettingsDir()/readest_covers/<hash>.png` (`cloud_covers.covers_dir()`); cloud storage key is `<user_id>/Readest/Books/<hash>/cover.png` (`build_cover_key`), which matches readest's `getCoverFilename` (`<hash>/cover.png`).
+
+**Issue #4374 (fixed):** `syncbooks.uploadBook` only shipped a `cover.png` if one was *already cached* under `readest_covers/<hash>.png` from a prior cloud download — so books that originated locally in KOReader uploaded with no cover and showed blank in readest. Fix = `syncbooks.extractLocalCover(file_path, dst_png)` (extracts via `getCoverImage` → writeToFile), called from `uploadBook` when `has_cover` is false. Only file-upload path is `librarywidget.lua` "Upload to Cloud" → `uploadBook` (FileManager `addToReadest` only stages a local row).
+
+Tests: network/live parts of `syncbooks.lua` aren't unit-tested (manual matrix in `docs/library-design.md`); `extractLocalCover` IS tested by injecting a fake `apps/filemanager/filemanagerbookinfo` via `package.loaded` in `spec/library/syncbooks_spec.lua`. A real KOReader checkout lives at `/Users/chrox/dev/koreader` for verifying KOReader APIs. See [[koplugin-i18n]].
@@ -0,0 +1,55 @@
+---
+name: koplugin-library-open-mosaic-cache-4954
+description: koplugin Library slow open on large libraries — group-cover mosaics recomposed every paint; fixed by availability-keyed cache + async compose
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 7e7dbb83-cffb-495d-9778-bf94ccb45d8b
+---
+
+Issue #4954 (PR #4974, MERGED 2026-07-07): opening the KOReader plugin Library
+was slow on large libraries (~1000 books) while navigation stayed fast.
+
+**Root cause (measured, not guessed).** Added open-path timing instrumentation
+(`ui/time` + `elapsed_ms` helper) to `library/librarywidget.lua` (initial
+`build_item_table`, `lightScan`, post-scan refresh, total synchronous open,
+cloud-sync elapsed) and a step breakdown in `library/localscanner.lua`. On a
+685-book library the synchronous open was ~300ms, dominated by a **254ms
+post-scan refresh** = `library/group_covers.lua` recomposing each folder's 2x2
+cover **mosaic from scratch on every paint** (up to 4 MuPDF decodes+scales per
+cell), with no cache, and again on the post-sync refresh. `build_item_table`
+(7ms) and `lightScan` (28ms, only 16 sidecar reads) were NOT the bottleneck —
+my initial hypotheses (defer lightScan / incremental history) were refuted by
+the log. Why "slow to load, fast to navigate": the root Groups view is mosaics;
+drilling into a group shows single covers (cheap, BIM-cached). Soft-scales with
+size (fuller groups → 4 covers/mosaic vs 1). Data-side pagination is NOT
+possible (KOReader `Menu` derives page count from `#item_table`).
+
+**Fix (mirror `cloud_covers` async pattern in `group_covers`).**
+- Cache composed master bb per group, keyed by `mosaic_cache_key` = ordered
+  child hashes + a per-child **cover-availability bit** (`child_cover_available`
+  → `cloud_covers.cover_exists(hash)` or local file stat). Serve `copy_bb` on
+  hit. The availability bit fixes the historical "partial composite served
+  forever" bug that killed the prior on-disk cache: a late cover flips the key
+  and recomposes once.
+- **Cache the `nil` result too** (critical): a coverless group whose children
+  aren't downloaded makes `compose` return nil; if not cached it re-enqueues +
+  `schedule_refresh` on every refresh → infinite recompose/refresh loop (eink
+  flashing). Caught this in the second emulator log (`group_nameLanguagegrid`
+  missing every refresh). Cache nil under the availability key → placeholder
+  served, no re-enqueue.
+- Compose off first-paint: miss enqueues a single-slot background job (one
+  mosaic per UI `nextTick`, `_pump_scheduled` coalesces), returns nil so the
+  cell paints its FakeCover placeholder; completions coalesce into one refresh.
+- `clear_cache()` on Library close (via `libraryitem.set_visible_hashes(nil)`)
+  frees masters (~0.7MB each).
+
+Result: synchronous open 300ms→151ms, post-scan refresh 254ms→89ms (now just the
+4 visible single cloud-book cover decodes + placeholders, mosaics deferred).
+
+**Left out (follow-ups noted in PR):** single cloud-book covers
+(`cloud_covers.load_cover_bb`) still re-decode from disk each refresh (~89ms/4)
+— same copy-on-serve cache could apply; deferred cloud sync uses synchronous
+HTTP that briefly freezes UI after the menu appears (elapsed 1.6-6.8s, network
+variance). Instrumentation kept intentionally (Library open is infrequent).
+See [[koplugin-stats-duplicate-book-rows-4861]], [[koplugin-library-stale-synced-cursor-4934]].
@@ -0,0 +1,23 @@
+---
+name: koplugin-library-stale-synced-cursor-4934
+description: "#4934 koplugin Library goes stale forever: pull cursor keyed on client updated_at not server synced_at; split pull/push cursors + v2->v3 heal migration"
+metadata:
+  node_type: memory
+  type: project
+---
+
+**Issue #4934, PR #4944 MERGED** (merge commit `0b180da6a`, koplugin Lua only, base `readest/readest:main`). Reporter: iOS + KOReader; the koplugin "Readest library" stopped receiving iOS updates and never recovered. Workaround was delete `koreader/settings/readest_library.sqlite3` + "Pull books now" (works for a while, re-breaks). **iOS/web library unaffected** — the smoking gun.
+
+**Root cause (the direct follow-up [[sync-synced-at-cursor-4678]] predicted).** Since #4678 the server keys the books GET on the server-stamped `synced_at` (`src/pages/api/sync.ts` `cursorColumn = table==='books' ? 'synced_at' : 'updated_at'`, `.gt('synced_at', since)`). Web/iOS advance their cursor from `synced_at` (`useSync.ts computeMaxTimestamp`, prefers synced_at) → always ≤ server-now → never stale. The **koplugin was left on `updated_at`**: `syncbooks.lua pullBooks` set `last_books_pulled_at = max(updated_at, deleted_at)` of returned rows; `parseSyncRow` never read `synced_at`. `updated_at` is CLIENT event time, and the koplugin stamps it from the **device clock** (`librarystore.lua touchBook` = `os.time()*1000`). An e-reader clock ahead of the server (common; dead RTC / wrong date) — or ANY single row account-wide carrying a future `updated_at` — drove the koplugin's global cursor past server-now, so `synced_at > since` returned nothing **forever**. Delete-sqlite reset the cursor to 0 (workaround); it re-broke once a book-open re-bumped it into the future.
+
+**Extra hazard #4678 flagged:** `last_books_pulled_at` was SHARED between the pull cursor (vs server synced_at) and push-delta detection (`getChangedBooks` vs LOCAL updated_at) — can't just retarget it to synced_at. So the fix requires a cursor SPLIT.
+
+**Fix (all in `apps/readest.koplugin/library/`):**
+1. `librarystore.lua parseSyncRow`: add transient `synced_at = iso_to_ms(dbRow.synced_at)` (NOT a books column; server sends it via `select('*')`). New `getLastPushedAt`/`setLastPushedAt` on key `last_books_pushed_at`.
+2. `syncbooks.lua`: new pure `row_pull_cursor(parsed)` = `parsed.synced_at` if present else `max(updated_at, deleted_at)` (mirrors computeMaxTimestamp; exported `M._row_pull_cursor` for tests). `pullBooks` seeds `pull_ts`/`push_ts` from their stored values (no regression on empty pages), advances `last_books_pulled_at` from `row_pull_cursor` (synced_at) and `last_books_pushed_at` from `max(updated_at, deleted_at)` of pulled rows. `pushChangedBooks` reads/writes `getLastPushedAt`/`setLastPushedAt` instead of the pull cursor.
+3. **Cursor split:** pull cursor = server `synced_at` (pull only); push watermark = local `updated_at`, advanced on BOTH pull and push (preserves the old dedup so pulled books aren't re-pushed — the old shared cursor did exactly this).
+4. **Heal migration `SCHEMA_VERSION 2->3`** (`M.new`, guard `prev>=1 and prev<3`): `INSERT last_books_pushed_at SELECT value FROM ... WHERE key='last_books_pulled_at'` then `UPDATE ... SET value='0' WHERE key='last_books_pulled_at'`. Seeds push watermark from the old shared value (no re-push storm) and zeroes the pull cursor → next sync does ONE full re-pull that re-establishes it on synced_at. **Auto-heals already-stale installs; user need not delete the sqlite.**
+
+**Scope note (intentional):** the push watermark, seeded from a poisoned future value, still suppresses the koplugin's OWN local pushes until wall-clock passes it — but that's UNCHANGED from before (old shared cursor did the same) and #4934 is a pull/viewing bug ("iOS unaffected"). Not fixing device-clock `updated_at` here. Only functional cursor callers are in syncbooks; `librarywidget.lua:557` only logs it.
+
+**Tests (TDD, gates `pnpm test:lua` 224✓ / `pnpm lint:lua` exit 0):** `librarystore_spec.lua` — parseSyncRow synced_at, getLast/setLastPushedAt independent round-trip, `v2->v3 migration` (reset pull=0 + seed push, per-user), bumped user_version 2→3 (and the v1->v2 test now lands at 3, migrations cumulative). `syncbooks_spec.lua` — `_row_pull_cursor` (synced_at wins over a future updated_at; fallback; 0), and `pullBooks` integration via injected fake `sync_auth`/client + real in-memory store asserting pull cursor=synced_at (not future updated_at) and push watermark=updated_at distinctly.
@@ -0,0 +1,18 @@
+---
+name: koplugin-note-deletion-sync
+description: "koplugin deleting a note didn't sync to Readest — push only walked live annotations; fixed with persisted tombstones"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: f3f6e25e-1bde-4e08-9fc9-c8184d1ef457
+---
+
+readest.koplugin deletions of highlights/bookmarks never reached the server (#4119 push direction; the pull direction was already handled by `removeDeletedAnnotations`).
+
+**Root cause:** `SyncAnnotations:push` builds its payload from `getAnnotations`, which walks `ui.annotation.annotations` (the *live* list). A deleted note is already removed from that list, so it can never appear in a push — the server never gets a `deleted_at`, and the next pull resurrects it.
+
+**Fix (all in `apps/readest.koplugin/`):**
+- `readest_syncannotations.lua`: extracted `buildNoteDescriptor(item, book_hash, meta_hash)` (shared by `getAnnotations` and the new deletion path). Added `recordDeletion(doc_settings, item)` — stamps `deletedAt = os.time()*1000` on the descriptor and persists it under `doc_settings.readest_sync.deleted_notes` (per-book sidecar, survives restart/offline). `push` folds `deleted_notes` into the payload (re-stamping current book/meta hash) and clears them in the success callback only (failed push retries).
+- `main.lua` `onAnnotationsModified(items)`: detects a removal via `items.index_modified < 0` (additions use positive index_modified; note-text edits / type-changes carry no index_modified — see KOReader `ReaderBookmark:removeItemByIndex`). Records the tombstone when `access_token` is set (independent of `auto_sync`, so a later manual/close push still carries it).
+
+**Key facts:** note id is deterministic — server-created notes keep their stored `item.id` (pulled in), koplugin-created ones derive `generateNoteId(hash, type, pos0, pos1)`; both match the server row, so the tombstone targets it. Server `sync.ts` POST picks the tombstone via `clientDeletedAt > serverDeletedAt` (deletedAt wins even when updatedAt is stale). Missing `text`/`note` in the payload is fine (`sanitizeString(undefined)` returns undefined; plain highlights already push `note=nil`). Tests in `spec/syncannotations_spec.lua` (recordDeletion + push-folds-tombstones, UI-glued push driven by stub client/doc_settings). Related: [[custom-fonts-reincarnation-4410]] (CRDT remove-wins).
@@ -0,0 +1,27 @@
+---
+name: koplugin-stats-sync
+description: KOReader readest.koplugin reading-stats sync (push on close / pull on open); 3-bug chain fixed in PR
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 9b3eaf27-8688-4293-ab42-f635af2e1905
+---
+
+`readest.koplugin` reading-statistics sync (KOReader `statistics.sqlite3` page events) — fixed in PR #4666 (`readest_syncstats.lua`, `main.lua`, `readest-sync-api.json`).
+
+**Trigger model (fully automatic, no menu/gesture):**
+- **Pull** on book OPEN: `onReaderReady` → `pullBookStats(false)` (via `nextTick`).
+- **Push** on book CLOSE: `onCloseDocument` → `pushBookStats(false)` (wrapped in `goOnlineToRun`).
+- Both gated on `self.settings.auto_sync and self.settings.access_token`, `interactive=false` (silent on failure).
+- NOT per-book: `collectSince` queries the whole `statistics.sqlite3` (`page_stat_data JOIN book`, no book filter). Open/close is just the trigger; it syncs the entire stats delta. Incremental via `stats_push_cursor` (max `start_time`) / `stats_pull_cursor` (max `updated_at_ms`); cursor advances only on full success.
+
+**3 stacked bugs (each hid the next):**
+1. `push`/`pull` called `settings:readSetting/saveSetting` on `self.settings`, which is the PLAIN `readest_sync` data table (from `G_reader_settings:readSetting("readest_sync", default)`), NOT a `LuaSettings` object → `attempt to call method 'readSetting' (a nil value)` on every open. Fix: field access + persist via `G_reader_settings:saveSetting("readest_sync", settings)` (mirrors `readest_syncauth.lua`). Field-access pattern is used everywhere else (`self.settings.access_token`, etc.).
+2. `pushChanges` requires `books/notes/configs` (`required_params`); stats sent only `statBooks/statPages` → Spore `books is required`. Fix: send empty `books={},notes={},configs={}` alongside. Server (`src/pages/api/sync.ts`) defaults each to `[]` and processes `statBooks`/`statPages` independently (gated only on their own `.length`).
+3. `statBooks/statPages` were in the spec's `payload` but not `optional_params` → Spore `statBooks is not expected`. **Spore's expected-param set = `required_params ∪ optional_params`; `payload` only controls body serialization, NOT acceptance** (`common/Spore/Request.lua` `validate()`). Fix: add `optional_params:["statBooks","statPages"]` to `readest-sync-api.json`. Must be optional not required (library/config/annotation pushes legitimately omit them).
+
+**Spore client:** `readest_syncclient.lua` `_dispatch` runs the RPC in a coroutine with Turbo `AsyncHTTP` (network is non-blocking, yields to event loop); `Format.JSON` encodes the body synchronously first. `SYNC_TIMEOUTS={5,10}` (block/total).
+
+**Large-backlog blocking risk (UNFIXED, potential follow-up):** push sends the WHOLE backlog in one request (no client chunking; only pull is paginated). For ~10k `page_stat_data` rows: `collectSince` builds a 10k-entry Lua table + ~1MB JSON encode SYNCHRONOUSLY on the main thread → ~1-2s UI stall on weak e-ink CPUs at book close (network part is async, doesn't freeze). Worse: 10s timeout + no chunking + all-or-nothing cursor → if it can't finish in time it fails silently, cursor stays 0, and every later close re-collects/re-encodes/re-uploads the same backlog (server upserts are idempotent but wasteful). Fix idea: chunk push (~500-1000/req, matching server `BATCH=500`), advance cursor per successful chunk.
+
+**Testing gap that hid it:** `spec/syncstats_spec.lua` originally tested only `collectSince`/`applyRemote`, never `push`/`pull`. Added tests: cursor advance on success (mock client enforces `required_params`), pull cursor from newest `updated_at_ms`, and a spec-level check parsing `readest-sync-api.json` to assert every stats-push key is an expected param (reproduces bug 3). Busted runs with `cwd=KOPLUGIN_DIR` so `io.open("readest-sync-api.json")` works; `require("json")`→dkjson via spec_helper shim. Debug logging kept (`ReadestStats` prefix). Related: [[koplugin-note-deletion-sync]], [[kosync-cfi-spine-resolution]].
@@ -0,0 +1,20 @@
+---
+name: kosync-connect-false-positive-4692
+description: "KOSync connect() accepted any 2xx (even an HTML web-UI page) as login → misconfigured Server URL silently \"connects\" but never syncs"
+metadata: 
+  node_type: memory
+  type: reference
+  originSessionId: 43e853c2-58ea-42f0-97ed-66aa3f65e4d1
+---
+
+#4692 (PR #4711): KOReader Sync to a self-hosted Grimmory/Booklore server failed on Android (worked on iOS). Root cause was a **misconfigured Server URL** that resolved to the host's static web UI instead of the sync endpoint, made undebuggable by a Readest gap.
+
+**Server-side tell (the smoking gun):** Android `PUT /syncs/progress` was handled by Spring's `ResourceHttpRequestHandler` → `HttpRequestMethodNotSupportedException: Request method 'PUT' is not supported`. That handler is Booklore's SPA/static fallback — so the request reached the server but **missed the koreader controller** and hit the catch-all static handler. GET requests (auth/pull) silently get the HTML index with 200; only PUT errors (static handler rejects non-GET/HEAD).
+
+**Readest gap:** `KOSyncClient.connect()` treated any 2xx from `/users/auth` (or `/users/create`) as success. An HTML web-UI page returns 200 → false-positive "connected"; then pulls show 0% and pushes fail with no error surfaced. Matches the classic "no errors reported, still 0%" report.
+
+**Fix:** validate the auth/registration response is an actual koreader JSON object (real server → `{"authorized":"OK"}`; HTML fails `response.json()`), else return "Not a KOReader Sync server. Check the Server URL." (`isKoSyncJsonResponse` helper in `KOSyncClient.ts`). Catches misconfig at setup, when actionable.
+
+**Still silent (intentional follow-up, not done):** per-sync push/pull failures. `getProgress`/`updateProgress` collapse "request failed" and "no remote data" into the same `null`/`false`; naive toasting would fire on every transient auto-push (5s). Needs noise-aware design before surfacing.
+
+KOSync settings are **per-device** (no Readest account → not synced across devices), so iOS vs Android URLs are entered independently — the #1 suspect when one platform syncs and the other doesn't. Related: [[kosync-cfi-spine-resolution]], [[empty-start-cfi-sync]].
@@ -0,0 +1,18 @@
+---
+name: library-reader-separate-texture-4743
+description: "Separate library vs reader background texture (#4743); shared-style-element + two gotchas"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: dfdb7b38-1869-4fb4-b869-c32301c80128
+---
+
+#4743: library and reader shared one background texture; split so each is set independently.
+
+**Architecture**: ONE global `<style id="background-texture">` paints `body::before` (covers library) plus reader containers (`.foliate-viewer/.sidebar-container/.notebook-container ::before`). Library and reader are separate routes (only one mounted), so the split = store two values + have each page apply its own on activation, not separate style elements. New device-local `SystemSettings.libraryBackground{TextureId,Opacity,Size}` (NOT in settings sync whitelist — texture *selection* is per-device like reader's `backgroundTextureId`; only image binaries sync via `texture` replica kind). `getLibraryViewSettings(settings)` in `helpers/settings.ts` resolves each field with `?? globalViewSettings.<field>` so the bookshelf inherits the reader texture until decoupled (no migration). `ColorPanel` is context-aware via `isLibraryContext = !bookKey`: library context writes `libraryBackground*` via `saveSysSettings`, reader context unchanged via `saveViewSettings`. Applied at boot (`Providers`) + on every library mount (`library/page.tsx` effect).
+
+**Gotcha 1 — `useBackgroundTexture` early-returned on `'none'` WITHOUT unmounting.** Since library+reader share the one style element, switching a page to None must actively clear a texture the OTHER page mounted. Fixed: always delegate to `applyTexture(envConfig, textureId || 'none')` (it unmounts on 'none'); only set CSS vars / addTexture for a real texture. Also fixes the symmetric reader case (opening a 'none' book after a textured one).
+
+**Gotcha 2 — `useSettingsStore` initializes `settings: {} as SystemSettings`.** So `settings.globalViewSettings` is `undefined` on the first renders before `appService.loadSettings()` runs. Any NEW effect/deps that deep-derefs `settings.globalViewSettings.<x>` crashes the library with "Cannot read properties of undefined (reading 'backgroundTextureId')". Caught only in a hard reload (HMR kept old store state, so first nav didn't repro). Fix = optional-chain in effect deps + make the resolver tolerate missing globalViewSettings (fallback to 'none'). Relates to [[cover-stale-inplace-mutation-memo]].
+
+Verified end-to-end in dev-web: library moon texture, reader stays none, round-trip persists, None clears live. Related: [[wordlens-feature]] i18n (recent feature commits ship `_()` strings WITHOUT running `i18n:extract`; translations are batched separately — don't commit locale churn in a feature PR).
@@ -0,0 +1,18 @@
+---
+name: list-view-series-overflow-4796
+description: "Library list view series + description text overlapped/clipped under fixed h-28, worsened by Android system font scaling"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 8645710b-673d-422a-ad8a-e3f385057f49
+---
+
+PR #4799 (branch `fix/list-series-overflow-4796`). Reported on Pixel 10 Pro / Android 16: in library **list view**, a book that belongs to a series shows its series line and description preview overlapping and cut off.
+
+**Root cause:** `BookItem.tsx` list-mode container used a fixed `h-28` (112px) with `overflow-hidden`. The right column stacks title + authors + (optional) series + description + a progress/actions row (`useResponsiveSize(15)` → ~19px on phones). Without a series it fits 112px; the optional series line (added in #4593/#4612) pushes the total over 112px, so the lines collide and clip. **Android applies the system accessibility font-size scale to WebView CSS text**, inflating line heights — that's what made it bad enough to report (matched the issue screenshot at ~130% scale).
+
+**Fix:** `h-28` → `min-h-28` (one class). Row grows to fit; non-series rows keep 112px. List is `Virtuoso` with measured (not fixed) heights, so variable row heights are fine.
+
+**Verification:** jsdom can't measure layout, so reproduced the exact flex markup in a real browser at normal + 130% font scale (before = overlap, after = clean). Lint + full `pnpm test` (6324 pass) + `format:check` pass.
+
+Lesson: fixed-height list/card rows are fragile against optional metadata lines AND user font scaling. Prefer `min-h-*` when the row can virtualize. Related: [[cover-stale-inplace-mutation-memo]].
@@ -0,0 +1,40 @@
+---
+name: markdown-md-support-774
+description: Markdown (.md) reading via in-memory foliate book (no EPUB); split-at-H1; foliate book-object contract gotchas
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: a82e979b-0edb-4964-91fd-3677ecfe5679
+---
+
+Issue #774: render standalone `.md` files at runtime (NO EPUB conversion). **MERGED as
+PR #4816** (branch `feat/markdown-support`). Built test-first via `/autoplan` (CEO+Eng
+dual-voice review). Suite green (6365), lint + format clean; live-verified in web app
+(import via drop, split TOC, cross-section nav, GFM rendering, pagination).
+
+**Where:** `src/utils/md.ts` `makeMarkdownBook(file)` builds an in-memory foliate book
+modeled on `packages/foliate-js/fb2.js`. Routed in `src/libs/document.ts` `open()` via
+`isMd()` **before `isTxt()`** (a `.md` served as `text/plain` would otherwise hit TXT→EPUB).
+`'md'` added to `SUPPORTED_BOOK_EXTS` (constants.ts). `sanitize.ts` `sanitizeHtml` gained
+`'class'` (code `language-*` theming) + `del`/`ins` tags. Pipeline: strip YAML frontmatter →
+`marked`(gfm) → `sanitizeHtml` → split at `<h1>` (preamble = pre-first-H1 content) → nested
+heading-outline TOC.
+
+**Non-obvious foliate book-object contract (cost us the CRITICAL review finding):**
+- `section.id` and `splitTOCHref()` output MUST be the SAME type. readest nav
+  (`services/nav/index.ts:133`) does `new Map(sections.map(s=>[s.id,s]))` then `.get(sectionId)`
+  where sectionId = `splitTOCHref(href)[0]`. `SectionItem.id` is typed `string`, so use
+  STRING ids + `splitTOCHref => href.split('#')`. fb2.js uses numbers consistently (works
+  only because it's untyped JS); do NOT copy fb2's `Number(x)`.
+- Fragment CFIs / TOC sub-anchors require `section.loadText` (nav skips sections without it,
+  index.ts:153). Provide it.
+- `SectionItem.cfi` is non-optional → set `cfi: ''` (foliate falls back to `CFI.fake.fromIndex`).
+- `createDocument()` parses `application/xhtml+xml`; marked's HTML5 void tags (`<br><hr><img>`)
+  are parse errors there → serialize sections with `XMLSerializer` (not innerHTML). `load()`
+  and `createDocument()` must derive from the SAME string (CFI round-trip).
+- `resolveHref` returns `null` for unresolved anchors (never index 0). jsdom lacks
+  `URL.createObjectURL` → `load()` is lazy + tests stub it.
+
+**Deferred follow-ups (open issues):** relative image resolution (web File-objects have no
+sibling access — needs the bundle model); Markdown folder/zip "package" model; footnotes/math/
+Mermaid/wikilinks; syntax-highlight token colors. Plan: `.claude/plans/2026-06-26-markdown-md-support-774.md`.
@@ -0,0 +1,48 @@
+---
+name: middle-click-autoscroll-4951
+description: "Middle-click autoscroll in scrolled mode (#4951): Autoscroller RAF core + armed-books registry in iframeEventHandlers; scrolls via renderer.containerPosition"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: d8d21fc2-b63b-4f65-8ca8-f65d9e6b17b2
+---
+
+Middle mouse button autoscroll for desktop Tauri apps in scrolled mode
+(readest#4951), PR #4955 MERGED 2026-07-06 (merge 6f3b401c2). No settings
+toggle: always on for desktop in scrolled mode (maintainer removed the toggle
+as unnecessary; middle click has no other use in the reader). The same PR also
+shipped a locale sync: 69 keys untranslated on main filled across 33 locales
+(agents per language family; scanner-prunable keys preserved).
+
+Key structure:
+- `src/app/reader/utils/autoscroller.ts` — pure `Autoscroller` class (RAF loop,
+  12px dead zone, 10 px/s per px linear velocity capped 4000, whole-pixel
+  emission with fractional carry, held→sticky/drag state machine). Tested in
+  `src/__tests__/reader/utils/autoscroller.test.ts` with injected raf/now.
+- `useMiddleClickAutoscroll(bookKey, viewRef, containerRef)` hook consumes
+  `iframe-mousedown/mouseup/mousemove/wheel/keydown` messages + window-level
+  capture listeners; returns anchor (container-relative) for
+  `AutoscrollIndicator`. Scrolls with `renderer.containerPosition += delta`
+  (public setter; native scroll path, so section preloading works). Axis from
+  `renderer.scrollProp` ('scrollLeft' = vertical writing → x axis; increasing
+  scrollLeft always moves viewport right even in RTL, no special-casing).
+- iframeEventHandlers runs in the parent realm: `setAutoscrollArmed(bookKey)`
+  registry lets `handleMousedown` preventDefault middle button (suppresses
+  WebView2's native autoscroll on Windows, avoids double-drive) and
+  `handleAuxclick` swallow link opens; `setAutoscrollTracking(bool)` gates an
+  `iframe-mousemove` postMessage forwarder so it costs nothing when idle.
+- Pointer deltas use screenX/Y (same trick as useTouchEvent pinch) so iframe
+  coordinate spaces/transforms don't matter. Anchor window position computed in
+  the iframe handler via `event.view.frameElement.getBoundingClientRect()` +
+  client-size scale, posted as windowX/windowY on button-1 mousedown only.
+- A left click that ends a sticky session must not also turn the page: the
+  hook consumes the later `iframe-single-click` via
+  `eventDispatcher.onSync` within a 500ms window (usePagination checks
+  dispatchSync consumption before paginating).
+- Setting `middleClickAutoscroll` in `BookLayout` (default TRUE, user chose
+  default-on), toggle in ControlPanel Scroll BoxedList, desktop only
+  (`appService?.isDesktopApp`), disabled unless scrolled mode. Web excluded on
+  purpose (browsers own middle click).
+
+Related: [[i18n-extract-prunes-keys]] (followed its manual single-key insertion
+recipe for the 'Middle-Click Autoscroll' label across 33 locales).
@@ -0,0 +1,21 @@
+---
+name: mobile-reading-widgets
+description: "Home-screen reading widgets (#1602, PR"
+metadata: 
+  node_type: memory
+  type: reference
+  originSessionId: 7f7f8218-4656-4863-972e-ea6204c130fa
+---
+
+Mobile home-screen reading widgets (issue #1602, merged PR #4842). Code lives in the **native-bridge plugin**: `src-tauri/plugins/tauri-plugin-native-bridge/{android,ios}/` (Android `ReadingWidgetProvider.kt` + `res/`; iOS writer `ReadingWidgetWriter.swift`) and the iOS WidgetKit extension at `src-tauri/gen/apple/ReadestWidget/`. App publishes a snapshot + downsized cover thumbnails via the `update_reading_widget` command to iOS App Group `group.com.bilingify.readest` / Android `SharedPreferences`. Widget hook: `src/hooks/useReadingWidget.ts`; payload builder `src/services/widget/readingWidget.ts`; tap opens `readest://book/{hash}` via `useOpenBookLink.ts`.
+
+Durable, non-obvious gotchas (each cost a debugging round):
+
+- **iOS widget missing from gallery = stale `.xcodeproj`.** `gen/apple/project.yml` defines the `ReadestWidget` target, but **Tauri's iOS build does NOT re-run xcodegen**, so a newly-added target is silently omitted from the build. Fix: `cd src-tauri/gen/apple && xcodegen generate`. Also: iOS builds from the **MAIN repo** `/Users/chrox/dev/readest` (complete gen/apple), NOT the `pnpm worktree:new` worktree (its gen/apple is incomplete — missing `Sources/`, `Assets.xcassets`, `Externals`, `LaunchScreen.storyboard` — so xcodegen fails there).
+- **Android RemoteViews allow only @RemoteView widgets.** Plain `<View>` (and `<Space>`) is NOT allowed → launcher inflate fails → "Can't load widget". Use an empty `FrameLayout` for spacers. Covers: badge + progress bar are **baked into the bitmap** (Canvas in `writeThumbnail`) because RemoteViews can't clip/overlay reliably; shown via `fitCenter`. Responsive sizing by grid cells: `n = (minWidthDp + 30) / 70` (Android cell formula); one book per column, cap 3.
+- **Background TTS progress freeze.** `book.progress` (libraryStore) AND `readerProgressStore` are both written by the same `setProgress`, inside `commitRelocate` → **`requestAnimationFrame`**, which Android pauses for a backgrounded WebView → both freeze during background TTS. No store-only fix (page-based progress needs rendering). Fix: in `FoliateViewer.progressRelocateHandler`, commit synchronously when `document.visibilityState === 'hidden'` (relocate still fires; only the rAF commit was deferred). Confirmed working on device.
+- **Android crash: "cannot use a recycled source in createBitmap" (exact-2:3 covers).** In `ReadingWidgetStore.writeThumbnail`, `Bitmap.createBitmap(src, x, y, w, h)` returns the SAME instance when the crop covers the whole *immutable* source (`decodeFile` bitmaps are immutable) — which happens when the cover decodes to exactly 2:3 (height==width*3/2), making the center-crop a no-op. The old code then did `bitmap.recycle()`, recycling `cropped` too, so the next `createScaledBitmap(cropped, …)` threw. Fix: `if (cropped !== bitmap) bitmap.recycle()` — mirror the `if (scaled !== cropped) cropped.recycle()` guard already 4 lines below. Trace was R8-obfuscated + ran inside `update_reading_widget`'s `pluginScope.launch { withContext(Dispatchers.IO) }`, surfacing as `FATAL EXCEPTION: main` with a `Dispatchers.Main` cancelled-coroutine suppressed frame. **iOS is unaffected** — `ReadingWidgetWriter.writeThumbnail` uses ARC-managed immutable `UIImage` + `UIGraphicsImageRenderer`, no manual recycle/aliasing.
+- **iOS TTS controls deferred** — interactive widget buttons need iOS 17 App Intents; widget min target is iOS 15 (15/16 widgets can only deep-link, no buttons). Android uses `MediaButtonReceiver.buildMediaButtonPendingIntent` (any version). Follow-up only.
+- **`.superpowers/` is NOT gitignored** in this repo → a subagent's `git add` can sweep SDD scratch (`*-report.md`) into a commit; check `git ls-files '.superpowers/*'` before squashing/pushing.
+
+Related: [[android-nativefile-remotefile-io]] · [[tts-fixes]] · build/worktree [[feedback_use_worktree]]
@@ -0,0 +1,16 @@
+---
+name: multiwindow-settings-clobber-4580
+description: Pagination/global settings revert with multiple desktop windows; cross-window broadcast fix
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 4df1808d-e106-4316-9206-b4e606b4b9bf
+---
+
+Issue #4580 (fix: PR #4803, branch `fix/multiwindow-settings-revert-4580`): on desktop (Tauri) global view settings (Click/Swipe to Paginate, Show Page Navigation Buttons) "revert to default" — only when multiple windows are open (OP ran `1 + n_opened_books` windows).
+
+**Root cause:** each Tauri window keeps its own in-memory `useSettingsStore.settings`, loaded once at window open. Global settings persist to ONE shared `settings.json`, and every window writes the WHOLE object via the store's `saveSettings`. A window opened before the user customized a global setting holds the default (e.g. `disableClick=false`); when it later saves (notably `handleCloseBooks` on reader-window close in `ReaderContent.tsx`, but ANY settings write) it clobbers the user's value back to default. Explains "reverts to *default*, only with multiple windows". Note: `replicaCursorStore` avoids this by load-modify-saving from disk each time.
+
+**Fix:** cross-window broadcast. `src/utils/settingsSync.ts` (`broadcastGlobalSettings` emits `global-settings-window-sync` with `sourceLabel` + the two global blobs; `subscribeSettingsSync` ignores self; `mergeSyncedGlobalSettings` adopts `globalViewSettings`/`globalReadSettings` and preserves all device/window-local fields). Store `saveSettings` calls `broadcastGlobalSettings` after persisting. `useSettingsSync` (mounted in `Providers.tsx`, the shared root for both library + reader windows) adopts broadcasts via `setSettings`. No-op off Tauri.
+
+Only the two global objects are synced (minimal scope) — covers the reported bug + sibling read settings; top-level scalars left window-local. No save/broadcast loop: receive calls `setSettings` only; the replica publisher subscriber pushes to network (no disk write) and pagination fields aren't in `SETTINGS_WHITELIST` anyway. Live cross-window view update of already-open books is intentionally NOT done (bug is persistence, not live propagation). Related: [[webdav-connect-nullified-4780]] (stale settings closure), [[window-state-sanitize-4398]].
@@ -0,0 +1,91 @@
+---
+name: native-ios-tts-4676
+description: Native local iOS TTS (AVSpeechSynthesizer) mirroring the Android native TTS plugin;
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: ec6b5ad5-f187-4615-83b4-33b1a9e77ba7
+---
+
+# Native local iOS TTS (#4676)
+
+STATUS: MERGED (PR #4697, into main 2026-06-21). Device-verified by maintainer:
+system-voice playback, voice selection, rate/pitch, auto-advance, pause/resume,
+stop/disable teardown, and lock-screen controls + metadata for both system and
+Edge TTS. Final design = iOS lock screen via `navigator.mediaSession` (NOT the
+native plugin); the Swift media-session methods are dead on iOS (Android-only).
+Diagnostic logging was stripped before merge.
+
+Goal: give iOS the same on-device TTS Android has (private, offline). The shared
+TypeScript `NativeTTSClient` (`src/services/tts/NativeTTSClient.ts`) and the Rust
+command/mobile layer (`src-tauri/plugins/tauri-plugin-native-tts/src/{commands,mobile,models}.rs`)
+were already platform-agnostic — only the Swift plugin (a `ping()` stub) and two
+gates were missing. See [[tts-fixes]].
+
+## What was changed
+- **`ios/Sources/NativeTTSPlugin.swift`** — full impl mirroring `android/.../NativeTTSPlugin.kt`.
+  Commands: init, speak, stop, pause, resume, set_rate, set_pitch, set_voice,
+  get_all_voices, set_media_session_active, update_media_session_state,
+  update_media_session_metadata, checkPermissions/requestPermissions.
+- **`TTSController.ts:91`** gate: `isAndroidApp` → `isAndroidApp || isIOSApp` (creates `ttsNativeClient`).
+- **`mediaSession.ts` `getMediaSession()`** reorder: check native platforms FIRST
+  (`(android||ios) && isTauriAppPlatform()` → `TauriMediaSession`), THEN
+  `'mediaSession' in navigator`. iOS WKWebView (and Android WebView) expose
+  `navigator.mediaSession`, but the web session can't drive lock-screen controls
+  for AVSpeech/TextToSpeech — so it must lose to the native plugin.
+- Tests: `tts-controller.test.ts` iOS gate + new `__tests__/libs/mediaSession.test.ts`.
+
+## Non-obvious gotchas
+- **`init` is a Swift reserved word.** Tauri iOS dispatch = `perform(Selector("\(command):"))`
+  (`mobile/ios-api/.../Tauri.swift`), so the "init" command needs selector `init:`.
+  Solution: `@objc(init:) public func initialize(_ invoke: Invoke)`. Verified it
+  compiles + `responds(to: Selector("init:"))==true` via swiftc. `perform` doesn't
+  apply ARC init-family retain rules (those are compile-time, direct-send only).
+  If it ever misbehaves on-device, fallback = rename the command for iOS in `mobile.rs`.
+- **Pause == stop (mirror Android).** JS `NativeTTSClient.pause()` returns `false`,
+  so `TTSController.pause()` (line 472) does stop + re-speak on resume. The Swift
+  delegate must emit `end` ONLY on `didFinish`, **never on `didCancel`** (cancel
+  comes from stop/pause; an `end` there would auto-advance the reader).
+- **AVAudioSession is owned by native-bridge.** `useTTSControl` calls
+  `invokeUseBackgroundAudio({enabled})` (plugin:native-bridge|use_background_audio →
+  `.playback`) on iOS TTS start/stop. AVSpeechSynthesizer uses the app session
+  (`usesApplicationAudioSession` defaults true), so the native-tts plugin does NOT
+  touch the audio session. Background + silent-switch playback comes for free
+  (Info.plist already declares `UIBackgroundModes: [audio]`).
+- **MPRemoteCommandCenter.shared() is app-global and shared** with native-bridge's
+  `MediaKeyHandler` (hardware media-key page-turns on next/previousTrack). The
+  native-tts plugin stores its `addTarget` tokens and removes ONLY those on
+  deactivate. Lock-screen next/previous + the media-key page-turn both fire if
+  both are active — on-device test point.
+- **Rate curve.** JS sends `pow(userRate, 2.5)` (tuned for Android setSpeechRate,
+  1.0=normal). Swift `avRate()` inverts (`^(1/2.5)`) and rescales onto
+  AVSpeechUtterance (0…1, `AVSpeechUtteranceDefaultSpeechRate`≈0.5 = normal). Top
+  speeds saturate at max (AV limitation).
+- Voice id = `AVSpeechSynthesisVoice.identifier` (round-trips through set_voice →
+  `AVSpeechSynthesisVoice(identifier:)`). All iOS voices group under "System TTS"
+  in the JS `getVoices` (no `_`-prefixed engine id); enhanced/premium quality
+  appended to the display name to disambiguate same-named variants.
+- Permissions already granted: `native-tts:default` (no platform restriction in
+  `capabilities/default.json`) covers every command.
+
+## Media session on iOS — REVERTED the native reroute (round 3)
+- On-device trace confirmed parallel teardown WORKS (`stop: wasSpeaking=true stopSpeaking returned true` → `set_media_session_active active=false` → `deactivateRemoteCommands: removed 5 targets, cleared nowPlayingInfo`). The remaining media-session problems were caused by the `getMediaSession()` reroute itself:
+  - Edge TTS lock screen lost cover + current sentence (REGRESSION): Edge plays via a WebView `<audio>` element → its lock-screen card is driven by `navigator.mediaSession.metadata` (set in `useTTSControl`). Routing iOS to `TauriMediaSession`/`MPNowPlayingInfoCenter` bypassed that.
+  - System TTS got NO controls: `AVSpeechSynthesizer` is not a WebView media element, so the app never becomes "Now Playing" and the plugin's `MPRemoteCommandCenter` targets never surface. (Edge gets controls because its `<audio>` element makes the app now-playing.)
+- FIX: `getMediaSession()` reverted so iOS uses `navigator.mediaSession` (Android still first→`TauriMediaSession` foreground service). iOS system TTS now rides the same WebView path as Edge — the silent keep-alive `unblockAudio` `<audio>` element + `navigator.mediaSession` metadata/action-handlers. OPEN/UNVERIFIED: whether the SILENT keep-alive element registers as Now Playing on iOS (if not, system TTS still shows no card — would need a non-silent keep-alive or a real native now-playing implementation). The iOS Swift media-session methods (set_media_session_active etc.) are now DEAD on iOS (only Android Kotlin uses them via TauriMediaSession); left in place, harmless.
+- Heavy Swift diagnostic logging (per-voice dump + per-command enter/resolve + delegate) still present; trim once confirmed.
+
+## Follow-up iOS fixes (same PR)
+- **Duplicate voice names**: Eloquence + legacy "novelty" voices (Rocko, Shelley, Grandma, Grandpa, Eddy, Reed, Flo, Sandy…) ship in many regions of one language, all quality=default. JS `getVoices` groups by primary language (`isSameLang`→normalized subtag), so e.g. en-US "Rocko" + en-GB "Rocko" collide in one "System TTS" list. Fix (in Swift `get_all_voices`): count `(primaryLanguage, displayName)`; for collisions append `regionDescription` (localized region, e.g. "Rocko (United Kingdom)"). Unique names stay clean. 192 system voices on a loaded device.
+- **First word clipped "sometimes"**: each sentence is a separate `AVSpeechUtterance` spoken after a gap → audio route goes cold between sentences → first phonemes clipped. Same family as the startup `!act` (cannotActivate) `AVAudioSession` error from native-bridge `use_background_audio`. Fix: `utterance.preUtteranceDelay = 0.1` warms the route with silence first.
+- **Stop "never tears down" / TTS icon stays blue (native only, Edge fine)**: the icon's blue state is driven by `viewState.ttsEnabled` (footer toggle) AND `isPlaying`/`showIndicator` (floating gradient `TTSIcon`). `handleStop` (useTTSControl) did all of `setIsPlaying`/`showIndicator` THEN `await ttsController.shutdown()` THEN `setTTSEnabled(bookKey,false)` as the LAST line — with NO try/catch. So if native `shutdown()` hangs OR throws, `setTTSEnabled(false)` never runs → footer icon stays blue forever; Edge never hits the stalling native path. ROOT FIX = reset ALL UI/session state (incl. `setTTSEnabled(false)`, null the ref) UP FRONT, then run shutdown/deinit best-effort in try/catch. Couldn't statically prove the exact native hang (every await in shutdown→stop is bounded/resolvable; native stop resolves since set_voice/set_rate use the same `resolve()` and playback works), so ALSO: bounded native stop invoke in `NativeTTSClient.stop()` (1500ms `Promise.race`) + Swift `os.Logger` lifecycle traces (speak/stop/pause/didStart/didFinish/didCancel) to pinpoint on-device — tapping stop should log `stop: requested`→`stop: resolved` + `didCancel`. Guard tests in `useTTSControl.test.tsx` assert `setTTSEnabled(false)` runs even when `shutdown()` rejects/never-resolves. NOTE: web bundle must be rebuilt for these JS fixes (not just the Swift plugin).
+- **Lock-screen media session keeps running after disable (native only) — round 2**: the icon fix moved `setTTSEnabled` early, but `deinitMediaSession()` + `invokeUseBackgroundAudio({enabled:false})` were STILL after `await ttsController.shutdown()`. Native `shutdown()` stalls → those never run → lock-screen Now Playing lingers (Edge unaffected: never hits the stalling native path). The Swift media-session teardown is correct (Edge proves `set_media_session_active(false)`→`deactivateRemoteCommands` clears `MPNowPlayingInfoCenter.nowPlayingInfo`) — it just wasn't being CALLED. FIX = run shutdown + `invokeUseBackgroundAudio(false)` + `deinitMediaSession()` via `Promise.all` (best-effort, parallel) so media/audio teardown never waits on the controller shutdown. Added `set_media_session_active` os_log + guard test (deinit called even when shutdown never resolves). Still UNCONFIRMED why native `shutdown()` itself stalls (all JS awaits bounded; native stop invoke should resolve) — Swift lifecycle logs will reveal on-device.
+
+## Verification done / pending
+- Done (host): `pnpm lint`, `pnpm test` (only pre-existing unrelated
+  `fixed-layout-paginated-scroll.test.ts` fails — untracked, no impl), swiftc
+  `-typecheck` of the plugin vs iOS SDK with Tauri stubs (0 errors; Sendable
+  warning is a standalone-swiftc strict-concurrency artifact, project is Swift 5).
+- Pending (on-device, user): build iOS, confirm init/speak/voices/rate/pitch,
+  auto-advance, pause-resume, lock-screen play/pause/next/prev + now-playing,
+  background playback, and the MediaKeyHandler interaction.
@@ -0,0 +1,18 @@
+---
+name: native-tts-offline-autoadvance-4613
+description: "Android/iOS System TTS stops at chapter end (or random intervals) offline — controller only auto-advances on 'end', native terminal 'error' dead-ends + wedges state"
+metadata: 
+  node_type: memory
+  type: project
+  originSessionId: 5ae3d6fc-9082-4ba2-b7d4-e02dd277ee8f
+---
+
+# Native System TTS offline auto-advance halt (#4613, #4408)
+
+**Symptom:** With Android System TTS (or iOS) **offline**, read-aloud stops — #4613 "at the end of the chapter, won't go to next chapter" (Samsung S25, Chinese voices); #4408 "random intervals" (GrapheneOS, Supertonic engine). Then the play/headphone controls feel **wedged**; #4408 also flashes the "Please log in to use advanced TTS features" toast on manual restart (separate client-selection path — controller briefly tries Edge).
+
+**Root cause (`TTSController.#speak`):** auto-advance fires ONLY on `lastCode === 'end'`. The native client surfaces an offline engine failure as a terminal **`'error'`** code (Android `UtteranceProgressListener.onError`). Usually a **specific unsynthesizable utterance** (an unsupported CHARACTER — chrox's insight, fits online/offline asymmetry: engines network-fall-back for hard chars when online), hit on the new chapter's first utterance. On `'error'`: no `forward()` → playback dead-ends; `this.state` stays `'playing'` → controls wedge (restart re-errors on the same chunk). Edge/Web throw instead (caught by `error()` → state 'stopped'), so only **native** hits this. Engine-specific: Google local voices emit `onDone` fine, so it doesn't reproduce on every device.
+
+**Fix (PR #4716, `#speak` only):** gate `canSkipOnError = this.ttsClient === this.ttsNativeClient`. On terminal `'error'` (native, playing, !aborted, !oneTime): **SKIP the chunk and `forward()`** — same as `'end'` — because re-speaking deterministically-bad text just fails again (do NOT retry; first attempt was retry-the-same-chunk which is futile for an unspeakable char). Bound `#consecutiveSpeakErrors` (reset on `'end'`); when it exceeds `TTS_NATIVE_SPEAK_MAX_CONSECUTIVE_ERRORS=5` → `await this.stop()` (graceful: wholly-unusable engine stops instead of silently racing to book end; leaves 'playing' so controls recover). Edge/Web byte-for-byte unchanged. Tests (`tts-controller.test.ts` "native TTS offline error recovery (#4613, #4408)"): skip-advances-past-bad-chunk (forward spied) + cap-stops-gracefully (key off `state.attempts` NOT `state` — controller starts 'stopped' and `forward()` transiently re-enters 'stopped', so `waitFor(state==='stopped')` false-matches).
+
+**On-device verification reality (Xiaomi 13 fuxi, Android 16, WebView 147, Google TTS):** CANNOT reproduce the fault — offline auto-advance works, even offline+screen-off (foreground-audio service keeps the WebView UNthrottled; Google local engine emits onDone offline). Matches maintainer's non-repro. Needs the reporter's engine (Samsung/Supertonic/Chinese-network voice). Force the engine-error path on this device by setting a `*-network` voice offline. See [[cdp-android-webview-profiling]] for the CDP recipe; gotcha: `window.__TAURI_INTERNALS__.invoke`/`runCallback` get RE-INJECTED on Next.js client nav (wrappers revert) — `console.log` wrapping persists, so trace via the `[TTS] speak` / `[TTS] Initialized TTS for section N` logs instead. Related: [[tts-fixes]], [[tts-browser-e2e-harness]].
--- a/Show More
+++ b/Show More