fix(launcher): normalize rofi prompt spacing

- Add formatRofiPrompt to trim trailing whitespace and append a single space, keeping the prompt from running into the input field - Apply it across all rofi -p usages in picker.ts and history-command.ts - Add tests for formatRofiPrompt edge cases (empty/whitespace-only prompts)
feat(launcher): add previous episode option to history entry menu
2026-07-27 04:49:49 -07:00 · 2026-07-26 00:13:54 -07:00 · 2026-07-25 23:35:44 -07:00 · 2026-07-22 23:51:21 -07:00 · 2026-07-22 23:34:08 -07:00 · 2026-07-22 23:07:07 -07:00
330 changed files with 138549 additions and 5912 deletions
@@ -8,98 +8,4 @@ on:

 jobs:
  build-test-audit:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint changelog fragments
-        run: bun run changelog:lint
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
-        if: github.event_name == 'pull_request'
-        run: bun run changelog:pr-check --base-ref "origin/${{ github.base_ref }}" --head-ref "HEAD" --labels "${{ join(github.event.pull_request.labels.*.name, ',') }}"
-
-      - name: Build (TypeScript check)
-        # Keep explicit typecheck for fast fail before full build/bundle.
-        run: bun run typecheck
-
-      - name: Verify generated config examples
-        run: bun run verify:config-example
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Stats UI tests
-        run: bun run test:stats
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
-
-      - name: Security audit
-        run: bun audit --audit-level high
-        continue-on-error: true
-
-      - name: Build Bun subminer wrapper
-        run: make build-launcher
-
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
-
-      - name: Enforce generated launcher workflow
-        run: bash scripts/verify-generated-launcher.sh
+    uses: ./.github/workflows/quality-gate.yml
@@ -12,86 +12,9 @@ concurrency:

 jobs:
  quality-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ runner.arch }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Build (TypeScript check)
-        run: bun run typecheck
-
-      - name: Install Lua
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y lua5.4
-          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
-          lua -v
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Environment suite
-        run: bun run test:env
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Stats UI tests
-        run: bun run test:stats
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml

  build-linux:
    needs: [quality-gate]
@@ -0,0 +1,117 @@
+name: Quality Gate
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.bun/install/cache
+            node_modules
+            stats/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Lint changelog fragments
+        run: bun run changelog:lint
+
+      - name: Lint stats (formatting)
+        run: bun run lint:stats
+
+      - name: Enforce pull request changelog fragments (`skip-changelog` label bypass)
+        if: github.event_name == 'pull_request'
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
+        run: bun run changelog:pr-check --base-ref "origin/$BASE_REF" --head-ref "HEAD" --labels "$PR_LABELS"
+
+      - name: Build (TypeScript check)
+        run: bun run typecheck
+
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Install Lua
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y lua5.4
+          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
+          lua -v
+
+      - name: Test suite (source)
+        run: bun run test:fast
+
+      - name: Environment suite
+        run: bun run test:env
+
+      - name: Coverage suite (maintained source lane)
+        run: bun run test:coverage:src
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-test-src
+          path: coverage/test-src/lcov.info
+          if-no-files-found: error
+
+      - name: Stats UI tests
+        run: bun run test:stats
+
+      - name: Launcher smoke suite (source)
+        run: bun run test:launcher:smoke:src
+
+      - name: Upload launcher smoke artifacts (on failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: launcher-smoke
+          path: .tmp/launcher-smoke/**
+          if-no-files-found: ignore
+
+      - name: Build (bundle)
+        run: bun run build
+
+      - name: Immersion SQLite verification
+        run: bun run test:immersion:sqlite:dist
+
+      - name: Dist smoke suite
+        run: bun run test:smoke:dist
+
+      - name: Security audit
+        run: bun audit --audit-level high
+
+      - name: Build Bun subminer wrapper
+        run: make build-launcher
+
+      - name: Verify Bun subminer wrapper
+        run: dist/launcher/subminer --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh
@@ -13,76 +13,9 @@ concurrency:

 jobs:
  quality-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-            stats/node_modules
-            vendor/subminer-yomitan/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: |
-          bun install --frozen-lockfile
-          cd stats && bun install --frozen-lockfile
-
-      - name: Lint stats (formatting)
-        run: bun run lint:stats
-
-      - name: Build (TypeScript check)
-        run: bun run typecheck
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - name: Coverage suite (maintained source lane)
-        run: bun run test:coverage:src
-
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-test-src
-          path: coverage/test-src/lcov.info
-          if-no-files-found: error
-
-      - name: Stats UI tests
-        run: bun run test:stats
-
-      - name: Launcher smoke suite (source)
-        run: bun run test:launcher:smoke:src
-
-      - name: Upload launcher smoke artifacts (on failure)
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: launcher-smoke
-          path: .tmp/launcher-smoke/**
-          if-no-files-found: ignore
-
-      - name: Build (bundle)
-        run: bun run build
-
-      - name: Immersion SQLite verification
-        run: bun run test:immersion:sqlite:dist
-
-      - name: Dist smoke suite
-        run: bun run test:smoke:dist
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml

  build-linux:
    needs: [quality-gate]
@@ -61,3 +61,6 @@ tests/*
 favicon.png
 .claude/*
 !stats/public/favicon.png
+
+# Browser-automation session artifacts (page snapshots, console logs, downloads)
+.playwright-mcp/
@@ -4,3 +4,4 @@ release
 coverage
 vendor
 *.log
+src/core/services/tokenizer/__fixtures__/golden/*.json
@@ -213,7 +213,7 @@ On **Windows**, just run `SubMiner.exe` and the setup will open automatically on
 subminer video.mkv          # launch mpv with SubMiner
 subminer /path/to/dir       # pick a file with fzf
 subminer -R /path/to/dir    # pick a file with rofi (Linux only)
-subminer -H                 # browse local watch history (replay / next episode / browse)
+subminer -H                 # browse history, then previous / replay / next / select / quit
 ```

 On **Windows**, use the **SubMiner mpv** shortcut created during setup. Double-click it or drag a video file onto it.
@@ -7,36 +7,45 @@
      "dependencies": {
        "@fontsource-variable/geist": "^5.2.8",
        "@fontsource-variable/geist-mono": "^5.2.7",
-        "@xhayper/discord-rpc": "^1.3.3",
-        "axios": "^1.13.5",
+        "@xhayper/discord-rpc": "^1.3.4",
+        "axios": "^1.18.1",
        "commander": "^14.0.3",
        "electron-updater": "^6.8.3",
-        "hono": "^4.12.7",
+        "hono": "^4.12.28",
        "jsonc-parser": "^3.3.1",
        "koffi": "^2.15.6",
        "libsql": "^0.5.22",
-        "ws": "^8.19.0",
+        "ws": "^8.21.0",
      },
      "devDependencies": {
        "@types/node": "^24.10.0",
        "@types/ws": "^8.18.1",
-        "electron": "42.2.0",
+        "electron": "42.6.0",
        "electron-builder": "26.8.2",
        "esbuild": "^0.25.12",
        "eslint": "^10.4.0",
        "prettier": "^3.8.1",
        "typescript": "^5.9.3",
+        "undici": "7.28.0",
      },
    },
  },
+  "patchedDependencies": {
+    "@discordjs/rest@2.6.1": "patches/@discordjs%2Frest@2.6.1.patch",
+  },
  "overrides": {
-    "@xmldom/xmldom": "0.8.12",
+    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.8.2",
+    "brace-expansion": "5.0.7",
    "electron-builder-squirrel-windows": "26.8.2",
+    "form-data": "4.0.6",
+    "ip-address": "10.2.0",
+    "js-yaml": "4.3.0",
    "lodash": "4.18.0",
    "minimatch": "10.2.3",
    "picomatch": "4.0.4",
-    "tar": "7.5.11",
+    "tar": "7.5.21",
+    "tmp": "0.2.7",
  },
  "packages": {
    "7zip-bin": ["7zip-bin@5.2.0", "", {}, "sha512-ukTPVhqG4jNzMro2qA9HSCSSVJN3aN7tlb+hfqYCt3ER0yWroeA2VR38MNrOHLQ/cVj+DaIMad0kFCtWWowh/A=="],
@@ -45,10 +54,12 @@

    "@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],

-    "@discordjs/rest": ["@discordjs/rest@2.6.1", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.40", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.24.1" } }, "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg=="],
+    "@discordjs/rest": ["@discordjs/rest@2.6.1", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.40", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.27.0" } }, "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg=="],

    "@discordjs/util": ["@discordjs/util@1.2.0", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-3LKP7F2+atl9vJFhaBjn4nOaSWahZ/yWjOvA4e5pnXkt2qyXRCHLxoBQy81GFtLGCq7K9lPm9R517M1U+/90Qg=="],

+    "@electron-internal/extract-zip": ["@electron-internal/extract-zip@1.0.4", "", {}, "sha512-Zr1Vs7E9tpCNhZHDAbFVXc2gEVCG9RqPDjrno5+bdgB6LRAuvgyMHJut4NCVyYwtAieapMzc3fiQ3CSTi75ARg=="],
+
    "@electron/asar": ["@electron/asar@3.4.1", "", { "dependencies": { "commander": "^5.0.0", "glob": "^7.1.6", "minimatch": "^3.0.4" }, "bin": { "asar": "bin/asar.js" } }, "sha512-i4/rNPRS84t0vSRa2HorerGRXWyF4vThfHesw0dmcWHp+cspK743UanA0suA5Q5y8kzY2y6YKrvbIUn69BCAiA=="],

    "@electron/fuses": ["@electron/fuses@1.8.0", "", { "dependencies": { "chalk": "^4.1.1", "fs-extra": "^9.0.1", "minimist": "^1.2.5" }, "bin": { "electron-fuses": "dist/bin.js" } }, "sha512-zx0EIq78WlY/lBb1uXlziZmDZI4ubcCXIMJ4uGjXzZW0nS19TjSPeXPAjzzTmKQlJUZm0SbmZhPKP7tuQ1SsEw=="],
@@ -215,13 +226,11 @@

    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],

-    "@types/yauzl": ["@types/yauzl@2.10.3", "", { "dependencies": { "@types/node": "*" } }, "sha512-oJoftv0LSuaDZE3Le4DbKX+KS9G36NzOeSap90UIK0yMA/NhKJhqlSGtNDORNRaIbQfzjXDrQa0ytJ6mNRGz/Q=="],
-
    "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],

-    "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.3", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.42", "ws": "^8.20.0" } }, "sha512-Ih48GHiua7TtZgKO+f0uZPhCeQqb84fY2qUys/oMh8UbUfiUkUJLVCmd/v2AK0/pV33euh0aqSXo7+9LiPSwGw=="],
+    "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.4", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.47", "ws": "^8.20.0" } }, "sha512-ff0uEXuibh9wi+l4vOj7xInLUjtlTaQBje/SCyQkeXZ0j2V0y+Zge5PQIQFRHH9TjjGaYJkTofEcQhncM2q7/w=="],

-    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.13", "", {}, "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw=="],

    "abbrev": ["abbrev@3.0.1", "", {}, "sha512-AO2ac6pjRB3SJmGJo+v5/aK6Omggp6fsLrs6wN9bd35ulu4cCwaAU9+7ZhXjeqHVkaHThLuzH0nZr0YpCDhygg=="],

@@ -229,7 +238,7 @@

    "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],

-    "agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+    "agent-base": ["agent-base@6.0.2", "", { "dependencies": { "debug": "4" } }, "sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ=="],

    "ajv": ["ajv@6.14.0", "", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw=="],

@@ -257,7 +266,7 @@

    "at-least-node": ["at-least-node@1.0.0", "", {}, "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg=="],

-    "axios": ["axios@1.13.6", "", { "dependencies": { "follow-redirects": "^1.15.11", "form-data": "^4.0.5", "proxy-from-env": "^1.1.0" } }, "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ=="],
+    "axios": ["axios@1.18.1", "", { "dependencies": { "follow-redirects": "^1.16.0", "form-data": "^4.0.5", "https-proxy-agent": "^5.0.1", "proxy-from-env": "^2.1.0" } }, "sha512-3nTvFlvpn9Zu/RkHUqtc7/+al4UpRW5az71ap5zccp6e8RAYEzhMTecX8Dz1wWDYrPpUoB1HAQEGEAEvUr7S9g=="],

    "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],

@@ -267,12 +276,10 @@

    "boolean": ["boolean@3.2.0", "", {}, "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw=="],

-    "brace-expansion": ["brace-expansion@5.0.4", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg=="],
+    "brace-expansion": ["brace-expansion@5.0.7", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA=="],

    "buffer": ["buffer@5.7.1", "", { "dependencies": { "base64-js": "^1.3.1", "ieee754": "^1.1.13" } }, "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ=="],

-    "buffer-crc32": ["buffer-crc32@0.2.13", "", {}, "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ=="],
-
    "buffer-from": ["buffer-from@1.1.2", "", {}, "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ=="],

    "builder-util": ["builder-util@26.8.1", "", { "dependencies": { "7zip-bin": "~5.2.0", "@types/debug": "^4.1.6", "app-builder-bin": "5.0.0-alpha.12", "builder-util-runtime": "9.5.1", "chalk": "^4.1.2", "cross-spawn": "^7.0.6", "debug": "^4.3.4", "fs-extra": "^10.1.0", "http-proxy-agent": "^7.0.0", "https-proxy-agent": "^7.0.0", "js-yaml": "^4.1.0", "sanitize-filename": "^1.6.3", "source-map-support": "^0.5.19", "stat-mode": "^1.0.0", "temp-file": "^3.4.0", "tiny-async-pool": "1.3.0" } }, "sha512-pm1lTYbGyc90DHgCDO7eo8Rl4EqKLciayNbZqGziqnH9jrlKe8ZANGdityLZU+pJh16dfzjAx2xQq9McuIPEtw=="],
@@ -347,7 +354,7 @@

    "dir-compare": ["dir-compare@4.2.0", "", { "dependencies": { "minimatch": "^3.0.5", "p-limit": "^3.1.0 " } }, "sha512-2xMCmOoMrdQIPHdsTawECdNPwlVFB9zGcz3kuhmBO6U3oU+UQjsue0i8ayLKpgBcm+hcXPMVSGUN9d+pvJ6+VQ=="],

-    "discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
+    "discord-api-types": ["discord-api-types@0.38.49", "", {}, "sha512-XnqcWmnFZFAE8ZM8SHAw9DIV8D3Or00rMQ8iQLotrEA2PmXhl+ykaf6L6q4l474hrSUH1JaYcv+iOMRWp2p6Tg=="],

    "dmg-builder": ["dmg-builder@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "fs-extra": "^10.1.0", "iconv-lite": "^0.6.2", "js-yaml": "^4.1.0" }, "optionalDependencies": { "dmg-license": "^1.0.11" } }, "sha512-DaWI+p4DOqiFVZFMovdGYammBOyJAiHHFWUTQ0Z7gNc0twfdIN0LvyJ+vFsgZEDR1fjgbpCj690IVtbYIsZObQ=="],

@@ -363,7 +370,7 @@

    "ejs": ["ejs@3.1.10", "", { "dependencies": { "jake": "^10.8.5" }, "bin": { "ejs": "bin/cli.js" } }, "sha512-UeJmFfOrAQS8OJWPZ4qtgHyWExa088/MtK5UEyoJGFH67cDEXkZSviOiKRCZ4Xij0zxI3JECgYs3oKx+AizQBA=="],

-    "electron": ["electron@42.2.0", "", { "dependencies": { "@electron/get": "^5.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-b2Tc7sIKiZEl0tBVwFM5GJ+FT5KYhmy9QJHjx8BGVZPVW2SctXWEvrE959ElB56qw7H05dBkhlikDA1DmpaAMw=="],
+    "electron": ["electron@42.6.0", "", { "dependencies": { "@electron-internal/extract-zip": "^1.0.1", "@electron/get": "^5.0.0", "@types/node": "^24.9.0" }, "bin": { "electron": "cli.js", "install-electron": "install.js" } }, "sha512-axGNgd+yCTg+vi1VEGrQqAj9WVWkePKwbICSAvMiT2eTaxhij9a/xhBHD6rXV8wrlW9ZfJzE5+xg752ImxrmTw=="],

    "electron-builder": ["electron-builder@26.8.2", "", { "dependencies": { "app-builder-lib": "26.8.2", "builder-util": "26.8.1", "builder-util-runtime": "9.5.1", "chalk": "^4.1.2", "ci-info": "^4.2.0", "dmg-builder": "26.8.2", "fs-extra": "^10.1.0", "lazy-val": "^1.0.5", "simple-update-notifier": "2.0.0", "yargs": "^17.6.2" }, "bin": { "electron-builder": "cli.js", "install-app-deps": "install-app-deps.js" } }, "sha512-ieiiXPdgH3qrG6lcvy2mtnI5iEmAopmLuVRMSJ5j40weU0tgpNx0OAk9J5X5nnO0j9+KIkxHzwFZVUDk1U3aGw=="],

@@ -419,8 +426,6 @@

    "exponential-backoff": ["exponential-backoff@3.1.3", "", {}, "sha512-ZgEeZXj30q+I0EN+CbSSpIyPaJ5HVQD18Z1m+u1FXbAeT94mr1zw50q4q6jiiC447Nl/YTcIYSAftiGqetwXCA=="],

-    "extract-zip": ["extract-zip@2.0.1", "", { "dependencies": { "debug": "^4.1.1", "get-stream": "^5.1.0", "yauzl": "^2.10.0" }, "optionalDependencies": { "@types/yauzl": "^2.9.1" }, "bin": { "extract-zip": "cli.js" } }, "sha512-GDhU9ntwuKyGXdZBUgTIe+vXnWj0fppUEtMDL0+idd5Sta8TGpHssn/eusA9mrPr9qNDym6SxAYZjNvCn/9RBg=="],
-
    "extsprintf": ["extsprintf@1.4.1", "", {}, "sha512-Wrk35e8ydCKDj/ArClo1VrPVmN8zph5V4AtHwIuHhvMXsKf73UT3BOD+azBIW+3wOJ4FhEH7zyaJCFvChjYvMA=="],

    "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
@@ -429,8 +434,6 @@

    "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],

-    "fd-slicer": ["fd-slicer@1.1.0", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g=="],
-
    "fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],

    "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="],
@@ -443,11 +446,11 @@

    "flatted": ["flatted@3.4.2", "", {}, "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA=="],

-    "follow-redirects": ["follow-redirects@1.15.11", "", {}, "sha512-deG2P0JfjrTxl50XGCDyfI97ZGVCxIpfKYmfyrQ54n5FO/0gfIES8C/Psl6kWVDolizcaaxZJnTS0QSMxvnsBQ=="],
+    "follow-redirects": ["follow-redirects@1.16.0", "", {}, "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw=="],

    "foreground-child": ["foreground-child@3.3.1", "", { "dependencies": { "cross-spawn": "^7.0.6", "signal-exit": "^4.0.1" } }, "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw=="],

-    "form-data": ["form-data@4.0.5", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.2", "mime-types": "^2.1.12" } }, "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w=="],
+    "form-data": ["form-data@4.0.6", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "es-set-tostringtag": "^2.1.0", "hasown": "^2.0.4", "mime-types": "^2.1.35" } }, "sha512-vKatAh4SlVfgbv+YtmhiRjhEMJsYpsG1Y2rMQtR+SVSbytsSD1YGzDIcrAJmdFec88u/+VoGmxnl+80gL1tRCQ=="],

    "fs-extra": ["fs-extra@10.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ=="],

@@ -487,9 +490,9 @@

    "has-tostringtag": ["has-tostringtag@1.0.2", "", { "dependencies": { "has-symbols": "^1.0.3" } }, "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw=="],

-    "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+    "hasown": ["hasown@2.0.4", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A=="],

-    "hono": ["hono@4.12.8", "", {}, "sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A=="],
+    "hono": ["hono@4.12.28", "", {}, "sha512-YwUvVpSF7m1yOblFPrU3Hbo8XhPheBoiyfGuII6z19LnOr6JpDnyyp7LFNrfV56wS8tpvtBFGRISHN02pDdLOA=="],

    "hosted-git-info": ["hosted-git-info@4.1.0", "", { "dependencies": { "lru-cache": "^6.0.0" } }, "sha512-kyCuEOWjJqZuDbRHzL8V93NzQhwIB71oFWSyzVo+KPZI+pnQPPxucdkrOZvkLRnrf5URsQM+IJ09Dw29cRALIA=="],

@@ -499,7 +502,7 @@

    "http2-wrapper": ["http2-wrapper@1.0.3", "", { "dependencies": { "quick-lru": "^5.1.1", "resolve-alpn": "^1.0.0" } }, "sha512-V+23sDMr12Wnz7iTcDeJr3O6AIxlnvT/bmaAAAP/Xda35C90p9599p0F1eHR/N1KILWSoWVAiOMFjBBXaXSMxg=="],

-    "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
+    "https-proxy-agent": ["https-proxy-agent@5.0.1", "", { "dependencies": { "agent-base": "6", "debug": "4" } }, "sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA=="],

    "iconv-corefoundation": ["iconv-corefoundation@1.1.7", "", { "dependencies": { "cli-truncate": "^2.1.0", "node-addon-api": "^1.6.3" }, "os": "darwin" }, "sha512-T10qvkw0zz4wnm560lOEg0PovVqUXuOFhhHAkixw8/sycy7TJt7v/RrkEKEQnAw2viPSJu6iAkErxnzR0g8PpQ=="],

@@ -515,7 +518,7 @@

    "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],

-    "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="],
+    "ip-address": ["ip-address@10.2.0", "", {}, "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA=="],

    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],

@@ -537,7 +540,7 @@

    "jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],

-    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+    "js-yaml": ["js-yaml@4.3.0", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q=="],

    "json-buffer": ["json-buffer@3.0.1", "", {}, "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ=="],

@@ -663,8 +666,6 @@

    "pe-library": ["pe-library@0.4.1", "", {}, "sha512-eRWB5LBz7PpDu4PUlwT0PhnQfTQJlDDdPa35urV4Osrm0t0AqQFGn+UIkU3klZvwJ8KPO3VbBFsXquA6p6kqZw=="],

-    "pend": ["pend@1.2.0", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
-
    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],

    "picomatch": ["picomatch@4.0.4", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
@@ -685,7 +686,7 @@

    "proper-lockfile": ["proper-lockfile@4.1.2", "", { "dependencies": { "graceful-fs": "^4.2.4", "retry": "^0.12.0", "signal-exit": "^3.0.2" } }, "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA=="],

-    "proxy-from-env": ["proxy-from-env@1.1.0", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
+    "proxy-from-env": ["proxy-from-env@2.1.0", "", {}, "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA=="],

    "pump": ["pump@3.0.4", "", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],

@@ -767,7 +768,7 @@

    "supports-color": ["supports-color@7.2.0", "", { "dependencies": { "has-flag": "^4.0.0" } }, "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw=="],

-    "tar": ["tar@7.5.11", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-ChjMH33/KetonMTAtpYdgUFr0tbz69Fp2v7zWxQfYZX4g5ZN2nOBXm1R2xyA+lMIKrLKIoKAwFj93jE/avX9cQ=="],
+    "tar": ["tar@7.5.21", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-XdhtCvlMywwxpCW8YEq3lOXBJpUPTR2OHHcwLPO3HwsJqOHa2Ok/oJ7ruGzp+JrKoRPVCzJwAdEjqLW/vNRPHA=="],

    "temp": ["temp@0.9.4", "", { "dependencies": { "mkdirp": "^0.5.1", "rimraf": "~2.6.2" } }, "sha512-yYrrsWnrXMcdsnu/7YMYAofM1ktpL5By7vZhf15CrXijWWrEYZks5AXBudalfSWJLlnen/QUJUB5aoB0kqZUGA=="],

@@ -779,7 +780,7 @@

    "tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],

-    "tmp": ["tmp@0.2.5", "", {}, "sha512-voyz6MApa1rQGUxT3E+BK7/ROe8itEx7vD8/HEvt4xwXucvQ5G5oeEiHkmHZJuBO21RpOf+YYm9MOivj709jow=="],
+    "tmp": ["tmp@0.2.7", "", {}, "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw=="],

    "tmp-promise": ["tmp-promise@3.0.3", "", { "dependencies": { "tmp": "^0.2.0" } }, "sha512-RwM7MoPojPxsOBYnyd2hy0bxtIlVrihNs9pj5SUvY8Zz1sQcQG2tG1hSr8PDxfgEB8RNKDhqbIlroIarSNDNsQ=="],

@@ -793,7 +794,7 @@

    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],

-    "undici": ["undici@7.25.0", "", {}, "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ=="],
+    "undici": ["undici@7.28.0", "", {}, "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA=="],

    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],

@@ -823,7 +824,7 @@

    "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],

-    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
+    "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],

    "xmlbuilder": ["xmlbuilder@15.1.1", "", {}, "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg=="],

@@ -835,11 +836,13 @@

    "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],

-    "yauzl": ["yauzl@2.10.0", "", { "dependencies": { "buffer-crc32": "~0.2.3", "fd-slicer": "~1.1.0" } }, "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g=="],
-
    "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],

-    "@discordjs/rest/undici": ["undici@6.24.1", "", {}, "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA=="],
+    "@discordjs/rest/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],
+
+    "@discordjs/rest/undici": ["undici@6.27.0", "", {}, "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg=="],
+
+    "@discordjs/util/discord-api-types": ["discord-api-types@0.38.43", "", {}, "sha512-sSoBf/nK6m7BGtw65mi+QBuvEWaHE8MMziFLqWL+gT6ME/BLg34dRSVKS3Husx40uU06bvxUc3/X+D9Y6/zAbw=="],

    "@electron/asar/commander": ["commander@5.1.0", "", {}, "sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg=="],

@@ -863,6 +866,10 @@

    "@malept/flatpak-bundler/fs-extra": ["fs-extra@9.1.0", "", { "dependencies": { "at-least-node": "^1.0.0", "graceful-fs": "^4.2.0", "jsonfile": "^6.0.1", "universalify": "^2.0.0" } }, "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ=="],

+    "@npmcli/agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+
+    "@npmcli/agent/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
+
    "@npmcli/agent/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],

    "@types/cacheable-request/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
@@ -877,12 +884,12 @@

    "@types/ws/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],

-    "@types/yauzl/@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
-
    "app-builder-lib/@electron/get": ["@electron/get@3.1.0", "", { "dependencies": { "debug": "^4.1.1", "env-paths": "^2.2.0", "fs-extra": "^8.1.0", "got": "^11.8.5", "progress": "^2.0.3", "semver": "^6.2.0", "sumchecker": "^3.0.1" }, "optionalDependencies": { "global-agent": "^3.0.0" } }, "sha512-F+nKc0xW+kVbBRhFzaMgPy3KwmuNTYX1fx6+FxxoSnNgwYX6LD7AKBTWkU0MQ6IBoe7dz069CNkR673sPAgkCQ=="],

    "app-builder-lib/ci-info": ["ci-info@4.3.1", "", {}, "sha512-Wdy2Igu8OcBpI2pZePZ5oWjPC38tmDVx5WKUXKwlLYkA0ozo85sLsLvkBbBn/sZaSCMFOGZJ14fvW9t5/d7kdA=="],

+    "builder-util/https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="],
+
    "cacache/glob": ["glob@10.5.0", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^3.1.2", "minimatch": "^9.0.4", "minipass": "^7.1.2", "package-json-from-dist": "^1.0.0", "path-scurry": "^1.11.1" }, "bin": { "glob": "dist/esm/bin.mjs" } }, "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg=="],

    "cacache/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
@@ -893,8 +900,14 @@

    "electron-winstaller/fs-extra": ["fs-extra@7.0.1", "", { "dependencies": { "graceful-fs": "^4.1.2", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw=="],

+    "es-set-tostringtag/hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
    "foreground-child/signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],

+    "get-intrinsic/hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
+
+    "http-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+
    "lru-cache/yallist": ["yallist@4.0.0", "", {}, "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A=="],

    "minipass-flush/minipass": ["minipass@3.3.6", "", { "dependencies": { "yallist": "^4.0.0" } }, "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw=="],
@@ -909,6 +922,8 @@

    "postject/commander": ["commander@9.5.0", "", {}, "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ=="],

+    "socks-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+
    "tiny-async-pool/semver": ["semver@5.7.2", "", { "bin": { "semver": "bin/semver" } }, "sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g=="],

    "@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
@@ -929,14 +944,14 @@

    "@types/ws/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],

-    "@types/yauzl/@types/node/undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
-
    "app-builder-lib/@electron/get/env-paths": ["env-paths@2.2.1", "", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],

    "app-builder-lib/@electron/get/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],

    "app-builder-lib/@electron/get/semver": ["semver@6.3.1", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],

+    "builder-util/https-proxy-agent/agent-base": ["agent-base@7.1.4", "", {}, "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ=="],
+
    "cross-spawn/which/isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],

    "electron-winstaller/fs-extra/jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
@@ -0,0 +1,5 @@
+type: fixed
+area: overlay
+
+- Applied configured primary POS exclusions consistently to merged trailing quote-particle tokens, preserved annotations for supplementary-plane kanji, and stopped treating katakana punctuation as kana-only annotation noise.
+- Kept kanji vocabulary tagged `名詞/非自立` eligible for N+1 highlighting, consistent with frequency, JLPT, and vocabulary persistence.
@@ -0,0 +1,4 @@
+type: changed
+area: shortcuts
+
+- Made the clipboard-video playlist shortcut configurable through `shortcuts.appendClipboardVideoToQueue`.
@@ -0,0 +1,4 @@
+type: fixed
+area: anki
+
+- Prevented video startup from crashing when another process already owns the configured AnkiConnect proxy port, and added a notification explaining how to resolve the conflict.
@@ -0,0 +1,4 @@
+type: fixed
+area: app
+
+- Fixed "Service Crash" desktop notifications (KDE DrKonqi) after closing a video when running the Linux AppImage: the short-lived background bootstrap spawned a Chromium GPU child that outlived it (surviving `app.exit`) and died with SIGBUS at session end when the bootstrap's FUSE mount was finally released. The bootstrap now runs with the GPU in-process so it leaves no children behind, and the detached app's mount remains supervised until its Chromium children finish. Set `SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1` to disable the detached-app mount supervisor.
@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed `mpv.pauseUntilOverlayReady` releasing playback seconds before tokenization warmup finished: startup subtitle priming emits the current cue untokenized so the overlay can paint early, and that emission was treated as the autoplay-readiness signal as soon as the overlay window loaded. The autoplay gate now ignores untokenized subtitle payloads while tokenization warmup is pending, so playback resumes only after the first tokenized delivery (or the post-warmup release). Most visible when resuming mid-episode or when a subtitle cue starts within the first two seconds.
@@ -0,0 +1,7 @@
+type: internal
+area: tokenizer
+
+- Added a golden-file regression corpus for the tokenizer/annotation pipeline: recorded Yomitan backend responses and MeCab tokens replay through the real tokenizeSubtitle pipeline in bun tests without Electron or dictionaries.
+- Added `record-tokenizer-fixture:electron` script to capture new fixtures from a live Yomitan/MeCab session, with flags for known words, JLPT levels, and annotation toggles.
+- Seeded eleven fixtures covering the #147–#156 regression classes (grammar-helper suppression, lexical くれる, kanji non-independent nouns, N+1 targeting, reading collisions, unparsed runs, ordinal/honorific prefixes).
+- Added `compare-yomitan-api:electron` script that diffs SubMiner tokenization against a stock Yomitan instance via the yomitan-api bridge (segmentation, readings, headword forms).
@@ -0,0 +1,5 @@
+type: added
+area: launcher
+
+- After a watch-history episode ends or mpv closes, the fzf or rofi launcher returns to that series with options to play the previous episode, rewatch, play the next episode, select another episode, or quit SubMiner. Previous and Next continue across season directories.
+- The action menu shown right after picking a series from `subminer -H` now also offers the previous episode, matching the menu shown after playback.
@@ -0,0 +1,4 @@
+type: internal
+area: overlay
+
+- Consolidated renderer modal state handling into a descriptor registry.
@@ -0,0 +1,4 @@
+type: internal
+area: release
+
+- Consolidated pull request, stable release, and prerelease quality checks in one reusable workflow, with Lua mpv plugin tests and blocking high-severity dependency audits running in every gate.
@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Rofi menu prompts now keep a space between the prompt text and the input field instead of running into the search placeholder.
@@ -0,0 +1,5 @@
+type: fixed
+area: stats
+
+- Validated nested and legacy AnkiConnect settings after splitting the resolver, preserving valid modern overrides while warning and falling back for invalid primitive values.
+- Hardened stats routes against malformed IDs and static paths, stalled AniList searches, word-mining media collisions, missing Yomitan bridges, and throwing timing observers.
@@ -0,0 +1,8 @@
+type: added
+area: sync
+
+- Added cross-machine immersion sync for stats and watch history over SSH, available as a window (**Sync Stats & History** in the tray menu, or `subminer sync --ui`) and as a command (`subminer sync <host>`, with `--push` / `--pull` for one-way insert-only transfers). The window keeps saved devices with per-host direction, one-click sync with live stage-by-stage progress and separate merge summaries for each machine, connection testing for first-time setup, cancellable runs while the app/stats server/playback is active, and manual database snapshots (create/merge/reveal/delete, stored in `/tmp/subminer-db-snapshots/` by default). Hosts with auto-sync enabled sync in the background on a configurable interval, including during playback, with results reported as overlay notifications; hosts synced from the CLI are remembered in `<config dir>/sync-hosts.json` and appear in the window automatically.
+- Merges are an insert-only union keyed on session UUIDs / video keys / series title keys, so re-syncing is idempotent and nothing is double-counted: each side snapshots its database (`VACUUM INTO`) from a consistent WAL point, snapshots are exchanged with `scp`, and each machine merges the other's data transactionally. Lifetime totals and daily/monthly rollups are updated incrementally (history older than the session retention window is preserved), unfinished sessions are excluded until a later sync sees them finalized, and remote-only historical rollups are copied only when they do not conflict with retained local session history. Sync aborts on stats schema version mismatches and refuses to run while the stats daemon or a live mpv session is active (`--force` overrides).
+- The sync engine runs only inside the app: the sync window and the `subminer sync` command both delegate to `SubMiner --sync-cli` (headless, works over SSH with no display), so neither machine needs bun or the command-line launcher. A remote machine only needs SubMiner itself, found automatically as the app binary or via the launcher proxy.
+- Windows remotes are supported: sync detects the remote shell (POSIX, cmd, or PowerShell) and manages remote temp files through SubMiner itself (`sync --make-temp` / `--remove-temp`) instead of `mktemp` / `rm`, so a Windows machine with the built-in OpenSSH Server works as a sync remote, found in its default Windows install location automatically.
+- Added supporting flags: `subminer sync <host> --check` tests the SSH connection and remote launcher availability without syncing, `subminer sync --snapshot <file>` and `--merge <file>` expose the underlying steps for manual transfers, and `subminer sync --json` emits machine-readable NDJSON progress (the protocol the sync window consumes).
@@ -0,0 +1,4 @@
+type: added
+area: overlay
+
+- Added TsukiHime subtitle downloads for the current video, with Japanese primary and configured secondary-language tracks loaded directly into mpv.
@@ -0,0 +1,4 @@
+type: internal
+area: stats
+
+- Removed the unused stats IPC data transport and unified the stats dashboard's HTTP wire types with the backend contract.
@@ -205,11 +205,13 @@
    "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
    "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
-    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
+    "toggleNotificationHistory": "CommandOrControl+N", // Accelerator that toggles the overlay notification history panel.
+    "appendClipboardVideoToQueue": "CommandOrControl+A" // Accelerator that appends a video path from the clipboard to the mpv playlist.
  }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.

  // ==========================================
@@ -611,6 +613,16 @@
    "maxEntryResults": 10 // Maximum Jimaku search results returned.
  }, // Jimaku API configuration and defaults.

+  // ==========================================
+  // TsukiHime
+  // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
+  // ==========================================
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+
  // ==========================================
  // YouTube Playback Settings
  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
@@ -327,6 +327,7 @@ const sidebar: DefaultTheme.SidebarItem[] = [
      { text: 'Jellyfin', link: '/jellyfin-integration' },
      { text: 'YouTube', link: '/youtube-integration' },
      { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'TsukiHime', link: '/tsukihime-integration' },
      { text: 'AniList', link: '/anilist-integration' },
      { text: 'AniSkip', link: '/aniskip-integration' },
      { text: 'Character Dictionary', link: '/character-dictionary' },
@@ -41,7 +41,7 @@ The update flow:
 1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename and path. Season folders such as `Season 2` are treated as a strong season signal. SubMiner tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
 2. **AniList search** -- The detected title is searched against the AniList GraphQL API. For season 2 and later files, SubMiner searches the season-specific title first, then falls back to the base title. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
 3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
-4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
+4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`, or `COMPLETED` when the watched episode is the final episode of the season (the "already at this progress" skip is bypassed for the final episode so completion still lands).

 ## Update Queue and Retry

@@ -81,7 +81,6 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w
    "enabled": true,
    "accessToken": "",
    "characterDictionary": {
-      "enabled": false,
      "maxLoaded": 3,
      "profileScope": "all",
      "collapsibleSections": {
@@ -99,10 +98,12 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w
 | `enabled`                                   | `true`, `false`     | Enable AniList post-watch progress updates (default: `false`)                                                |
 | `accessToken`                               | string              | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
 | `characterDictionary.maxLoaded`             | number              | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
+| `characterDictionary.refreshTtlHours`       | number              | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                        |
+| `characterDictionary.evictionPolicy`        | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                               |
 | `characterDictionary.profileScope`          | `"all"`, `"active"` | Apply dictionary to all Yomitan profiles or only the active one                                              |
 | `characterDictionary.collapsibleSections.*` | `true`, `false`     | Control which dictionary entry sections start expanded                                                       |

-See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format. Character dictionary sync follows `subtitleStyle.nameMatchEnabled`.
+There is no `characterDictionary.enabled` key: character dictionary sync is enabled by `subtitleStyle.nameMatchEnabled`. See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.

 ## CLI Commands

@@ -6,12 +6,12 @@ Intro detection runs in the SubMiner app over the mpv IPC socket. It is availabl

 ## Setup

-AniSkip is opt-in. Enable it in your config:
+AniSkip is enabled by default. Disable it or change the skip key in your config:

 ```jsonc
 {
  "mpv": {
-    "aniskipEnabled": true,
+    "aniskipEnabled": true, // default: true
    "aniskipButtonKey": "TAB",
  },
 }
@@ -37,7 +37,9 @@ On each local file load:
 4. If an interval is found, SubMiner adds `AniSkip Intro Start` and `AniSkip Intro End` chapter markers to the current file and binds the skip key (`mpv.aniskipButtonKey`, default `TAB`).
 5. At the start of the intro, an OSD prompt appears for 3 seconds: `You can skip by pressing TAB` (reflects your configured key). Pressing the key at any point during the intro seeks to the intro end.

-Results are cached per file for the app session. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.
+When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback skip trigger.
+
+Results are cached per file for the app session; only definitive "no intro found" results are cached, so transient lookup failures are retried on the next file load. Reload detection is also handled: if mpv reloads the same file, SubMiner re-applies the chapter markers without a new API lookup.

 ## Triggering from mpv

@@ -37,7 +37,7 @@ In both modes, the enrichment workflow is the same:
 4. Fills the translation field from the secondary subtitle or AI.
 5. Writes metadata to the miscInfo field.

-Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it uses Yomitan's current mining deck when available; otherwise it searches all decks. In Settings, the AnkiConnect deck dropdown auto-fills and persists Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect.
+Polling mode uses the query `"deck:<ankiConnect.deck>" added:1` to find recently added cards. If no deck is configured, it searches all decks (`added:1`). In Settings, the AnkiConnect deck dropdown auto-fills and persists Yomitan's current mining deck when available, then falls back to the decks reported by AnkiConnect; stats-dashboard mining also falls back to Yomitan's mining deck when `ankiConnect.deck` is empty.
 Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.

 ### Proxy Mode Setup (Yomitan / Texthooker)
@@ -56,12 +56,12 @@ Known-word sync scope is controlled by `ankiConnect.knownWords.decks`.

 Then point Yomitan/clients to `http://127.0.0.1:8766` instead of `8765`.

-When SubMiner loads the bundled Yomitan extension, it also attempts to update the **default Yomitan profile** (`profiles[0].options.anki.server`) to the active SubMiner endpoint:
+When SubMiner loads the bundled Yomitan extension, it also attempts to update the **currently active Yomitan profile**'s Anki server to the active SubMiner endpoint (falling back to `profiles[0]` if the active-profile index is invalid):

 - proxy URL when `ankiConnect.proxy.enabled` is `true`
 - direct `ankiConnect.url` when proxy mode is disabled

-To avoid clobbering custom setups, this auto-update only changes the default profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).
+To avoid clobbering custom setups, this auto-update only changes the profile when its current server is blank or the stock Yomitan default (`http://127.0.0.1:8765`).

 For browser-based Yomitan or other external clients (for example Texthooker in a normal browser profile), set their Anki server to the same proxy URL separately: `http://127.0.0.1:8766` (or your configured `proxy.host` + `proxy.port`).

@@ -81,7 +81,7 @@ In Yomitan, go to Settings → Profile and:
 3. Set server to `http://127.0.0.1:8766` (or your configured proxy URL).
 4. Save and make that profile active when using SubMiner.

-This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets `profiles[0]` when it is blank or still default.
+This is only for non-bundled, external/browser Yomitan or other clients. The bundled profile auto-update logic only targets the active profile when its server is blank or still default.

 ### Proxy Troubleshooting (quick checks)

@@ -101,10 +101,11 @@ curl -sS http://127.0.0.1:8766 \
  -d '{"action":"version","version":2}'
 ```

-3. Check both log sinks:
+3. Check the log sinks in `~/.config/SubMiner/logs/`:

- Launcher/mpv-integrated log: `~/.cache/SubMiner/mp.log`
- App runtime log: `~/.config/SubMiner/logs/SubMiner-YYYY-MM-DD.log`
+- App runtime log: `app-YYYY-MM-DD.log`
+- Launcher log: `launcher-YYYY-MM-DD.log`
+- mpv log: `mpv-YYYY-MM-DD.log`

 4. Ensure config JSONC is valid and logging shape is correct:

@@ -133,7 +134,9 @@ SubMiner maps its data to your Anki note fields. Configure these under `ankiConn
 }
 ```

-Field names must match your Anki note type exactly (case-sensitive). If a configured field does not exist on the note type, SubMiner skips it without error.
+Field names are matched against your Anki note type case-insensitively (an exact match wins, then a lowercase comparison). If a configured field does not exist on the note type, SubMiner skips it without error.
+
+Two related options live alongside `fields`: `ankiConnect.deck` (target deck; empty falls back as described above) and `ankiConnect.tags` (tags added to mined cards, default `["SubMiner"]`; set `[]` to disable tagging). The `miscInfo` content is controlled by `ankiConnect.metadata.pattern` (default `[SubMiner] %f (%t)`; tokens: `%f` filename, `%F` filename with extension, `%t` timestamp, `%T` timestamp with milliseconds, `<br>` newline).

 ### Minimal Config

@@ -169,7 +172,7 @@ Audio is extracted from the video file using the subtitle's start and end timest
 }
 ```

-Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness. Changing this setting applies to the next extraction without restarting SubMiner.
+Output format: MP3 at 44100 Hz. If the video has multiple audio streams, SubMiner uses the active stream. Generated sentence audio is loudness-normalized to -23 LUFS by default during extraction; set `normalizeAudio` to `false` to keep raw source loudness. When subtitle timing is missing, clips fall back to `media.fallbackDuration` seconds (default `3`). Changing these settings applies to the next extraction without restarting SubMiner.

 `mirrorMpvVolume` is also enabled by default. Immediately before extracting each playback-overlay card's audio, SubMiner reads mpv's numeric `volume` and applies mpv's cubic software-volume curve after loudness normalization. For example, mpv volume `50` produces `0.5³ = 0.125` gain. Amplified output above mpv volume `100` is limited to a `-1 dBFS` ceiling before MP3 encoding to prevent clipping. It ignores mpv's separate `mute` state. If the volume property is missing, invalid, or unavailable, extraction continues with unity scaling; disabling this option skips the query and volume filter. Changing this setting applies to the next extraction without restarting SubMiner. YouTube cards queued for a background media-cache download retain the volume captured when the card was mined. Stats-dashboard mining does not currently have access to the active mpv property client, so it does not apply mpv volume scaling.

@@ -186,8 +189,8 @@ A single frame is captured at the current playback position.
    "imageType": "static",
    "imageFormat": "jpg",        // "jpg", "png", or "webp"
    "imageQuality": 92,          // 1–100
-    "imageMaxWidth": null,       // optional, preserves aspect ratio
-    "imageMaxHeight": null
+    "imageMaxWidth": 0,          // 0 = preserve source resolution
+    "imageMaxHeight": 0
  }
 }
 ```
@@ -203,13 +206,13 @@ Instead of a static screenshot, SubMiner can generate an animated AVIF covering
    "imageType": "avif",
    "animatedFps": 10,
    "animatedMaxWidth": 640,
-    "animatedMaxHeight": null,
+    "animatedMaxHeight": 0,      // 0 = preserve aspect ratio
    "animatedCrf": 35            // 0–63, lower = better quality
  }
 }
 ```

-Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds.
+Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`) in your FFmpeg build. Generation timeout is 60 seconds. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing word-audio duration, so the motion starts together with the sentence audio.

 ### Behavior Options

@@ -220,6 +223,7 @@ Animated AVIF requires an AV1 encoder (`libaom-av1`, `libsvtav1`, or `librav1e`)
    "overwriteImage": true,         // replace existing image, or append
    "mediaInsertMode": "append",    // "append" or "prepend" to field content
    "autoUpdateNewCards": true,     // auto-update when new card detected
+    "highlightWord": true,          // bold the mined word inside the sentence field
    "notificationType": "overlay"   // "overlay", "system", "both", or "none"
  }
 }
@@ -269,14 +273,14 @@ The built-in translation request asks for English output by default. Customize t
 SubMiner can create standalone sentence cards (without a word/expression) using a separate note type. This is designed for use with [Lapis](https://github.com/donkuri/Lapis) and similar sentence-focused note types.

 ::: warning Required config
-Sentence card creation and audio card marking both require `ankiConnect.isLapis.enabled: true` and a valid `sentenceCardModel` pointing to your Lapis/Kiku note type. Without this, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
+Sentence card creation and audio card marking require a non-empty `ankiConnect.isLapis.sentenceCardModel` naming a note type that exists in Anki (default: `"Lapis"`). If the model is empty or missing, the `Ctrl/Cmd+S` and `Ctrl/Cmd+Shift+A` shortcuts will not create cards.
 :::

 ```jsonc
 "ankiConnect": {
  "isLapis": {
    "enabled": true,
-    "sentenceCardModel": "Japanese sentences"
+    "sentenceCardModel": "Lapis" // default; point at your Lapis/Kiku note type
  }
 }
 ```
@@ -303,25 +307,28 @@ When you mine the same word multiple times, SubMiner can merge the cards instead

 **Disabled** (`"disabled"`): No duplicate detection. Each card is independent.

-**Auto** (`"auto"`): When a duplicate expression is found, SubMiner merges the new card into the existing one automatically. Both sentences, audio clips, and images are preserved, and exact duplicate values are collapsed to one entry. If `deleteDuplicateInAuto` is true, the new card is deleted after merging.
+**Auto** (`"auto"`): When a duplicate expression is found, SubMiner merges the new card into the existing one automatically. Both cards' sentences, audio clips, and images are preserved as grouped entries. If `deleteDuplicateInAuto` is true, the new card is deleted after merging.

 **Manual** (`"manual"`): A modal appears in the overlay showing both cards. You choose which card to keep, preview the merge result, then confirm. The modal has a 90-second timeout, after which it cancels automatically.

 ### What Gets Merged

-| Field    | Merge behavior                                                  |
-| -------- | --------------------------------------------------------------- |
-| Sentence | Both sentences preserved (exact duplicate text is deduplicated) |
-| Audio    | Both `[sound:...]` entries kept (exact duplicates deduplicated) |
-| Image    | Both images kept (exact duplicates deduplicated)                |
+| Field    | Merge behavior                          |
+| -------- | ---------------------------------------- |
+| Sentence | Both cards' sentences kept as grouped entries |
+| Audio    | Both cards' `[sound:...]` entries kept  |
+| Image    | Both cards' images kept                 |
+
+Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.

 ### Keyboard Shortcuts in the Modal

-| Key       | Action                             |
-| --------- | ---------------------------------- |
-| `1` / `2` | Select card 1 or card 2 to keep    |
-| `Enter`   | Confirm selection                  |
-| `Esc`     | Cancel (keep both cards unchanged) |
+| Key         | Action                             |
+| ----------- | ---------------------------------- |
+| `1` / `2`   | Select card 1 or card 2 to keep    |
+| `Enter`     | Confirm selection                  |
+| `Backspace` | Go back from the merge preview     |
+| `Esc`       | Cancel (keep both cards unchanged) |

 ## Full Config Example

@@ -331,8 +338,10 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
    "enabled": true,
    "url": "http://127.0.0.1:8765",
    "pollingRate": 3000,
+    "deck": "",
+    "tags": ["SubMiner"],
    "proxy": {
-      "enabled": false,
+      "enabled": true, // default
      "host": "127.0.0.1",
      "port": 8766,
      "upstreamUrl": "http://127.0.0.1:8765",
@@ -363,10 +372,13 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
      "autoUpdateNewCards": true,
      "notificationType": "overlay",
    },
+    "metadata": {
+      "pattern": "[SubMiner] %f (%t)",
+    },
    "ai": {
      "enabled": false,
-      "model": "openai/gpt-4o-mini",
-      "systemPrompt": "Translate mined sentence text only.",
+      "model": "", // e.g. "openai/gpt-4o-mini"
+      "systemPrompt": "",
    },
    "isKiku": {
      "enabled": false,
@@ -375,7 +387,7 @@ When you mine the same word multiple times, SubMiner can merge the cards instead
    },
    "isLapis": {
      "enabled": false,
-      "sentenceCardModel": "Japanese sentences",
+      "sentenceCardModel": "Lapis",
    },
  },
  "ai": {
@@ -6,7 +6,7 @@ SubMiner is split into three cooperating runtimes:

 - Electron desktop app (`src/`) for overlay/UI/runtime orchestration.
 - Launcher CLI (`launcher/`) for mpv/app command workflows.
- mpv Lua plugin (`plugin/subminer/init.lua` + module files) for player-side controls and IPC handoff.
+- mpv Lua plugin (`plugin/subminer/main.lua` + module files) for player-side controls and IPC handoff.

 Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services.

@@ -24,13 +24,14 @@ Within the desktop app, `src/main.ts` is a composition root that wires small run

 ```text
 launcher/                 # Standalone CLI launcher wrapper and mpv helpers
-  commands/               # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough)
+  commands/               # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough/
+                          #   dictionary/history/logs/stats/update)
  config/                 # Launcher config parsers + CLI parser builder
  main.ts                 # Launcher entrypoint and command dispatch
 plugin/
-  subminer/               # Modular mpv plugin (init · main · bootstrap · lifecycle · process
+  subminer/               # Modular mpv plugin (main · init · bootstrap · lifecycle · process
                          #   state · messages · hover · ui · options · environment · log
-                          #   binary)
+                          #   binary · session_bindings · version)
 src/
  ai/                      # AI translation provider utilities (client, config)
  main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
@@ -38,6 +39,7 @@ src/
  preload.ts               # Electron preload bridge
  types.ts                 # Shared type definitions
  main/                    # Main-process composition/runtime adapters
+    boot/                  # Pre-ready boot helpers
    app-lifecycle.ts       # App lifecycle + app-ready runtime runner factories
    character-dictionary-runtime.ts # Character-dictionary orchestration/public runtime API
    cli-runtime.ts         # CLI command runtime service adapters
@@ -71,17 +73,17 @@ src/
    resolve/               # Domain-specific config resolution pipeline stages
  shared/ipc/              # Cross-process IPC channel constants + payload validators
  renderer/                # Overlay renderer (modularized UI/runtime)
-    handlers/              # Keyboard/mouse interaction modules
-    modals/                # Jimaku/Kiku/subsync/runtime-options/session-help modals
+    handlers/              # Keyboard/mouse/gamepad interaction modules
+    modals/                # Modal flows (Jimaku, Kiku, subsync, runtime options, session help,
+                           #   character dictionary, playlist browser, subtitle sidebar,
+                           #   YouTube track picker, controller config/debug/select)
    positioning/           # Subtitle position controller (drag-to-reposition)
+  settings/                # Settings window UI (model, controls, markup)
+  types/                   # Domain type modules (anki, config, integrations, ...)
  window-trackers/         # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS, Windows)
  jimaku/                  # Jimaku API integration helpers
  subsync/                 # Subtitle sync (alass/ffsubsync) helpers
-  subtitle/                # Subtitle processing utilities
-  tokenizers/              # Tokenizer implementations
  anki-integration/        # AnkiConnect proxy server + note-update enrichment workflow
-  token-mergers/           # Token merge strategies
-  translators/             # AI translation providers
 ```

 ### Service Layer (`src/core/services/`)
@@ -92,7 +94,7 @@ src/
 - **Mining + Anki/Jimaku runtime:** `mining.ts`, `field-grouping.ts`, `field-grouping-overlay.ts`, `anki-jimaku.ts`, `anki-jimaku-ipc.ts`
 - **Subtitle/token pipeline:** `subtitle-processing-controller.ts`, `subtitle-position.ts`, `subtitle-ws.ts`, `tokenizer.ts` + `tokenizer/*` stage modules (including `parser-enrichment-worker-runtime.ts` for async MeCab enrichment and `yomitan-parser-runtime.ts`)
 - **Integrations:** `jimaku.ts`, `subsync.ts`, `subsync-runner.ts`, `texthooker.ts`, `jellyfin.ts`, `jellyfin-remote.ts`, `discord-presence.ts`, `yomitan-extension-loader.ts`, `yomitan-settings.ts`
- **Anki integration:** `anki-integration.ts`, `anki-integration/anki-connect-proxy.ts` (local proxy for push-based auto-enrichment), `anki-integration/note-update-workflow.ts`
+- **Anki integration (repo `src/` root, not under `core/services/`):** `src/anki-integration.ts`, `src/anki-integration/anki-connect-proxy.ts` (local proxy for push-based auto-enrichment), `src/anki-integration/note-update-workflow.ts`
 - **Config/runtime controls:** `config-hot-reload.ts`, `runtime-options-ipc.ts`, `cli-command.ts`, `startup.ts`
 - **Domain submodules:** `anilist/*` (token/update queue/updater), `immersion-tracker/*` (storage/session/metadata/query/reducer)

@@ -116,12 +118,19 @@ src/renderer/
  handlers/
    keyboard.ts            # Keybindings, chord handling, modal key routing
    mouse.ts               # Hover/drag behavior, selection + observer wiring
+    gamepad-controller.ts  # Gamepad/controller input handling
+    controller-binding-capture.ts # Controller binding capture flow
  modals/
    jimaku.ts              # Jimaku modal flow
    kiku.ts                # Kiku field-grouping modal flow
    runtime-options.ts     # Runtime options modal flow
    session-help.ts        # Keyboard shortcuts/help modal flow
    subsync.ts             # Manual subsync modal flow
+    character-dictionary.ts # Character dictionary modal flow
+    playlist-browser.ts    # Playlist browser modal flow
+    subtitle-sidebar.ts    # Subtitle sidebar modal flow
+    youtube-track-picker.ts # YouTube subtitle track picker
+    controller-*.ts        # Controller config/debug/select modals
  utils/
    dom.ts                 # Required DOM lookups + typed handles
    platform.ts            # Layer/platform capability detection
@@ -130,7 +139,7 @@ src/renderer/
 ### Launcher + Plugin Runtimes

 - `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff.
- `plugin/subminer/init.lua` runs inside mpv and loads modular Lua files: `main.lua` (orchestration), `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.
+- `plugin/subminer/main.lua` is the mpv entrypoint: it sets up the module path and loads `init.lua`, a thin shim that boots the modular Lua files: `bootstrap.lua` (startup), `lifecycle.lua` (connect/disconnect), `process.lua` (process management), `state.lua` (shared state), `messages.lua` (IPC), `hover.lua` (hover-token highlight rendering), `ui.lua` (OSD rendering), `options.lua` (config), `environment.lua` (detection), `log.lua` (logging), `binary.lua` (path resolution), `session_bindings.lua` (configurable session keybindings), `version.lua` (version metadata). AniSkip intro detection lives in the SubMiner app (`src/main/runtime/aniskip-runtime.ts`), which drives mpv chapters and the skip key over the IPC socket.

 ## Flow Diagram

@@ -313,7 +322,7 @@ The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc
 - **Critical-path init:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs strict config reload, resolves keybindings, creates the `MpvIpcClient` (which immediately connects and subscribes to mpv subtitle/playback properties via `observe_property`), and initializes the `RuntimeOptionsManager`, `SubtitleTimingTracker`, and `ImmersionTrackerService`.
 - **Overlay runtime:** `initializeOverlayRuntime()` creates the primary overlay window (interactive Yomitan lookups and subtitle rendering), registers global shortcuts, and sets up bounds tracking via the active window tracker. mpv subtitle suppression is handled by a dedicated `overlay-mpv-sub-visibility` service.
 - **Background warmups:** Non-critical services are launched asynchronously: MeCab tokenizer check (with async worker thread), Yomitan extension load, JLPT + frequency dictionary prewarm, optional Jellyfin remote session, Discord presence service, AniList token refresh, and optional AnkiConnect proxy server. Warmup coverage is configurable through `startupWarmups` (including low-power mode that defers all but Yomitan).
- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, overlay shortcuts, and hot-reload notifications route through runtime handlers/composers. Subtitle text flows through `SubtitlePipeline` (normalize → tokenize → merge), and results are sent to the main overlay renderer and modal surfaces.
+- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, overlay shortcuts, and hot-reload notifications route through runtime handlers/composers. Subtitle text flows through the `SubtitleProcessingController` (normalize → tokenize → merge), and results are sent to the main overlay renderer and modal surfaces.
 - **Shutdown:** `onWillQuitCleanup` destroys tray + config watcher, unregisters shortcuts, stops WebSocket + texthooker servers, closes the mpv socket + flushes OSD log, stops the window tracker, closes the Yomitan parser window, flushes the immersion tracker (SQLite), stops Jellyfin/Discord services, stops the AnkiConnect proxy server, and cleans Anki/AniList state.

 ```mermaid
@@ -380,7 +389,7 @@ flowchart TB

 ## Subtitle Prefetch Pipeline

-SubMiner can pre-tokenize upcoming subtitle lines before they appear on screen. When an external subtitle file (SRT, VTT, or ASS) is detected on the active track, the `SubtitlePrefetchService` parses all cues via the `SubtitleCueParser`, identifies a priority window of upcoming lines based on the current playback position, and tokenizes them in the background through the same pipeline used for live subtitles. Results are stored directly into the `SubtitleProcessingController` cache, so when a subtitle actually appears during playback, it hits a warm cache and renders in ~30-50ms instead of ~200-320ms.
+SubMiner can pre-tokenize upcoming subtitle lines before they appear on screen. When an external subtitle file (SRT, VTT, or ASS) is detected on the active track, the `SubtitlePrefetchService` parses all cues via the subtitle cue parser (`subtitle-cue-parser.ts`), identifies a priority window of upcoming lines based on the current playback position, and tokenizes them in the background through the same pipeline used for live subtitles. Results are stored directly into the `SubtitleProcessingController` cache, so when a subtitle actually appears during playback, it hits a warm cache and renders in ~30-50ms instead of ~200-320ms.

 The prefetcher yields to live subtitle processing (which always takes priority over background work) and re-computes its priority window on seek. Cache invalidation events (e.g. marking a word as known) trigger re-prefetching of the current window to keep results fresh.

@@ -134,7 +134,7 @@ Each character entry in the Yomitan dictionary includes structured content:

 - **Name** - the matched Japanese name form
 - **Known names** - generated non-honorific Japanese aliases for that character, excluding raw romanized/English aliases from lookup results
- **Role badge** - color-coded by role: main (score 100), supporting (90), side (80), background (70)
+- **Role badge** - color-coded by role: main / "Protagonist" (score 100), primary / "Main Character" (75), side / "Side Character" (50), appears / "Minor Role" (25). AniList's MAIN maps to main, SUPPORTING to primary, and BACKGROUND to side.
 - **Portrait** - character image from AniList, embedded in the ZIP
 - **Description** - biography text from AniList (collapsible)
 - **Character information** - age, birthday, gender, blood type (collapsible)
@@ -166,7 +166,7 @@ These phases are emitted through the configured notification surface. Some phase

 1. **checking** - Is there already a cached snapshot for this media ID?
 2. **generating** - No cache hit: fetch characters from AniList GraphQL, download portraits (250ms throttle between image requests), save snapshot JSON.
-3. **syncing** - Add the media ID to the most-recently-used list. Evict old entries beyond `maxLoaded`.
+3. MRU update (no notification) - add the media ID to the most-recently-used list and evict old entries beyond `maxLoaded`.
 4. **building** - Merge active snapshots into a single Yomitan ZIP. A SHA-1 revision hash is computed from the media set - if it matches the previously imported revision, the import is skipped.
 5. **importing** - Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
 6. **ready** - Dictionary is live. Character names will match on the next subtitle line.
@@ -175,12 +175,14 @@ These phases are emitted through the configured notification surface. Some phase

 ```jsonc
 {
-  "activeMediaIds": [170942, 163134, 154587],
+  "activeMediaIds": ["170942 - Frieren", "163134 - ...", "154587 - ..."],
  "mergedRevision": "a1b2c3d4e5f6",
  "mergedDictionaryTitle": "SubMiner Character Dictionary",
 }
 ```

+(Entries are `"<mediaId> - <title>"` label strings; bare numeric IDs from older versions are still read.)
+
 The `maxLoaded` setting (default: 3) controls how many media snapshots stay in the active set. When you start a 4th title, the oldest is evicted and the merged dictionary is rebuilt without it.

 ## Manual Generation
@@ -228,7 +230,7 @@ Manual selections are stored in `character-dictionaries/anilist-overrides.json`
 Open the manager with `Ctrl/Cmd+D` (`shortcuts.openCharacterDictionaryManager`). The manager shows the merged dictionary's active MRU entries, marks the current anime, and lets you adjust eviction priority for the other loaded entries.

 - **Remove** drops a non-current entry from the active merged dictionary and rebuilds/imports once.
- **Up/Down** changes MRU order for future eviction without rebuilding.
+- **Up/Down** changes MRU order for future eviction; the merged dictionary is rebuilt and re-imported after a reorder.
 - **Override** opens the AniList selector for that entry's title so you can replace a saved loaded entry.

 The current anime cannot be removed while you are watching it; it stays loaded until playback changes.
@@ -250,13 +252,13 @@ character-dictionaries/
    m170942-va67890.jpg       # Voice actor portrait
 ```

-**Snapshot format** (v17): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images.
+**Snapshot format** (v19, `CHARACTER_DICTIONARY_FORMAT_VERSION`): each snapshot contains the media ID, title, entry count, timestamp, an array of Yomitan term entries, and base64-encoded images. Snapshots with a different format version are regenerated.

 **ZIP structure** follows the Yomitan dictionary format:

 ```text
 merged.zip
-  index.json                  # { title, revision, format: 3, author: "SubMiner" }
+  index.json                  # { title, revision, format: 3, author: "SubMiner", description }
  tag_bank_1.json             # Tag definitions
  term_bank_1.json            # Up to 10,000 terms per bank
  term_bank_2.json
@@ -46,12 +46,13 @@ The Settings window groups options by workflow instead of mirroring the raw conf
 - Appearance
 - Behavior
 - Mining & Anki
- Playback & Sources
 - Input
 - Integrations
 - Tracking & App
 - Advanced

+Playback-related fields live as sections inside these groups (for example "Playback Behavior" under **Behavior** and "mpv Playback" / "YouTube Playback Settings" under **Integrations**).
+
 Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Behavior** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`. Anki-aware fields can query AnkiConnect for deck names, note types, and field names. The AnkiConnect deck field also reads Yomitan's current mining deck and persists it into an empty setting when one is found. Stats mining also uses Yomitan's current mining deck when `ankiConnect.deck` is empty. Keybinding fields use click-to-learn controls instead of raw text boxes.

 The Settings window preserves existing JSONC comments, trailing commas, and unrelated keys. Resetting a field removes the explicit config path so the built-in default applies.
@@ -95,9 +96,11 @@ On macOS, these validation warnings also open a native dialog with full details
 SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.

 Hot-reloadable settings include subtitle appearance, sidebar controls, keybindings,
-logging level, selected source-language preferences, Jimaku/Subsync settings, and
-the Anki deck, known-word, N+1, field, sentence-card, and Kiku options listed
-in the reference tables below.
+shortcuts, notifications, logging level, selected source-language preferences,
+Jimaku/Subsync settings, AniSkip settings (`mpv.aniskipEnabled`, `mpv.aniskipButtonKey`),
+stats keys (`stats.toggleKey`, `stats.markWatchedKey`), the secondary-subtitle default
+mode, and the Anki deck, known-word, N+1, field, sentence-card, AI, and Kiku options
+listed in the reference tables below.

 When these values change, SubMiner applies them live. Invalid config edits are rejected and the previous valid runtime config remains active.

@@ -482,6 +485,8 @@ Configure the parsed-subtitle sidebar modal.
 | `autoScroll`                | boolean | Keep the active cue in view while playback advances                                                     |
 | `subtitleSidebar.css`       | object  | CSS declaration object applied to the sidebar. Use CSS properties plus sidebar custom properties below. |

+Direct style keys are also available under `subtitleSidebar` and map to the same visuals as the CSS custom properties: `maxWidth` (default `420`), `opacity` (`0.95`), `backgroundColor`, `textColor`, `fontFamily`, `fontSize` (`16`), `timestampColor`, `activeLineColor`, `activeLineBackgroundColor`, and `hoverLineBackgroundColor`.
+
 Sidebar CSS custom properties:

 | CSS Property                                 | Default                     | Description                  |
@@ -498,7 +503,7 @@ The sidebar is only available when the active subtitle source has been parsed in

 For full details on layout modes, behavior, and the keyboard shortcut, see the [Subtitle Sidebar](/subtitle-sidebar) page.

-`jlptColors` keys are:
+`subtitleStyle.jlptColors` keys are:

 | Key  | Default   | Description             |
 | ---- | --------- | ----------------------- |
@@ -508,12 +513,6 @@ For full details on layout modes, behavior, and the keyboard shortcut, see the [
 | `N4` | `#8bd5ca` | JLPT N4 underline color |
 | `N5` | `#8aadf4` | JLPT N5 underline color |

-**Image Quality Notes:**
-
- `imageQuality` affects JPG and WebP only; PNG is lossless and ignores this setting
- JPG quality is mapped to FFmpeg's scale (2-31, lower = better)
- WebP quality uses FFmpeg's native 0-100 scale
-
 ### Subtitle Position

 Set the initial vertical subtitle position (measured from the bottom of the screen):
@@ -656,6 +655,7 @@ See `config.example.jsonc` for detailed configuration options.
    "openJimaku": "Ctrl+Shift+J",
    "toggleSubtitleSidebar": "Backslash",
    "toggleNotificationHistory": "CommandOrControl+N",
+    "appendClipboardVideoToQueue": "CommandOrControl+A",
    "multiCopyTimeoutMs": 3000
  }
 }
@@ -682,6 +682,7 @@ See `config.example.jsonc` for detailed configuration options.
 | `openJimaku`                     | string \| `null` | Opens the Jimaku search modal (default: `"Ctrl+Shift+J"`)                                                                                                                          |
 | `toggleSubtitleSidebar`          | string \| `null` | Dispatches the subtitle sidebar toggle action (default: `"Backslash"`). `subtitleSidebar.toggleKey` remains the primary bare-key setting.                                          |
 | `toggleNotificationHistory`      | string \| `null` | Toggles the overlay notification history panel (default: `"CommandOrControl+N"`). The panel slides in from the same edge as notifications (right when notifications are centered). |
+| `appendClipboardVideoToQueue`    | string \| `null` | Appends a video file path from the clipboard to the mpv playlist (default: `"CommandOrControl+A"`). Works whether the overlay or mpv has focus.                                    |

 **See `config.example.jsonc`** for the complete list of shortcut configuration options.

@@ -797,7 +798,7 @@ If you bind a discrete action to an axis manually, include `direction`:

 Treat the button-index map as reference-only unless you are copying values from the debug modal. Updating it alone does not rewrite the hardcoded raw numeric values already present in controller bindings or controller profiles. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.

-If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `auto` accepts either style and remains the default.
+If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `digital` forces pressed/not-pressed handling; `auto` accepts either style and remains the default.

 If one controller reports non-standard raw button numbers, override that controller profile's button-index map using values from the `Alt+Shift+C` debug modal. Use the global button-index map only when the mapping should apply to every controller without a profile.

@@ -821,7 +822,7 @@ When automatic card updates are disabled, new cards are detected but not automat
 | `Ctrl+Shift+A` | Mark the last added Anki card as an audio card (sets IsAudioCard, SentenceAudio, Sentence, Picture)           |
 | `Ctrl+D`       | Open loaded character dictionary manager                                                                      |
 | `Ctrl+Shift+O` | Open runtime options palette (session-only live toggles)                                                      |
-| `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (fixed, not currently configurable)                               |
+| `Ctrl/Cmd+A`   | Append clipboard video path to MPV playlist (configurable via `shortcuts.appendClipboardVideoToQueue`)        |

 **Multi-line copy workflow:**

@@ -834,7 +835,7 @@ These shortcuts are only active when the overlay window is visible and automatic

 ### Session Help Modal

-The session help modal opens from the overlay with `Ctrl/Cmd+/` by default. The mpv plugin also exposes it through the `Y-H` chord (falling back to `Y-K` if needed). It shows the current session keybindings and color legend.
+The session help modal opens from the overlay with `Ctrl/Cmd+/` by default. The mpv plugin also exposes it through the `y-h` chord. It shows the current session keybindings and color legend.

 You can filter the modal quickly with `/`:

@@ -861,8 +862,8 @@ When config hot-reload updates shortcut/keybinding/style values, close and reope
 Use the runtime options palette to toggle settings live while SubMiner is running. These changes are session-only and reset on restart.

 Current runtime options cover automatic card updates, known-word highlighting,
-JLPT underlines, frequency highlighting, known-word match mode, and Kiku field
-grouping mode.
+N+1 annotation, JLPT underlines, frequency highlighting, known-word match mode,
+and Kiku field grouping mode.

 Annotation toggles only apply to new subtitle lines after the toggle. The currently displayed line is not re-tokenized in place.

@@ -879,7 +880,7 @@ Palette controls:

 ### Shared AI Provider

-This is the single, shared connection to an OpenAI-compatible LLM endpoint. Configure it **once** here at the top level, and SubMiner reuses it wherever AI is needed (today: Anki translation/enrichment). Per-feature toggles and prompt/model tweaks live in their own sections (for example `ankiConnect.ai`) and inherit this transport.
+This is the single, shared connection to an OpenAI-compatible LLM endpoint. Configure it **once** here at the top level, and SubMiner reuses it wherever AI is needed (Anki translation/enrichment and YouTube subtitle fixing). Per-feature toggles and prompt/model tweaks live in their own sections (for example `ankiConnect.ai` and `youtubeSubgen.ai`) and inherit this transport.

 ```json
 {
@@ -907,6 +908,7 @@ This is the single, shared connection to an OpenAI-compatible LLM endpoint. Conf
 SubMiner uses the shared provider for:

 - Anki translation/enrichment when Anki AI is enabled
+- YouTube generated-subtitle fixing when `youtubeSubgen.fixWithAi` is enabled (with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides)

 ### AnkiConnect

@@ -1008,7 +1010,7 @@ This example is intentionally compact. The option table below documents availabl
 | `media.generateImage`                             | `true`, `false`                             | Generate image/animation screenshots (default: `true`)                                                                                                                                                                          |
 | `media.imageType`                                 | `"static"`, `"avif"`                        | Image type: static screenshot or animated AVIF (default: `"static"`)                                                                                                                                                            |
 | `media.imageFormat`                               | `"jpg"`, `"png"`, `"webp"`                  | Image format (default: `"jpg"`)                                                                                                                                                                                                 |
-| `media.imageQuality`                              | number (1-100)                              | Image quality for JPG/WebP; PNG ignores this (default: `92`)                                                                                                                                                                    |
+| `media.imageQuality`                              | number (1-100)                              | Image quality for JPG/WebP; PNG ignores this (default: `92`). JPG values are mapped onto FFmpeg's 2-31 quality scale; WebP uses the value directly.                                                                             |
 | `media.imageMaxWidth`                             | number (px)                                 | Optional max width for static screenshots. Unset keeps source width.                                                                                                                                                            |
 | `media.imageMaxHeight`                            | number (px)                                 | Optional max height for static screenshots. Unset keeps source height.                                                                                                                                                          |
 | `media.animatedFps`                               | number (1-60)                               | FPS for animated AVIF (default: `10`)                                                                                                                                                                                           |
@@ -1032,7 +1034,7 @@ This example is intentionally compact. The option table below documents availabl
 | `ankiConnect.nPlusOne.minSentenceWords`           | number                                      | Minimum number of words required in a sentence before single unknown-word N+1 highlighting can trigger (default: `3`).                                                                                                          |
 | `behavior.notificationType`                       | `"overlay"`, `"system"`, `"both"`, `"none"` | Notification type on card update (default: `"overlay"`). `"both"` means overlay + system. `osd` and `osd-system` are legacy config-file-only values; use `"osd-system"` to keep the old OSD + system behavior.                  |
 | `behavior.autoUpdateNewCards`                     | `true`, `false`                             | Automatically update cards on creation (default: `true`)                                                                                                                                                                        |
-| `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time                                                                                                                                                        |
+| `metadata.pattern`                                | string                                      | Format pattern for metadata: `%f`=filename, `%F`=filename+ext, `%t`=time, `%T`=time with milliseconds, `<br>`=newline                                                                                                           |
 | `isLapis`                                         | object                                      | Lapis/shared sentence-card config: `{ enabled, sentenceCardModel }`. Sentence/audio field names are fixed to `Sentence` and `SentenceAudio`.                                                                                    |
 | `isKiku`                                          | object                                      | Kiku-only config: `{ enabled, fieldGrouping, deleteDuplicateInAuto }` (shared sentence/audio/model settings are inherited from `isLapis`)                                                                                       |

@@ -1136,8 +1138,6 @@ Configure Jimaku API access and defaults:

 Jimaku is rate limited; if you hit a limit, SubMiner will surface the retry delay from the API response.

-Set `openBrowser` to `false` to only print the URL without opening a browser.
-
 ### Subtitle Sync

 Sync the active subtitle track from the overlay picker using `alass` or `ffsubsync`. Both are **optional external tools** that must be installed separately and available on your `PATH` (or configured via the path options below).
@@ -1158,8 +1158,8 @@ Sync the active subtitle track from the overlay picker using `alass` or `ffsubsy

 | Option           | Values          | Description                                                                                                               |
 | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `alass_path`     | string path     | Path to `alass` executable. Empty or `null` resolves from `PATH`. `alass` must be installed separately.                   |
-| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty or `null` resolves from `PATH`. `ffsubsync` must be installed separately.           |
+| `alass_path`     | string path     | Path to `alass` executable. Empty falls back to `/usr/bin/alass`. `alass` must be installed separately.                   |
+| `ffsubsync_path` | string path     | Path to `ffsubsync` executable. Empty falls back to `/usr/bin/ffsubsync`. `ffsubsync` must be installed separately.       |
 | `ffmpeg_path`    | string path     | Path to `ffmpeg` (used for internal subtitle extraction). Empty or `null` falls back to `/usr/bin/ffmpeg`.                |
 | `replace`        | `true`, `false` | When `true` (default), overwrite the active subtitle file on successful sync. When `false`, write `<name>_retimed.<ext>`. |

@@ -1195,6 +1195,8 @@ AniList integration is opt-in and disabled by default. Enable it to allow SubMin
 | `anilist.enabled`                                              | `true`, `false`     | Enable AniList post-watch progress updates (default: `false`)                                                 |
 | `accessToken`                                                  | string              | Optional explicit AniList access token override (default: empty string)                                       |
 | `characterDictionary.maxLoaded`                                | number              | Maximum number of most-recently-used AniList media snapshots included in the merged dictionary (default: `3`) |
+| `characterDictionary.refreshTtlHours`                          | number              | Hours before a cached media snapshot is refreshed (default: `168`, clamped to 1–8760)                         |
+| `characterDictionary.evictionPolicy`                           | `"delete"`, `"disable"` | What happens to snapshots evicted beyond `maxLoaded` (default: `"delete"`)                                |
 | `characterDictionary.collapsibleSections.description`          | `true`, `false`     | Open the Description section by default in generated dictionary entries                                       |
 | `characterDictionary.collapsibleSections.characterInformation` | `true`, `false`     | Open the Character Information section by default in generated dictionary entries                             |
 | `characterDictionary.collapsibleSections.voicedBy`             | `true`, `false`     | Open the Voiced by section by default in generated dictionary entries                                         |
@@ -1504,7 +1506,7 @@ Configure the mpv executable, profile, and window state for SubMiner-managed mpv
 | `executablePath`         | string                                                                      | Absolute path to `mpv.exe` for Windows launch flows. Leave empty to auto-discover from `SUBMINER_MPV_PATH` or `PATH` (default `""`)         |
 | `profile`                | string                                                                      | mpv profile name passed as `--profile=<name>`. Leave empty to pass no profile (default `""`)                                                |
 | `launchMode`             | `"normal"` \| `"maximized"` \| `"fullscreen"`                               | Window state when SubMiner spawns mpv (default `"normal"`)                                                                                  |
-| `socketPath`             | string                                                                      | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (default: `\\\\.\\pipe\\subminer-socket`)                  |
+| `socketPath`             | string                                                                      | mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin (platform-dependent default: `/tmp/subminer-socket`, or `\\\\.\\pipe\\subminer-socket` on Windows) |
 | `backend`                | `"auto"` \| `"hyprland"` \| `"sway"` \| `"x11"` \| `"macos"` \| `"windows"` | Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform (default: `"auto"`)                             |
 | `autoStartSubMiner`      | `true`, `false`                                                             | Start SubMiner in the background when SubMiner-managed mpv loads a file (default: `true`)                                                   |
 | `pauseUntilOverlayReady` | `true`, `false`                                                             | Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness, with a 30-second fallback (default: `true`) |
@@ -1552,15 +1554,18 @@ Current launcher behavior:
 - If YouTube/mpv already exposes an authoritative matching subtitle track, SubMiner reuses it; otherwise it downloads and injects only the missing side.
 - SubMiner loads the primary subtitle plus a best-effort secondary subtitle.
 - Playback waits only for primary subtitle readiness; secondary failures do not block playback.
- English secondary subtitles are selected from the secondary-subtitle language list when primary language matches are unavailable.
 - Native mpv secondary subtitle rendering stays hidden during this flow so the SubMiner overlay remains the visible secondary subtitle surface.
 - If primary subtitle loading fails, use `Ctrl+Alt+C` to open the subtitle modal and pick a track.

-Language targets are derived from subtitle config:
+Track selection:

- primary track: `youtube.primarySubLanguages` (falls back to `["ja","jpn"]`)
- secondary track: secondary-subtitle language list (falls back to English when empty)
- Local playback uses the same priorities after mpv reports subtitle track metadata, so sidecar/internal mixed sets can override an incorrect initial `sid=auto` pick.
+- YouTube auto-selection always targets a Japanese primary track and an English secondary track, preferring manual uploads over auto-generated captions.
+- `youtube.primarySubLanguages` (default `["ja","jpn"]`) defines which loaded track counts as a satisfactory primary for the "primary subtitle missing" notification and for managed local/playlist subtitle selection.
+- Local playback applies these priorities after mpv reports subtitle track metadata, so sidecar/internal mixed sets can override an incorrect initial `sid=auto` pick.
 - Tracks are resolved and loaded before mpv starts; the older launcher mode switch has been removed.

-Precedence for launcher defaults is: CLI flag > environment variable > `config.jsonc` > built-in default.
+These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.
+
+#### YouTube Subtitle Generation (`youtubeSubgen`)
+
+An advanced, template-hidden section for Whisper-based YouTube subtitle generation: `whisperBin`, `whisperModel`, `whisperVadModel`, `whisperThreads` (default `4`), and `fixWithAi` (default `false`), which post-processes generated subtitles through the [Shared AI Provider](#shared-ai-provider) with optional `youtubeSubgen.ai.model` / `systemPrompt` overrides. These keys are accepted in `config.jsonc` but intentionally omitted from the generated template.
@@ -5,6 +5,8 @@ For internal architecture/workflow guidance, use `docs/README.md` at the repo ro
 ## Prerequisites

 - [Bun](https://bun.sh)
+- A system `lua` interpreter for `bun run test:launcher` / `bun run test:plugin:src`
+- macOS builds compile a Swift helper via `scripts/build-macos-helper.sh` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)

 ## Setup

@@ -133,7 +135,7 @@ Focused commands:
 bun run test:config       # Source-level config schema/validation tests
 bun run test:launcher     # Launcher regression tests (config discovery + command routing)
 bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
-bun run test:launcher:env:src # Launcher smoke + Lua plugin gate
+bun run test:env                # Launcher smoke + Lua plugin gate
 bun run test:src          # Bun-managed maintained src/** discovery lane
 bun run test:launcher:unit:src # Bun-managed maintained launcher unit lane
 bun run test:scripts      # Bun-managed scripts/** test lane
@@ -163,7 +165,7 @@ make pretty
 bun run format:check:src
 ```

- `make pretty` runs the maintained Prettier allowlist only (`format:src`).
+- `make pretty` runs the maintained Prettier allowlists (`format:src` and `format:stats`).
 - `bun run format:check:src` checks the same scoped set without writing changes.
 - `bun run format` remains the broad repo-wide Prettier command; use it intentionally.

@@ -196,15 +198,7 @@ bun run docs:preview # Preview built site at http://localhost:4173
 bun run docs:test    # Docs regression tests
 ```

-Cloudflare Pages deploy settings:
-
- Git repo: `ksyasuda/SubMiner`
- Root directory: `docs-site`
- Build command: `bun run docs:build`
- Build output directory: `.vitepress/dist`
- Build watch paths: `docs-site/*`
-
-Use Cloudflare's single `*` wildcard syntax for watch paths. `docs-site/*` covers nested docs-site changes in the repo; `docs-site/**` is not the correct Pages pattern and may skip docs-only pushes.
+Deployment: production docs are built with `bun run docs:build:versioned` and uploaded directly to Cloudflare Pages by the `docs-pages` GitHub Actions workflow using Wrangler (from `.tmp/docs-versioned-site`). Cloudflare's automatic Git-integration deployments are intentionally disabled - see `docs-site/README.md` for the deployment contract. Do not re-enable Pages build settings in the Cloudflare dashboard.

 ## Makefile Reference

@@ -241,6 +235,7 @@ Run `make help` for a full list of targets. Key ones:
 | `SUBMINER_APPIMAGE_PATH`           | Override SubMiner app binary path for launcher playback commands               |
 | `SUBMINER_BINARY_PATH`             | Alias for `SUBMINER_APPIMAGE_PATH`                                             |
 | `SUBMINER_ROFI_THEME`              | Override rofi theme path for launcher picker                                   |
+| `SUBMINER_MPV_PLUGIN_PATH`         | Override the mpv plugin directory injected by the launcher                     |
 | `SUBMINER_LOG_LEVEL`               | Override app logger level (`debug`, `info`, `warn`, `error`)                   |
 | `SUBMINER_MPV_LOG`                 | Override mpv/app shared log file path                                          |
 | `SUBMINER_JIMAKU_API_KEY`          | Override Jimaku API key for launcher subtitle downloads                        |
@@ -25,15 +25,16 @@ Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_

 - Leave `dbPath` empty to use the default location (`immersion.sqlite` in SubMiner's app-data directory).
 - Set an explicit path to move the database (useful for backups, cloud syncing, or external tools).
+- To share stats and watch history between two machines, use [`subminer sync <host>`](/launcher-script#sync-between-machines) instead of file-level cloud sync — it merges both databases without one side overwriting the other.

 ## Stats Dashboard

 The same immersion data powers the stats dashboard.

 - In-app overlay: focus the visible overlay, then press the key from `stats.toggleKey` (default: `` ` `` / `Backquote`).
- Launcher command: run `subminer stats` to start the local stats server on demand and open the dashboard in your browser.
+- Launcher command: run `subminer stats` to start the local stats server on demand (it also opens the dashboard in your browser when `stats.autoOpenBrowser` is enabled; the default is `false`).
 - Background server: run `subminer stats -b` to start or reuse a dedicated background stats daemon without keeping the launcher attached, and `subminer stats -s` to stop that daemon.
- Maintenance command: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand.
+- Maintenance commands: run `subminer stats cleanup` or `subminer stats cleanup -v` to backfill/repair vocabulary metadata (`headword`, `reading`, POS) and purge stale or excluded rows from `imm_words` on demand; `subminer stats cleanup -l` repairs lifetime summary tables. `subminer stats rebuild` and `subminer stats backfill` rebuild or backfill rollup data.
 - Browser page: open `http://127.0.0.1:6969` directly if the local stats server is already running.

 ### Dashboard Tabs
@@ -86,6 +87,7 @@ Stats server config lives under `stats`:
 {
  "stats": {
    "toggleKey": "Backquote",
+    "markWatchedKey": "KeyW",
    "serverPort": 6969,
    "autoStartServer": true,
    "autoOpenBrowser": false,
@@ -94,6 +96,7 @@ Stats server config lives under `stats`:
 ```

 - `toggleKey` is overlay-local, not a system-wide shortcut.
+- `markWatchedKey` toggles the watched state of the highlighted entry inside the stats dashboard.
 - `serverPort` controls the localhost dashboard URL.
 - `autoStartServer` starts the local stats HTTP server on launch once immersion tracking is active, or reuses the dedicated background stats server when one is already running. Background app launches (`subminer app`) start the stats server immediately, registering it so later launches reuse it instead of starting another one.
 - `autoOpenBrowser` controls whether `subminer stats` launches the dashboard URL in your browser after ensuring the server is running.
@@ -185,7 +188,6 @@ SELECT
  total_watched_ms,
  active_watched_ms,
  lines_seen,
-  words_seen,
  tokens_seen,
  cards_mined
 FROM imm_session_telemetry
@@ -203,13 +205,13 @@ SELECT
  s.started_at_ms,
  s.ended_at_ms,
  COALESCE(s.active_watched_ms, 0) AS active_watched_ms,
-  COALESCE(s.words_seen, 0) AS words_seen,
+  COALESCE(s.tokens_seen, 0) AS tokens_seen,
  COALESCE(s.cards_mined, 0) AS cards_mined,
  CASE
    WHEN COALESCE(s.active_watched_ms, 0) > 0
-      THEN COALESCE(s.words_seen, 0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
+      THEN COALESCE(s.tokens_seen, 0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
    ELSE NULL
-  END AS words_per_min,
+  END AS tokens_per_min,
  CASE
    WHEN COALESCE(s.active_watched_ms, 0) > 0
      THEN (COALESCE(s.cards_mined, 0) * 60.0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
@@ -229,7 +231,7 @@ SELECT
  la.total_sessions,
  la.total_active_ms,
  la.total_cards,
-  la.total_words_seen,
+  la.total_tokens_seen,
  la.total_lines_seen,
  la.first_watched_ms,
  la.last_watched_ms
@@ -248,11 +250,10 @@ SELECT
  total_sessions,
  total_active_min,
  total_lines_seen,
-  total_words_seen,
  total_tokens_seen,
  total_cards,
  cards_per_hour,
-  words_per_min,
+  tokens_per_min,
  lookup_hit_rate
 FROM imm_daily_rollups
 ORDER BY rollup_day DESC, video_id DESC
@@ -268,7 +269,6 @@ SELECT
  total_sessions,
  total_active_min,
  total_lines_seen,
-  total_words_seen,
  total_tokens_seen,
  total_cards
 FROM imm_monthly_rollups
@@ -287,15 +287,19 @@ LIMIT ?;
 - Large-table reads are index-backed for `sample_ms`, session time windows, frequency-ranked words/kanji, and cover-art identity lookups.
 - Workload-dependent tuning knobs remain at defaults unless you change them: `cache_size`, `mmap_size`, `temp_store`, `auto_vacuum`.

-### Schema (v4)
+### Schema (v18)
+
+The exact schema version lives in `SCHEMA_VERSION` (`src/core/services/immersion-tracker/types.ts`) and is recorded in the `imm_schema_version` table.

 Core tables:

 - `imm_videos` - video key/title/source metadata
+- `imm_anime` - anime/series metadata referenced by videos and lifetime tables
 - `imm_sessions` - session UUID, video reference, timing/status, final denormalized totals
 - `imm_session_telemetry` - high-frequency session aggregates over time
 - `imm_session_events` - event stream with compact numeric event types
 - `imm_subtitle_lines` - persisted subtitle text and timing per session/video
+- `imm_youtube_videos` - YouTube video/channel metadata for tracked videos

 Lifetime summary tables:

@@ -308,11 +312,14 @@ Rollup tables:

 - `imm_daily_rollups`
 - `imm_monthly_rollups`
+- `imm_rollup_state` - incremental rollup progress bookkeeping

 Vocabulary tables:

- `imm_words(id, headword, word, reading, first_seen, last_seen, frequency)`
+- `imm_words(id, headword, word, reading, part_of_speech, pos1, pos2, pos3, first_seen, last_seen, frequency, frequency_rank)` with `UNIQUE(headword, word, reading)`
 - `imm_kanji(id, kanji, first_seen, last_seen, frequency)`
+- `imm_word_line_occurrences` / `imm_kanji_line_occurrences` - word/kanji ↔ subtitle-line occurrence links
+- `imm_stats_excluded_words` - vocabulary exclusion list managed from the dashboard

 Media-art tables:

@@ -79,6 +79,7 @@ SubMiner extracts media info from the current video path to pre-fill the search

 - **Season + episode patterns:** `S01E03`, `1x03`
 - **Episode-only patterns:** `E03`, `EP03`, or dash-separated numbers like `Title - 03 -`
+- **Season folders:** a parent directory named `Season 2` or `S2` fills in the season when the filename lacks one
 - **Bracket tags:** `[SubGroup]`, `[1080p]`, `[HEVC]` - stripped before title extraction
 - **Year tags:** `(2024)` - stripped
 - **Dots and underscores:** treated as spaces
@@ -94,7 +95,7 @@ Configure `jimaku.apiKey` or `jimaku.apiKeyCommand` in your config. If using `ap

 **"Jimaku request failed" or HTTP 429**

-The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again. An API key provides higher rate limits.
+The Jimaku API has rate limits. If you see 429 errors, wait for the retry duration shown in the OSD message and try again.

 **No entries found**

@@ -54,6 +54,7 @@ The theme is auto-detected from these paths (first match wins):
 - `/usr/local/share/SubMiner/themes/subminer.rasi`
 - `/usr/share/SubMiner/themes/subminer.rasi`
 - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
+- `assets/themes/subminer.rasi` next to the launcher script (final fallback)

 Override with the `SUBMINER_ROFI_THEME` environment variable:

@@ -72,16 +73,68 @@ subminer -R -H                         # rofi history browser

 The first menu lists every locally watched series, most recently watched first, using the parsed media title (e.g. the anime title) when available and the directory name otherwise. Selecting a series opens an action menu:

- **Replay last watched** — replays the most recently watched episode
- **Next episode** — plays the episode after the last watched one (continues into the next season directory when the season ends)
- **Browse episodes** — lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu is shown first
+- **Previous episode**: plays the episode before the last watched one and continues into the previous season directory when the season starts
+- **Replay last watched**: replays the most recently watched episode
+- **Next episode**: plays the episode after the last watched one and continues into the next season directory when the season ends
+- **Browse episodes**: lists the video files in the series directory in episode order, using the same fzf/rofi episode picker as directory browsing; if the series has multiple season directories, a season menu appears first
+- **Quit SubMiner**: closes the history session without starting an episode
+
+After an episode ends or you close mpv, the launcher returns to an action menu for the same series. The menu lists Previous, Rewatch, Next, Select episode, and Quit SubMiner in that order, omitting Previous or Next when no episode exists in that direction. Choosing Previous or Next can move between season directories. After you play another episode, Previous, Rewatch, and Next use it instead of the older database entry. Pressing Escape closes the history session.

 Series whose directories are not currently accessible (e.g. an unmounted network share) are hidden from the list. Watch history requires the immersion tracker database (`immersionTracking.dbPath`, default `<config dir>/immersion.sqlite`), which SubMiner populates during playback.

+## Sync Between Machines
+
+`subminer sync <host>` merges immersion stats and watch history between two machines over SSH, so both end up with the union of sessions, lifetime totals, vocabulary counts, daily/monthly charts, and `--history` entries. `<host>` is anything `ssh` accepts (`user@hostname` or an ssh config alias); SubMiner must be installed on both machines at the same version. The sync engine runs only inside the app (`SubMiner --sync-cli sync ...`): the sync window spawns it that way, `subminer sync` is a thin proxy that forwards to the installed app, and the remote side is found automatically whether it has the launcher or just the app. The command-line launcher is optional everywhere.
+
+```bash
+subminer sync macbook                  # two-way sync with the host "macbook"
+subminer sync macbook --push           # merge local data into macbook only
+subminer sync macbook --pull           # merge macbook data into local only
+subminer sync user@192.168.1.20       # explicit user@host
+subminer sync macbook --remote-cmd ~/bin/subminer  # custom remote SubMiner/launcher path
+subminer sync macbook --check          # test SSH + remote SubMiner without syncing
+subminer sync --ui                     # open the sync window (also in the tray menu)
+```
+
+How it works: each side takes a consistent snapshot of its database (`VACUUM INTO`), the snapshots are exchanged over `scp`, and each machine merges the other's snapshot into its own database. The merge is an insert-only union keyed on stable identifiers (session UUIDs, video keys, series title keys, word/kanji identity), so it is safe to re-run at any time. Syncing twice changes nothing, and nothing is ever overwritten or summed twice. Lifetime totals and rollup charts are updated incrementally, so history older than the session retention window is preserved on both sides.
+
+For a one-way transfer, `--push` snapshots the local database and merges it into the host without changing the local database. `--pull` snapshots the host and merges it into the local database without changing the host. These modes add missing data; they do not delete destination-only data or make the destination an exact mirror.
+
+Command-line sync defaults to a cold-start safety check: close SubMiner (and stop the background stats daemon with `subminer stats -s`) on both machines before running it, or pass `--force`. Syncs started from the Sync window use live mode automatically, including scheduled auto-syncs while SubMiner or playback is active. SQLite WAL provides a consistent snapshot, the transactional merge serializes with live writes, and each machine's unfinished session is excluded from the transfer; that session syncs normally after it finishes. The mpv safety check requires a live socket connection, so a stale socket file left after mpv exits does not block command-line sync. Both machines must be on the same SubMiner version; otherwise, the sync aborts on a stats schema mismatch.
+
+On the remote, sync looks for the `subminer` launcher first (PATH and `~/.local/bin`), then the app binary in `--sync-cli` mode (`SubMiner` on PATH, then the standard macOS `/Applications` and `~/Applications` installs), checking standard SubMiner and Bun locations (`~/.local/bin`, `~/.bun/bin`, Homebrew, `/usr/local/bin`, `/usr/bin`, and `/bin`) even when the non-interactive SSH shell omits them from `PATH`. An AppImage in a custom location can be addressed with `--remote-cmd /path/to/SubMiner.AppImage` (or symlink it as `SubMiner` somewhere on the remote PATH).
+
+Windows remotes are supported: enable Windows' built-in **OpenSSH Server** and sync detects the remote shell (cmd or PowerShell) automatically, finding SubMiner in its default install location (`%LOCALAPPDATA%\Programs\SubMiner`), the launcher shim (`%LOCALAPPDATA%\SubMiner\bin`), or on PATH. Temp files on the remote are created and removed by SubMiner itself (`sync --make-temp` / `--remove-temp`), so no POSIX tools are required on the remote side.
+
+Two lower-level modes are used internally over SSH and also work standalone for manual transfers (e.g. via a USB drive):
+
+```bash
+subminer sync --snapshot /tmp/stats.sqlite   # write a consistent snapshot of the local database
+subminer sync --merge /tmp/stats.sqlite      # merge a snapshot file into the local database
+```
+
+Unfinished sessions (a crash mid-playback) are skipped until the app finalizes them; they sync on the next run. Word/kanji "known" state from Anki is not part of the database and does not sync. Each machine derives it from its own Anki collection.
+
+`subminer sync <host> --check` verifies a host without touching any data: it probes the SSH connection, locates SubMiner on the remote (launcher or app binary), and reports its version. `--json` switches any sync mode to machine-readable NDJSON progress output (this is what the sync window consumes).
+
+`sync --make-temp` creates a restricted temporary directory and prints its path; `sync --remove-temp <dir>` removes one created by that command. They are internal SSH transfer helpers, exposed for compatibility but normally invoked only by sync itself. `SubMiner --sync-cli sync ...` is the packaged app's headless compatibility entrypoint; use `SubMiner --sync-cli --help` for its sync-specific help. The `subminer sync` launcher command selects this entrypoint automatically and runs AppImages in Node-only mode, so remote sync does not require a graphical session.
+
+### Sync window
+
+`subminer sync --ui` opens a dedicated window for the same engine in a detached app process, returning the shell immediately. Closing that standalone-launched window exits its app instance. Opening **Sync Stats & History** from the tray keeps the resident app running when the window closes:
+
+- **Devices:** saved hosts with a per-host direction (two-way / push / pull), an auto-sync toggle, last-sync status, and one-click **Sync now** / **Test** / **Remove**. Hosts synced from the command line appear here automatically.
+- **Add a device:** test SSH + remote SubMiner availability before saving, with a setup checklist for first-time SSH configuration.
+- **Activity:** live stage-by-stage progress, remote output, and separate merge summaries (sessions, words, kanji, rollups) for each machine updated by the run. Runs can be cancelled and can proceed while the app, stats server, or playback is active.
+- **Snapshots:** create manual database snapshots (stored in `/tmp/subminer-db-snapshots/` by default), merge a snapshot file into the local database, or reveal/delete existing snapshots.
+
+Hosts with **Auto-sync** enabled are synced in the background on a configurable interval (default every 60 minutes), including during active playback; results surface as overlay notifications. The unfinished playback session is skipped until a later sync sees it finalized. Host bookkeeping lives in `<config dir>/sync-hosts.json`.
+
 ## Common Commands

 ```bash
-subminer video.mkv                      # play a specific file (default plugin config auto-starts visible overlay)
+subminer video.mkv                      # play a specific file (managed launches auto-start the visible overlay by default)
 subminer https://youtu.be/...           # YouTube playback (requires yt-dlp)
 subminer --backend x11 video.mkv        # Force x11 backend for a specific file
 subminer -u                             # check for SubMiner updates
@@ -92,55 +145,61 @@ subminer stats -b                       # start background stats daemon

 ## Subcommands

-| Subcommand                                 | Purpose                                                            |
-| ------------------------------------------ | ------------------------------------------------------------------ |
-| `subminer jellyfin` / `jf`                 | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login)         |
-| `subminer stats`                           | Start stats server and open immersion dashboard in browser         |
-| `subminer stats -b`                        | Start or reuse background stats daemon (non-blocking)              |
-| `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows                  |
-| `subminer doctor`                          | Dependency + config + socket diagnostics                           |
-| `subminer settings`                        | Open the SubMiner settings window                                  |
-| `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path           |
-| `subminer config path`                     | Print active config file path                                      |
-| `subminer config show`                     | Print active config contents                                       |
-| `subminer mpv status`                      | Check mpv socket readiness                                         |
-| `subminer mpv socket`                      | Print active socket path                                           |
-| `subminer mpv idle`                        | Launch detached idle mpv instance                                  |
-| `subminer dictionary <path>`               | Generate character dictionary ZIP from file/dir target             |
-| `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction |
-| `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                     |
-| `subminer texthooker`                      | Launch texthooker-only mode                                        |
-| `subminer texthooker -o`                   | Launch texthooker and open it in the default browser               |
-| `subminer app`                             | Pass arguments directly to SubMiner binary                         |
+| Subcommand                                 | Purpose                                                                                           |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `subminer jellyfin` / `jf`                 | Jellyfin workflows (`-d` discovery, `-p` play, `-l` login, `--logout`, `--setup`)                 |
+| `subminer stats`                           | Start the stats server (opens the dashboard when `stats.autoOpenBrowser` is on)                   |
+| `subminer stats -b` / `-s`                 | Start/reuse or stop the background stats daemon                                                   |
+| `subminer stats cleanup`                   | Backfill vocabulary metadata and prune stale rows (`-v` vocab, `-l` lifetime summaries)           |
+| `subminer stats rebuild` / `backfill`      | Rebuild or backfill rollup data                                                                   |
+| `subminer doctor`                          | Dependency + config + socket diagnostics (`--refresh-known-words` refreshes the known-word cache) |
+| `subminer settings`                        | Open the SubMiner settings window                                                                 |
+| `subminer logs -e`                         | Export a sanitized local-date log ZIP and print its path                                          |
+| `subminer config path`                     | Print active config file path                                                                     |
+| `subminer config show`                     | Print active config contents                                                                      |
+| `subminer mpv status`                      | Check mpv socket readiness                                                                        |
+| `subminer mpv socket`                      | Print active socket path                                                                          |
+| `subminer mpv idle`                        | Launch detached idle mpv instance                                                                 |
+| `subminer sync <host>`                     | Two-way stats/history sync with another machine over SSH                                          |
+| `subminer sync <host> --push`              | Merge local stats/history into another machine only                                               |
+| `subminer sync <host> --pull`              | Merge another machine's stats/history into the local database only                                |
+| `subminer sync <host> --check`             | Test SSH connection and remote launcher availability                                              |
+| `subminer sync --ui`                       | Open the sync window (saved devices, auto-sync, snapshots)                                        |
+| `subminer dictionary <path>` / `dict`      | Generate character dictionary ZIP from file/dir target                                            |
+| `subminer dictionary --candidates <path>`  | List AniList candidate matches for character dictionary correction                                |
+| `subminer dictionary --select <id> <path>` | Pin an AniList media ID for that target series                                                    |
+| `subminer texthooker`                      | Launch texthooker-only mode                                                                       |
+| `subminer texthooker -o`                   | Launch texthooker and open it in the default browser                                              |
+| `subminer app` / `bin`                     | Pass arguments directly to SubMiner binary (e.g. `subminer app --setup`)                          |

 Use `subminer <subcommand> -h` for command-specific help.

 ## Options

-| Flag                  | Description                                                          |
-| --------------------- | -------------------------------------------------------------------- |
-| `-d, --directory`     | Video search directory (default: cwd)                                |
-| `-r, --recursive`     | Search directories recursively                                       |
-| `-R, --rofi`          | Use rofi instead of fzf                                              |
-| `-H, --history`       | Browse local watch history (see [Watch History](#watch-history))     |
-| `--setup`             | Open first-run setup popup manually                                  |
-| `-v, --version`       | Print installed SubMiner version                                     |
-| `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible |
-| `--start`             | Explicitly start overlay after mpv launches                          |
-| `-S, --start-overlay` | Explicitly start overlay after mpv launches                          |
-| `-T, --no-texthooker` | Disable texthooker server                                            |
-| `-p, --profile`       | mpv profile name (no default; omitted unless set)                    |
-| `-a, --args`          | Pass additional mpv arguments as a quoted string                     |
-| `-b, --backend`       | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`) |
-| `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                  |
-| `--dev`, `--debug`    | Enable app dev-mode (not tied to log level)                          |
+| Flag                  | Description                                                                 |
+| --------------------- | --------------------------------------------------------------------------- |
+| `-d, --directory`     | Video search directory (default: cwd)                                       |
+| `-r, --recursive`     | Search directories recursively                                              |
+| `-R, --rofi`          | Use rofi instead of fzf                                                     |
+| `-H, --history`       | Browse local watch history (see [Watch History](#watch-history))            |
+| `-v, --version`       | Print the launcher's own version (can differ from the installed app binary) |
+| `-u, --update`        | Check for SubMiner updates and update the app/launcher when possible        |
+| `--start`             | Explicitly start overlay after mpv launches                                 |
+| `-S, --start-overlay` | Force the visible overlay on start                                          |
+| `-T, --no-texthooker` | Disable texthooker server                                                   |
+| `-p, --profile`       | mpv profile name (no default; omitted unless set)                           |
+| `-a, --args`          | Pass additional mpv arguments as a quoted string                            |
+| `-b, --backend`       | Force window backend (`hyprland`, `sway`, `x11`, `macos`, `windows`)        |
+| `--settings`          | Open the SubMiner settings window                                           |
+| `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                         |
+
+App-binary flags such as `--setup`, `--dev`, and `--debug` are not launcher flags - pass them through with `subminer app`, for example `subminer app --setup`.

 On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, runtime plugin copy, and rofi theme even when SubMiner is already running in the tray.

-With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`), explicit start flags are usually unnecessary.
+Managed launches inject `auto_start=yes`, `auto_start_visible_overlay=yes`, and `auto_start_pause_until_ready=yes` as plugin script-opts from SubMiner's config defaults (`mpv.autoStartSubMiner`, `auto_start_overlay`), so explicit start flags are usually unnecessary. The plugin's own built-in defaults are off - mpv launched outside SubMiner does not auto-start the overlay.

 ## Logging

- Default log level is `info`
- `--background` mode defaults to `warn` unless `--log-level` is explicitly set
- `--dev` / `--debug` control app behavior, not logging verbosity - use `--log-level` for that
+- Default log level is `warn` (launcher and app; configurable via `logging.level`)
+- `--dev` / `--debug` are app-binary flags that control app dev-mode, not logging verbosity - use `--log-level` for that
@@ -56,20 +56,20 @@ This is useful when auto-update is disabled or when you want explicit control ov
 Create a standalone sentence card without going through Yomitan:

 - **Mine current sentence**: `Ctrl/Cmd+S` (configurable via `shortcuts.mineSentence`)
- **Mine multiple lines**: `Ctrl/Cmd+Shift+S` followed by a digit 1–9 to select how many recent subtitle lines to combine.
+- **Mine multiple lines**: `Ctrl/Cmd+Shift+S` followed by a digit 1–9 to select how many recent subtitle lines to combine (the digit selector times out after 3 seconds, configurable via `shortcuts.multiCopyTimeoutMs`).

 The sentence card uses the note type configured in `isLapis.sentenceCardModel` and always maps sentence/audio to `Sentence` and `SentenceAudio`.

 ::: warning Requires Lapis/Kiku note type
-Sentence card creation requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+Sentence card creation requires `ankiConnect.isLapis.sentenceCardModel` to name a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type that exists in Anki (default: `"Lapis"`). See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

 ### 4. Mark as Audio Card

-After adding a word via Yomitan, press the audio card shortcut to overwrite the audio with a longer clip spanning the full subtitle timing.
+After adding a word via Yomitan, press the audio card shortcut (`Ctrl/Cmd+Shift+A` by default, `shortcuts.markAudioCard`) to mark the card as an audio card. This sets the audio-card flag and fills sentence, image, and metadata fields alongside the full-subtitle audio clip.

 ::: warning Requires Lapis/Kiku note type
-Audio card marking requires a [Lapis](https://github.com/donkuri/lapis) or [Kiku](https://github.com/youyoumu/kiku) compatible note type and `ankiConnect.isLapis.enabled: true` in your config. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
+Audio card marking uses the same `ankiConnect.isLapis.sentenceCardModel` note type as sentence cards. See [Anki Integration - Sentence Cards](/anki-integration#sentence-cards-lapis) for setup.
 :::

 ### Field Grouping (Kiku)
@@ -172,7 +172,7 @@ Install the sync tools separately - see [Troubleshooting](/troubleshooting#subti

 ## Texthooker

-SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (configurable port) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.
+SubMiner runs a local HTTP server at `http://127.0.0.1:5174` (fixed default port; overridable only via the mpv plugin's `texthooker_port` script-opt) that serves a texthooker UI. This allows external tools - such as a browser-based Yomitan instance - to receive subtitle text in real time.

 The texthooker page displays the current subtitle and updates as new lines arrive. This is useful if you prefer to do lookups in a browser rather than through the overlay's built-in Yomitan.

@@ -4,7 +4,7 @@

 **Who needs this page:** Most users never touch the plugin directly - SubMiner-managed launches (the app, the `subminer` launcher, or the Windows shortcut) inject the bundled plugin automatically for that session, so there is nothing to install into mpv's global `scripts` directory. Read on if you launch mpv from another tool and want SubMiner's in-player controls, or you want to script mpv against SubMiner.

-The plugin ships as a modular Lua package under `plugin/subminer/` (entry point `init.lua`, which loads `main.lua` and sibling modules). Earlier releases shipped a single global `main.lua`; runtime loading replaces it.
+The plugin ships as a modular Lua package under `plugin/subminer/` (entry point `main.lua`, which loads `init.lua` and sibling modules). Earlier releases shipped a single global `main.lua`; runtime loading replaces it.

 ## Runtime Loading

@@ -27,6 +27,25 @@ On Windows, use a named pipe instead:
 input-ipc-server=\\.\pipe\subminer-socket
 ```

+## Configuration (script-opts)
+
+The plugin reads options from `script-opts` with the `subminer-` prefix (for example `--script-opts=subminer-backend=hyprland`). Managed launches inject these automatically from your SubMiner config; the shipped `subminer.conf` is intentionally empty so command-line opts always win.
+
+| Option                                             | Default          | Description                                                                     |
+| -------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------- |
+| `binary_path`                                      | `""`             | Path to the SubMiner binary; empty enables [auto-detection](#binary-auto-detection) |
+| `socket_path`                                      | platform default | mpv IPC socket path (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows) |
+| `texthooker_enabled`                               | `no`             | Start the texthooker server with the overlay                                    |
+| `texthooker_port`                                  | `5174`           | Texthooker server port                                                          |
+| `backend`                                          | `auto`           | Window backend (`auto`, `hyprland`, `sway`, `x11`, `macos`)                     |
+| `auto_start`                                       | `no`             | Start the overlay app on `file-loaded` (managed launches set this from `mpv.autoStartSubMiner`) |
+| `auto_start_visible_overlay`                       | `no`             | Show the visible overlay on auto-start (from `auto_start_overlay` in config)    |
+| `overlay_loading_osd`                              | `no`             | Show an OSD loading spinner while the overlay starts                            |
+| `auto_start_pause_until_ready`                     | `yes`            | Keep mpv paused until the overlay reports tokenization-ready                    |
+| `auto_start_pause_until_ready_timeout_seconds`     | `30`             | Timeout before resuming playback anyway                                         |
+| `osd_messages`                                     | `yes`            | Show plugin OSD status messages                                                 |
+| `log_level`                                        | `info`           | Plugin log verbosity                                                            |
+
 ## Keybindings

 Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "chord"):
@@ -44,7 +63,7 @@ Most plugin actions use a `y` chord prefix - press `y`, then the second key (a "
 | `v`             | Toggle primary subtitle bar visibility |
 | `TAB` (default) | Skip intro (AniSkip)                   |

-The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. The legacy `y-k` chord still works as a fallback unless you remap the AniSkip key onto it. See [AniSkip Integration](/aniskip-integration) for setup and details.
+The AniSkip key is **not** a `y` chord and is not bound by the plugin: the SubMiner app binds it over the mpv IPC socket while it is connected. It defaults to `TAB` and is configurable via `mpv.aniskipButtonKey`. When a custom key (other than `TAB` or `y-k`) is configured, the legacy `y-k` chord is also bound as a fallback. See [AniSkip Integration](/aniskip-integration) for setup and details.

 The bare `v` binding is a forced mpv binding. It overrides mpv's default primary subtitle visibility toggle and routes the action to SubMiner's primary subtitle bar instead.

@@ -70,7 +89,7 @@ Notes:

 ## Menu

-Press `y-y` to open an interactive menu in mpv's OSD:
+Press `y-y` to open an interactive menu (rendered with mpv's console selector):

 ```text
 SubMiner:
@@ -80,6 +99,7 @@ SubMiner:
 4. Open options
 5. Restart overlay
 6. Check status
+7. Stats
 ```

 Select an item by pressing its number.
@@ -92,8 +112,8 @@ When `binary_path` is empty, the plugin searches platform-specific locations:

 1. `~/.local/bin/SubMiner.AppImage`
 2. `/opt/SubMiner/SubMiner.AppImage`
-3. `/usr/local/bin/SubMiner`
-4. `/usr/bin/SubMiner`
+3. `/usr/local/bin/SubMiner` / `/usr/local/bin/subminer`
+4. `/usr/bin/SubMiner` / `/usr/bin/subminer`

 **macOS:**

@@ -102,11 +122,14 @@ When `binary_path` is empty, the plugin searches platform-specific locations:

 **Windows:**

-1. `C:\Program Files\SubMiner\SubMiner.exe`
-2. `C:\Program Files (x86)\SubMiner\SubMiner.exe`
-3. `C:\SubMiner\SubMiner.exe`
+A PowerShell system lookup runs first (running SubMiner process, registry App Paths, `Get-Command`), then static paths:

-Packaged Windows plugin installs also rewrite `socket_path` to `\\.\pipe\subminer-socket` automatically.
+1. `%LOCALAPPDATA%\Programs\SubMiner\SubMiner.exe` (the default per-user install location)
+2. `C:\Program Files\SubMiner\SubMiner.exe`
+3. `C:\Program Files (x86)\SubMiner\SubMiner.exe`
+4. `C:\SubMiner\SubMiner.exe`
+
+On Windows the plugin also normalizes a Unix-style `socket_path` (`/tmp/subminer-socket`) to the named pipe `\\.\pipe\subminer-socket` at runtime.

 ## Backend Detection

@@ -135,8 +158,16 @@ script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
 script-message subminer-autoplay-ready
+script-message subminer-stats-toggle
+script-message subminer-visible-overlay-shown
+script-message subminer-visible-overlay-hidden
+script-message subminer-managed-subtitles-loading
+script-message subminer-overlay-loading-ready
+script-message subminer-reload-session-bindings
 ```

+The last five are primarily used by the SubMiner app to notify the plugin of overlay/loading state and to trigger session-binding reloads.
+
 The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) still exist, but they are handled by the SubMiner app over the IPC socket rather than by the plugin - see [AniSkip Integration](/aniskip-integration#triggering-from-mpv).

 The `subminer-start` message accepts overrides:
@@ -155,8 +186,8 @@ For how the plugin's auto-start fits into the full launch sequence - including w
 - **File loaded**: If `auto_start=yes`, the plugin starts the overlay.
 - **Auto-start pause gate**: If `auto_start_visible_overlay=yes` and `auto_start_pause_until_ready=yes`, launcher starts mpv paused. On cold managed background startup, SubMiner opens the tray and visible overlay shell before tokenization warmups finish, then the plugin resumes playback after SubMiner reports tokenization-ready (with a 30-second timeout fallback).
 - **Duplicate auto-start events**: Repeated `file-loaded` hooks while overlay is already running are ignored for auto-start triggers (prevents duplicate start attempts).
- **MPV shutdown**: The plugin sends a stop command to gracefully shut down both the overlay and the texthooker server.
- **Texthooker**: Starts as a separate subprocess before the overlay to ensure the app lock is acquired first.
+- **MPV shutdown**: The plugin clears its hover/OSD/gate state on shutdown; the overlay app notices the closed IPC socket and shuts itself down.
+- **Texthooker**: When `texthooker_enabled=yes`, the plugin appends `--texthooker` to the overlay start command so the app starts the texthooker server alongside the overlay.

 ## Using with the `subminer` Wrapper

@@ -205,11 +205,13 @@
    "openCharacterDictionaryManager": "CommandOrControl+D", // Accelerator that opens the character dictionary manager modal.
    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openTsukihime": "Ctrl+Shift+T", // Accelerator that opens the TsukiHime subtitle search modal (configured secondary/Japanese primary tabs).
    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
    "toggleSubtitleSidebar": "Backslash", // Accelerator that toggles the subtitle sidebar visibility.
-    "toggleNotificationHistory": "CommandOrControl+N" // Accelerator that toggles the overlay notification history panel.
+    "toggleNotificationHistory": "CommandOrControl+N", // Accelerator that toggles the overlay notification history panel.
+    "appendClipboardVideoToQueue": "CommandOrControl+A" // Accelerator that appends a video path from the clipboard to the mpv playlist.
  }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.

  // ==========================================
@@ -611,6 +613,16 @@
    "maxEntryResults": 10 // Maximum Jimaku search results returned.
  }, // Jimaku API configuration and defaults.

+  // ==========================================
+  // TsukiHime
+  // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+  // Hot-reload: TsukiHime changes apply to the next TsukiHime request.
+  // ==========================================
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1", // Base URL of the TsukiHime API (Animetosho successor). No API key required.
+    "maxSearchResults": 10 // Maximum TsukiHime search results returned.
+  }, // TsukiHime subtitle search configuration for Japanese primary and configured secondary subtitles. No API key required.
+
  // ==========================================
  // YouTube Playback Settings
  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
@@ -10,17 +10,15 @@ A few terms used throughout:

 All shortcuts are configurable in `config.jsonc` under `shortcuts` and `keybindings`. Set any shortcut to `null` to disable it.

-## Global Shortcuts
+## App-Wide Shortcuts

-These work system-wide regardless of which window has focus.
-
-| Shortcut      | Action                 | Configurable                           |
-| ------------- | ---------------------- | -------------------------------------- |
-| `Alt+Shift+O` | Toggle visible overlay | `shortcuts.toggleVisibleOverlayGlobal` |
-| `Alt+Shift+Y` | Open Yomitan settings  | Fixed (not configurable)               |
+| Shortcut      | Action                 | Scope                                       | Configurable                           |
+| ------------- | ---------------------- | -------------------------------------------- | -------------------------------------- |
+| `Alt+Shift+O` | Toggle visible overlay | Works while the overlay or mpv has focus     | `shortcuts.toggleVisibleOverlayGlobal` |
+| `Alt+Shift+Y` | Open Yomitan settings  | OS-global (registered with the OS)           | Fixed (not configurable)               |

 ::: tip
-Global shortcuts are registered with the OS. If they conflict with another application, update them in `shortcuts` config and restart SubMiner.
+`Alt+Shift+O` is dispatched by the overlay window and the mpv plugin, so it works from either surface without OS registration. Only `Alt+Shift+Y` is registered with the OS; if it conflicts with another application, that binding cannot be changed. All `shortcuts.*` keys hot-reload - no restart needed.
 :::

 ## Mining Shortcuts
@@ -68,9 +66,8 @@ These control playback and subtitle display. They require overlay window focus.
 | `Ctrl+W`             | Quit mpv                                                   |
 | `Right-click`        | Toggle pause (outside subtitle area)                       |
 | `Right-click + drag` | Reposition subtitles (on subtitle area)                    |
-| `Ctrl/Cmd+A`         | Append clipboard video path to mpv playlist                |

-The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V`, `Ctrl/Cmd+A`, and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.
+The mpv-command rows above (`Space`, `F`, `J`, `Shift+J`, the seek/sub-seek/sub-step/sub-delay keys, replay/play-next, and quit) are merged from the `keybindings` config array and can be remapped or disabled there. `V` and the mouse actions are built-in overlay behaviors and are not part of the `keybindings` array. The playlist browser opens a split overlay modal with sibling video files on the left and the live mpv playlist on the right.

 On macOS managed playback, SubMiner disables mpv's menu-bar shortcuts so configured SubMiner shortcuts like `Cmd+Shift+O` reach the mpv plugin instead of opening native mpv menu actions.

@@ -85,13 +82,17 @@ Mouse-hover playback behavior is configured separately from shortcuts: `subtitle
 | `Ctrl/Cmd+Shift+O` | Open runtime options palette                             | `shortcuts.openRuntimeOptions`             |
 | `Ctrl/Cmd+/`       | Open session help modal                                  | `shortcuts.openSessionHelp`                |
 | `Ctrl+Shift+J`     | Open Jimaku subtitle search modal                        | `shortcuts.openJimaku`                     |
+| `Ctrl+Shift+T`     | Open TsukiHime subtitle search modal (EN/JA tabs)       | `shortcuts.openTsukihime`                 |
 | `Ctrl/Cmd+N`       | Toggle overlay notification history panel                | `shortcuts.toggleNotificationHistory`      |
 | `Ctrl+Alt+C`       | Open the manual YouTube subtitle picker                  | `keybindings`                              |
 | `Ctrl+Alt+S`       | Open subtitle sync (subsync) modal                       | `shortcuts.triggerSubsync`                 |
-| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey`                |
+| `Ctrl/Cmd+A`       | Append clipboard video path to mpv playlist              | `shortcuts.appendClipboardVideoToQueue`    |
+| `\`                | Toggle subtitle sidebar                                  | `subtitleSidebar.toggleKey` (overlay) / `shortcuts.toggleSubtitleSidebar` (mpv session binding) |
 | `` ` ``            | Toggle stats overlay                                     | `stats.toggleKey`                          |
 | `W`                | Mark current video watched and advance to next in queue  | `stats.markWatchedKey`                     |

+`shortcuts.openAnimetosho` remains accepted as a deprecated alias for `shortcuts.openTsukihime`. The current name takes precedence when both are configured.
+
 The stats toggle is handled inside the focused visible overlay window. It is configurable through the top-level `stats.toggleKey` setting and defaults to `Backquote`.

 The subtitle sidebar toggle is overlay-local and only opens when SubMiner has a parsed cue list for the active subtitle source.
@@ -109,7 +110,7 @@ Controller input only drives the overlay while keyboard-only mode is enabled. Th

 ## MPV Plugin Chords

-When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key within 1 second.
+When the mpv plugin is installed, all commands use a `y` chord prefix - press `y`, then the second key (the overlay-side chord times out after 1 second; the mpv plugin uses native mpv key sequences).

 | Chord | Action                                                     |
 | ----- | ---------------------------------------------------------- |
@@ -10,6 +10,8 @@ SubMiner's primary tokenizer is Yomitan itself - subtitle text is tokenized base

 Before any of those layers render, SubMiner strips annotation metadata from tokens that are usually just subtitle glue or annotation noise. Standalone particles, auxiliaries, adnominals, common explanatory endings like `んです` / `のだ`, merged trailing quote-particle forms like `...って`, auxiliary-stem grammar tails like `そうだ` (MeCab POS3 `助動詞語幹`), repeated kana interjections, and similar non-lexical helper tokens remain hoverable in the subtitle text, but they render as plain tokens without known-word, N+1, frequency, JLPT, or name-match annotation styling.

+Kanji vocabulary that MeCab labels `名詞/非自立`, such as `日` or `以外`, remains content for every annotation layer. The `非自立` exclusion only suppresses kana grammar nouns such as `こと` and `もの`.
+
 ## N+1 Word Highlighting

 N+1 highlighting identifies sentences where you know every word except one, making them ideal mining targets. When enabled, SubMiner builds a local cache of your known vocabulary from Anki and highlights tokens accordingly.
@@ -24,16 +26,16 @@ N+1 highlighting identifies sentences where you know every word except one, maki

 **Key settings:**

-| Option                                    | Default      | Description                                                                                                                                                   |
-| ----------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ankiConnect.knownWords.highlightEnabled` | `false`      | Enable known-word cache lookups used by N+1 highlighting                                                                                                      |
-| `ankiConnect.knownWords.refreshMinutes`   | `1440`       | Minutes between Anki cache refreshes                                                                                                                          |
-| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries                                                                                                                  |
-| `ankiConnect.knownWords.matchMode`        | `"headword"` | `"headword"` (dictionary form) or `"surface"` (raw text)                                                                                                      |
-| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting                                                                                                                               |
-| `ankiConnect.nPlusOne.minSentenceWords`   | `3`          | Minimum tokens in a sentence for N+1 to trigger                                                                                                               |
-| `subtitleStyle.nPlusOneColor`             | `#c6a0f6`    | Color for the single unknown target word                                                                                                                      |
-| `subtitleStyle.knownWordColor`            | `#a6da95`    | Color for already-known tokens                                                                                                                                |
+| Option                                    | Default      | Description                                              |
+| ----------------------------------------- | ------------ | -------------------------------------------------------- |
+| `ankiConnect.knownWords.highlightEnabled` | `false`      | Enable known-word cache lookups used by N+1 highlighting |
+| `ankiConnect.knownWords.refreshMinutes`   | `1440`       | Minutes between Anki cache refreshes                     |
+| `ankiConnect.knownWords.decks`            | `{}`         | Deck→fields map for known-word cache queries             |
+| `ankiConnect.knownWords.matchMode`        | `"headword"` | `"headword"` (dictionary form) or `"surface"` (raw text) |
+| `ankiConnect.nPlusOne.enabled`            | `false`      | Enable N+1 target highlighting                           |
+| `ankiConnect.nPlusOne.minSentenceWords`   | `3`          | Minimum tokens in a sentence for N+1 to trigger          |
+| `subtitleStyle.nPlusOneColor`             | `#c6a0f6`    | Color for the single unknown target word                 |
+| `subtitleStyle.knownWordColor`            | `#a6da95`    | Color for already-known tokens                           |

 Prefer expression/word fields for `ankiConnect.knownWords.decks`. Reading-only fields can mark unrelated homophones as known, so only include them when that tradeoff is intentional.

@@ -64,7 +66,7 @@ For full details on dictionary generation, name variant expansion, auto-sync lif

 ## Frequency Highlighting

-Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance. Frequency ranks are sourced from the **highest-ranked frequency dictionary** installed in Yomitan - other frequency dictionaries are not consulted.
+Frequency highlighting colors tokens based on how common they are, using dictionary frequency rank data. This helps you spot high-value vocabulary at a glance. For each token, ranks from the installed Yomitan frequency dictionaries are consulted in priority order: the highest-priority dictionary that has the term wins, lower-priority dictionaries fill in terms it lacks, and occurrence-based dictionaries are skipped.

 **Modes:**

@@ -126,22 +128,24 @@ All colors are customizable via the `subtitleStyle.jlptColors` object.

 ## Runtime Toggles

-All annotation layers can be toggled at runtime via the mpv command menu without restarting:
+These annotation layers can be toggled at runtime via the runtime options palette (`Ctrl/Cmd+Shift+O`) without restarting:

 - `ankiConnect.knownWords.highlightEnabled` (`On` / `Off`)
- `subtitleStyle.nameMatchEnabled` (`On` / `Off`)
- `subtitleStyle.nameMatchImagesEnabled` (`On` / `Off`)
+- `ankiConnect.knownWords.matchMode`
+- `ankiConnect.nPlusOne.enabled` (`On` / `Off`)
 - `subtitleStyle.enableJlpt` (`On` / `Off`)
 - `subtitleStyle.frequencyDictionary.enabled` (`On` / `Off`)

+(Character-name matching, `subtitleStyle.nameMatchEnabled`, is toggled through config or the Settings window, not the runtime palette.)
+
 Toggles only apply to new subtitle lines after the change - the currently displayed line is not re-tokenized in place.

 ## Rendering Priority

 When multiple annotations apply to the same token, the visual priority is:

-1. **N+1 target** (highest) - the single unknown word in an N+1 sentence
-2. **Character-name match** - dictionary-driven character-name token styling
+1. **Character-name match** (highest) - dictionary-driven character-name token styling; it clears the token's N+1, frequency, and JLPT annotations
+2. **N+1 target** - the single unknown word in an N+1 sentence
 3. **Known-word color** - already-learned token tint
-4. **Frequency highlight** - common-word coloring (not applied when N+1/character-name/known-word already matched)
-5. **JLPT underline** - level-based underline (stacks with the above since it uses underline rather than text color)
+4. **Frequency highlight** - common-word coloring (not applied when a higher layer already matched)
+5. **JLPT underline** - level-based underline (stacks with N+1/known/frequency since it uses underline rather than text color, but not with a character-name match)
@@ -164,7 +164,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo
 **Overlay does not appear**

 - Confirm SubMiner is running: `SubMiner.AppImage --start` or check for the process.
- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool` and `xwininfo` must be installed).
+- On Linux, the overlay requires a supported window backend. Hyprland and Sway have native Wayland support; all other compositors require both mpv and SubMiner to run under X11 or Xwayland (`xdotool`, `xprop`, and `xwininfo` must be installed).
 - On macOS, grant Accessibility permission to SubMiner in System Settings > Privacy & Security > Accessibility.

 **Overlay appears but clicks pass through / cannot interact**
@@ -177,7 +177,7 @@ Shown when SubMiner tries to update a card that no longer exists, or when AnkiCo

 - Renderer errors now trigger an automatic recovery path. You should see a short toast ("Renderer error recovered. Overlay is still running.").
 - Recovery closes any open modal and restores click-through/shortcuts automatically without interrupting mpv playback.
- If errors keep recurring, toggle the overlay's DevTools using overlay chord `y` then `d` (or global `F12`) and inspect the `renderer overlay recovery` error payload for stack trace + modal/subtitle context.
+- If errors keep recurring, toggle the overlay's DevTools using overlay chord `y` then `d` (`F12` also works in dev builds) and inspect the `renderer overlay recovery` error payload for stack trace + modal/subtitle context.

 **Overlay is on the wrong monitor or position**

@@ -258,22 +258,22 @@ Without FFmpeg, card creation still works but audio and image fields will be emp
 Media generation has a 30-second timeout (60 seconds for animated AVIF). If your video file is on a slow network mount or the codec requires software decoding, generation may time out. Try:

 - Using a local copy of the video file.
- Reducing `media.imageQuality` or switching from `avif` to `static` image type.
- Checking that `media.maxMediaDuration` is not set too high.
+- Reducing `ankiConnect.media.imageQuality` or switching from `avif` to `static` image type.
+- Checking that `ankiConnect.media.maxMediaDuration` is not set too high.

 ## Shortcuts

 **"Failed to register global shortcut"**

-Global shortcuts (`Alt+Shift+O`, `Alt+Shift+Y`) may conflict with other applications or desktop environment keybindings.
+This warning refers to the OS-registered shortcut `Alt+Shift+Y` (Yomitan settings), which is fixed and may conflict with other applications or desktop environment keybindings.

- Check your DE/WM keybinding settings for conflicts.
- Change the shortcut in your config under `shortcuts.toggleVisibleOverlayGlobal`.
+- Check your DE/WM keybinding settings for conflicts and free up `Alt+Shift+Y` there.
+- `Alt+Shift+O` (`shortcuts.toggleVisibleOverlayGlobal`) is not OS-registered - it is handled by the overlay window and the mpv plugin, so it does not trigger this warning and only needs those windows focused.
 - On Wayland, global shortcut registration has limitations depending on the compositor. Only Hyprland and Sway are supported natively - see the [Hyprland](#hyprland) section below for shortcut passthrough rules. Other Wayland compositors require X11/Xwayland.

 **Overlay keybindings not working**

-Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use the global shortcut to toggle it to give it focus.
+Overlay-local shortcuts (Space, arrow keys, etc.) only work when the overlay window has focus. Click on the overlay or use `Alt+Shift+O` (with the overlay or mpv focused) to toggle it and give it focus.

 ## Subtitle Timing

@@ -307,9 +307,9 @@ Install ffsubsync or configure the path:
 - **pip**: `pip install ffsubsync`
 - Must be on `PATH` or configured via `subsync.ffsubsync_path` in your config.

-**"Subtitle synchronization failed"**
+**"alass synchronization failed" / "ffsubsync synchronization failed"**

-If subtitle sync fails:
+If subtitle sync fails (the error message is prefixed with the engine name):

 - Ensure the reference subtitle track exists in the video (alass requires a source track).
 - Check that `ffmpeg` is available (used to extract the internal subtitle track).
@@ -0,0 +1,81 @@
+# TsukiHime Integration
+
+[TsukiHime](https://tsukihime.org) tracks anime torrent releases and extracts every attachment - including embedded subtitle tracks - from the release files, hosting them for direct download. SubMiner integrates with the TsukiHime API so you can pull English subtitles for the currently playing episode straight from the overlay, no torrent client involved. Downloaded subtitles are decompressed, saved next to the video, and loaded into mpv immediately.
+
+This is the multi-language companion to the [Jimaku integration](/jimaku-integration). Releases that ship multiple languages (e.g. Netflix `[MultiSub]` rips) expose them all; the modal's tabs pick which ones you see, and each download is saved with its own language suffix.
+
+::: tip Successor to Animetosho
+TsukiHime replaces [Animetosho](https://animetosho.org), which stops processing new releases in May 2026. TsukiHime imported the Animetosho index and mirrors its attachment storage, so older releases stay reachable alongside new ones.
+:::
+
+::: tip No API key required
+Unlike Jimaku, TsukiHime needs no account or API key. The only requirement is the `xz` binary on your `PATH` - TsukiHime serves extracted subtitles xz-compressed, and SubMiner shells out to `xz` to decompress them. Most Linux distributions ship it by default (package `xz` or `xz-utils`).
+:::
+
+## How It Works
+
+The integration runs through an in-overlay modal opened with `Ctrl+Shift+T` by default. The modal has two tabs that filter the subtitle tracks of the selected release by role: the first follows `secondarySub.secondarySubLanguages` (English when unset), and the second is always **Japanese**, the currently supported primary subtitle language. Tracks with no language tag stay visible on the secondary tab.
+
+When you open the modal, SubMiner parses the current video filename to extract a title and episode number (same parser as Jimaku - `S01E03`, `1x03`, `E03`, and dash-separated numbers all work). If the filename yields a high-confidence match, SubMiner auto-searches immediately.
+
+From there:
+
+1. **Search** - SubMiner queries TsukiHime with `<title> <episode>`. Results appear as a list of releases (e.g. `[SubsPlease] ... - 28 (1080p)`), each showing size, file count, and the subtitle languages the release carries.
+2. **Browse releases** - Select a release to list the text subtitle tracks extracted from its files. English tracks sort first; image-based tracks (PGS/VobSub) are filtered out.
+3. **Download** - Selecting a track downloads the xz-compressed subtitle from TsukiHime's storage, decompresses it, saves it next to the video (or a temp directory for remote/streamed media), and loads it into mpv. Japanese tracks are selected as mpv's **primary** subtitle. Tracks from the configured secondary tab are assigned to mpv's **secondary** subtitle slot without replacing the primary. The filename carries the track's language - `<video basename>.en.<ext>` for English, `.ja` for Japanese, and so on - so mpv and media servers detect the language correctly.
+
+Because releases on TsukiHime are the same files circulating as torrents, picking the release that matches your local file (same group, same version) gives you subtitles with exact timing - no resync needed. If your file is a raw or from a different group, pick any release of the same episode and adjust timing with the [subtitle sync tools](/troubleshooting#subtitle-sync-subsync) (`Ctrl+Alt+S`) if necessary.
+
+### Modal Keyboard Shortcuts
+
+| Key                          | Action                          |
+| ---------------------------- | ------------------------------- |
+| `Enter` (in text field)      | Search                          |
+| `Enter` (in list)            | Select release / download track |
+| `Arrow Up` / `Arrow Down`    | Navigate releases or tracks     |
+| `Arrow Left` / `Arrow Right` | Switch English / Japanese tab   |
+| `Escape`                     | Close modal                     |
+
+## Configuration
+
+The integration works out of the box. An optional `tsukihime` section in `config.jsonc` tunes it:
+
+```jsonc
+{
+  "tsukihime": {
+    "apiBaseUrl": "https://api.tsukihime.org/v1",
+    "maxSearchResults": 10,
+  },
+}
+```
+
+| Option                       | Type     | Default                          | Description                                                                |
+| ---------------------------- | -------- | -------------------------------- | -------------------------------------------------------------------------- |
+| `tsukihime.apiBaseUrl`       | `string` | `"https://api.tsukihime.org/v1"` | Base URL of the TsukiHime API. Only change this if using a mirror.         |
+| `tsukihime.maxSearchResults` | `number` | `10`                             | Maximum number of releases returned per search (the API caps this at 100). |
+
+The keyboard shortcut is configured separately under `shortcuts`:
+
+```jsonc
+{
+  "shortcuts": {
+    "openTsukihime": "Ctrl+Shift+T", // default; set to null to disable
+  },
+}
+```
+
+Existing Animetosho configuration remains compatible. SubMiner treats the old `animetosho` section and `shortcuts.openAnimetosho` setting as deprecated aliases. When old and current names are both present, `tsukihime` and `shortcuts.openTsukihime` take precedence.
+
+## Other Ways to Open It
+
+- CLI: `subminer --open-tsukihime`
+- Keybinding command: bind any key to `["__tsukihime-open"]` in the `keybindings` array
+
+The previous `--open-animetosho` flag and `__animetosho-open` keybinding command remain accepted as deprecated aliases.
+
+## Troubleshooting
+
+- **"xz binary not found"** - install `xz`/`xz-utils` with your package manager.
+- **"Batch releases are not supported"** - TsukiHime only exposes extracted attachments for single-file torrents. Pick the single-episode release for your episode instead of a season batch.
+- **"No text subtitle tracks in this release"** - the release only carries image-based subtitles (PGS/VobSub) or none at all; try a different release (fansub and SubsPlease-style releases almost always carry ASS tracks).
+- **Timing is off** - the subtitle came from a different release than your video file. Use the subtitle sync modal (`Ctrl+Alt+S`) or pick the release matching your file exactly.
@@ -60,13 +60,20 @@ The mpv plugin is always available - it's bundled with SubMiner and injected at

 While SubMiner is running, it watches your active config file and applies safe updates automatically.

-Live-updated settings:
+Live-updated settings include:

 - `subtitleStyle`
 - `keybindings`
 - `shortcuts`
 - `secondarySub.defaultMode`
- `ankiConnect.ai`
+- `subtitleSidebar`
+- `notifications`
+- `logging`
+- `jimaku`, `subsync`
+- `mpv.aniskipEnabled`, `mpv.aniskipButtonKey`
+- `stats.toggleKey`, `stats.markWatchedKey`
+- `youtube.primarySubLanguages`
+- most `ankiConnect.*` settings (including `ankiConnect.ai`)

 Invalid config edits are rejected; SubMiner keeps the previous valid runtime config and shows an error notification.
 For restart-required sections, SubMiner shows a restart-needed notification.
@@ -82,12 +89,13 @@ subminer -R                       # Use rofi instead of fzf
 subminer -d ~/Videos              # Specific directory
 subminer -r -d ~/Anime            # Recursive search
 subminer video.mkv                # Play specific file (overlay auto-starts)
-subminer --start video.mkv        # Explicit overlay start (use when auto_start=no in config)
-subminer -S video.mkv             # Same as above via --start-overlay
+subminer --start video.mkv        # Explicit overlay start (use when mpv.autoStartSubMiner is false in config)
+subminer -S video.mkv             # Also force the visible overlay on start (--start-overlay)
 subminer https://youtu.be/...     # Play a YouTube URL
 subminer ytsearch:"jp news"       # Play first YouTube search result
-subminer --setup                  # Open first-run setup popup
-subminer --version                # Print installed SubMiner version
+subminer -H                       # Browse history, then choose previous/replay/next after playback
+subminer app --setup              # Open first-run setup popup
+subminer --version                # Print the launcher's version
 subminer -v                       # Same as above
 subminer --log-level debug video.mkv # Enable verbose logs for launch/debugging
 subminer --log-level warn video.mkv  # Set logging level explicitly
@@ -111,11 +119,24 @@ subminer config show              # Print active config contents
 subminer mpv socket               # Print active mpv socket path
 subminer mpv status               # Exit 0 if socket is ready, else exit 1
 subminer mpv idle                 # Launch detached idle mpv with SubMiner defaults
+subminer sync media-box           # Sync stats/watch history with an SSH host
+subminer sync media-box --push    # Merge this machine's stats into the host only
+subminer sync media-box --pull    # Merge the host's stats into this machine only
+subminer sync media-box --check   # Verify SSH and remote SubMiner without syncing
+subminer sync media-box --json    # Emit machine-readable NDJSON progress
+subminer sync --ui                # Open the Sync Stats & History window
+subminer sync --snapshot ~/subminer-snapshot.sqlite  # Write a local DB snapshot
+subminer sync --merge ~/subminer-snapshot.sqlite     # Merge a snapshot into the local DB
+subminer sync --make-temp         # Create an internal sync temp directory
+subminer sync --remove-temp /tmp/subminer-sync-123   # Remove an internal sync temp directory
 subminer dictionary /path/to/file-or-directory  # Generate character dictionary ZIP from target (manual Yomitan import)
 subminer dictionary --candidates /path/to/file.mkv
 subminer dictionary --select 21355 /path/to/file.mkv
 subminer texthooker               # Launch texthooker-only mode
 subminer texthooker -o            # Launch texthooker and open it in your browser
+subminer stats                    # Start the local stats server (see Immersion Tracking)
+subminer stats -b                 # Start/reuse the background stats daemon
+subminer stats -s                 # Stop the background stats daemon
 subminer app --anilist-setup      # Pass args directly to SubMiner binary (example: AniList login flow)

 # Direct packaged app control
@@ -129,6 +150,8 @@ SubMiner.AppImage --start --toggle        # Start MPV IPC + toggle visibility
 SubMiner.AppImage --show-visible-overlay              # Force show visible overlay
 SubMiner.AppImage --hide-visible-overlay              # Force hide visible overlay
 SubMiner.AppImage --toggle-primary-subtitle-bar       # Toggle primary subtitle bar visibility
+SubMiner.AppImage --toggle-subtitle-sidebar           # Toggle the subtitle sidebar
+SubMiner.AppImage --open-tsukihime                    # Open TsukiHime subtitle search
 SubMiner.AppImage --start --dev                         # Enable app/dev mode only
 SubMiner.AppImage --start --debug                       # Alias for --dev
 SubMiner.AppImage --start --log-level debug             # Force verbose logging without app/dev mode
@@ -142,12 +165,18 @@ SubMiner.AppImage --jellyfin-libraries
 SubMiner.AppImage --jellyfin-items --jellyfin-library-id LIBRARY_ID --jellyfin-search anime --jellyfin-limit 20
 SubMiner.AppImage --jellyfin-play --jellyfin-item-id ITEM_ID --jellyfin-audio-stream-index 1 --jellyfin-subtitle-stream-index 2  # Requires connected mpv IPC (--start)
 SubMiner.AppImage --jellyfin-remote-announce  # Force cast-target capability announce + visibility check
+SubMiner.AppImage --sync-cli --help           # Show the packaged app's headless sync help
+SubMiner.AppImage --sync-cli sync media-box   # Run the sync engine directly in headless mode
 SubMiner.AppImage --dictionary             # Generate character dictionary ZIP for current anime
 SubMiner.AppImage --dictionary-candidates  # List AniList candidates for current character dictionary series
 SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355  # Pin correct AniList media for series
 SubMiner.AppImage --help                  # Show all options
 ```

+`--check` performs connection and version checks without changing data. `--json` emits the NDJSON event protocol used by the sync window. `--ui` opens that window in a detached app process and returns the shell immediately; closing a standalone-launched Sync window exits that app instance. `--make-temp` and `--remove-temp` are internal remote-transfer helpers and should normally be left to SubMiner. The packaged app's `--sync-cli` flag selects its headless sync-compatible entrypoint; the `subminer sync` launcher command proxies to it automatically.
+
+The previous `--open-animetosho` flag remains accepted as a deprecated alias for `--open-tsukihime`.
+
 The tray menu includes `Export Logs`, which creates the same sanitized local-date log ZIP as `subminer logs -e` and shows the archive path when complete. Export sanitization masks common PII and secrets, including home-directory usernames, IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL query strings. The exported copy is sanitized; source log files remain unredacted on disk.

 Once Jellyfin is configured, the tray menu includes `Jellyfin Discovery` for starting or stopping cast discovery in the current app session without changing config.
@@ -194,6 +223,7 @@ This flow requires `mpv.exe` to be discoverable. Leave `mpv.executablePath` blan
 - `subminer logs -e`: export a sanitized ZIP of today's local-date logs, or the most recent logs when no current-day log exists. The exported copy masks common PII and secrets; on-disk logs are unchanged.
 - `subminer config`: config file helpers (`path`, `show`).
 - `subminer mpv`: mpv helpers (`status`, `socket`, `idle`).
+- `subminer sync <host>`: sync immersion stats and watch history with another machine over SSH. The host is the SSH destination (`user@host` or an SSH config alias). Use `--push` to merge only this machine's data into the host, or `--pull` to merge only the host's data into this machine; both remain insert-only and do not make either database an exact mirror. Remote launcher checks include standard SubMiner and Bun paths even when SSH omits them from `PATH`. Use `--snapshot <file>` to write a consistent local stats DB snapshot, `--merge <file>` to merge a snapshot into the local stats DB, and `--force` to skip the running stats/mpv safety check. Advanced options: `--db <file>` overrides the local stats DB path, and `--remote-cmd <cmd>` overrides the `subminer` command used on the remote host.
 - `subminer dictionary <path>`: generates a Yomitan-importable character dictionary ZIP from a file/directory target.
 - Use `subminer dictionary --candidates <path>` and `subminer dictionary --select <id> <path>` to correct AniList character-dictionary matches for a whole series.
 - `subminer texthooker`: texthooker-only shortcut (same behavior as `--texthooker`). A _texthooker_ is a web page that displays the current subtitle line as selectable text, so browser-based dictionary extensions and other tools can read along with playback.
@@ -207,7 +237,7 @@ Setup popup appears on first launch, or when setup has not been completed.
 You can also open it manually:

 ```bash
-subminer --setup
+subminer app --setup
 SubMiner.AppImage --setup
 ```

@@ -243,6 +273,7 @@ Top-level launcher flags like `--jellyfin-*` are intentionally rejected.
 - `--sub-file-paths=.;subs;subtitles`
 - `--sid=auto`
 - `--secondary-sid=auto`
+- `--sub-visibility=no` (the overlay renders subtitles instead of mpv)
 - `--secondary-sub-visibility=no`

 You can append additional MPV arguments with launcher `-a/--args`, for example `--args "--ao=alsa --volume=80"`.
@@ -288,8 +319,8 @@ Notes:
 - Press `Ctrl+Alt+C` during active YouTube playback to open the manual YouTube subtitle picker and retry track selection.
 - For YouTube URLs, `subminer` probes available YouTube subtitle tracks, reuses existing authoritative tracks when available, and downloads only missing sides.
 - Native mpv secondary subtitle rendering stays hidden so the overlay remains the visible secondary subtitle surface.
- Primary subtitle target languages come from `youtube.primarySubLanguages` (defaults to `["ja","jpn"]`).
- Secondary target languages come from `secondarySub.secondarySubLanguages` (empty by default; when empty, no language-based secondary track is auto-selected, though mpv's `--slang` list above still prefers English variants). When multiple matching secondary tracks exist, SubMiner prefers a non-Signs/Songs track.
+- YouTube auto-selection always targets a Japanese primary track and an English secondary track (manual uploads preferred over auto-generated captions). `youtube.primarySubLanguages` (defaults to `["ja","jpn"]`) defines which loaded track counts as a satisfactory primary for the missing-subtitle notification and for managed local/playlist selection.
+- When multiple matching secondary tracks exist, SubMiner prefers a non-Signs/Songs track.
 - Configure defaults in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc`) under `youtube` and `secondarySub`.

 For local video files, SubMiner uses the same config-driven language priorities to auto-select the primary and secondary subtitle tracks from internal and external subtitle sources.
@@ -324,6 +355,8 @@ By default SubMiner uses the first connected controller after controller support
 | `Select` / `Minus`      | Quit mpv                                |
 | `L2` / `R2`             | Unbound (available for custom bindings) |

+Note: the default quit binding uses gamepad button index 6. Pads that follow the W3C standard gamepad layout report L2 as index 6 (Select is index 8), so on those controllers the quit action may fire on L2 instead - use `Alt+C` learn mode to remap it for your pad.
+
 ### Analog Controls

 | Input                 | Action                                        |
@@ -341,18 +374,18 @@ All button and axis mappings are configurable under the `controller` config bloc

 See [Keyboard Shortcuts](/shortcuts) for the full reference, including mining shortcuts, overlay controls, and customization.

-**Global shortcuts** (work system-wide):
+**App-wide shortcuts:**

-| Keybind       | Action                 |
-| ------------- | ---------------------- |
-| `Alt+Shift+O` | Toggle visible overlay |
-| `Alt+Shift+Y` | Open Yomitan settings  |
+| Keybind       | Action                 | Scope                                                                                              |
+| ------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `Alt+Shift+O` | Toggle visible overlay | Works while the overlay or mpv has focus (configurable via `shortcuts.toggleVisibleOverlayGlobal`) |
+| `Alt+Shift+Y` | Open Yomitan settings  | OS-global - registered with the system, works from any window                                      |

 `Alt+Shift+Y` is fixed and not configurable. All other shortcuts can be changed under `shortcuts` in your config.

 Useful overlay-local default keybinding: `Ctrl+Alt+P` opens the playlist browser for the current video's parent directory and the live mpv queue so you can append, reorder, remove, or jump between episodes without leaving playback.

-Press `V` to hide or restore the primary SubMiner subtitle bar. The bundled mpv plugin also binds bare `v` to the same action (injected at runtime).
+Press `V` to cycle the primary SubMiner subtitle bar through hidden → visible → hover modes. The bundled mpv plugin also binds bare `v` to the same action (injected at runtime).

 `Ctrl/Cmd+/` opens the session help modal with the current overlay and mpv keybindings. The same help view is also available through the `y-h` chord in mpv.

@@ -362,5 +395,6 @@ Hovering over subtitle text pauses mpv by default; leaving resumes it. Yomitan p

 - Drop video files onto the overlay to replace current playback.
 - Hold `Shift` while dropping to append to the playlist instead.
+- Drop subtitle files onto the overlay to load them as a new subtitle track.

 Next: [Mining Workflow](/mining-workflow) - word lookup, card creation, and the full mining loop.
@@ -265,9 +265,15 @@ script-message subminer-options
 script-message subminer-restart
 script-message subminer-status
 script-message subminer-autoplay-ready
+script-message subminer-stats-toggle
+script-message subminer-visible-overlay-shown
+script-message subminer-visible-overlay-hidden
+script-message subminer-managed-subtitles-loading
+script-message subminer-overlay-loading-ready
+script-message subminer-reload-session-bindings
 ```

-The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) are handled by the SubMiner app over the mpv IPC socket while it is connected.
+The overlay/loading/session-binding messages are primarily sent by the SubMiner app to keep the plugin's state in sync. The AniSkip messages (`subminer-skip-intro`, `subminer-aniskip-refresh`) are handled by the SubMiner app over the mpv IPC socket while it is connected.

 The start command also accepts inline overrides:

@@ -96,7 +96,7 @@ For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (Ti

 By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.

-Background cache downloads use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.
+Background cache downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`; set `0` for unlimited) and use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.

 ## Configuration Reference

@@ -112,11 +112,13 @@ Background cache downloads use IPv4 and retry flags to reduce YouTube throttling

 | Option                | Type       | Description                                                                           |
 | --------------------- | ---------- | ------------------------------------------------------------------------------------- |
-| `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |
+| `primarySubLanguages` | `string[]` | Languages that count as a satisfactory primary subtitle (default `["ja", "jpn"]`). Used by the "primary subtitle missing" notification and by managed local/playlist subtitle selection. |
+
+YouTube auto-selection itself always picks a Japanese track first (manual over auto), then falls back to any manual track — `primarySubLanguages` does not change which YouTube track is auto-picked.

 ### Secondary Subtitle Languages

-Secondary track selection uses the shared `secondarySub` config:
+YouTube secondary selection is fixed: SubMiner always tries an English track (manual over auto) and loads it when found. The shared `secondarySub` config does not change YouTube track selection — `secondarySubLanguages` and `autoLoadSecondarySub` apply only to local/Jellyfin sidecar selection — but `defaultMode` still controls how the loaded secondary bar is displayed:

 ```jsonc
 {
@@ -130,11 +132,11 @@ Secondary track selection uses the shared `secondarySub` config:

 | Option                  | Type                                 | Description                                                                                                                                                                                         |
 | ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
-| `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary track (default: `false`)                                                                                                                                  |
+| `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track for local/Jellyfin sidecar files. Default is empty (`[]`). Not used for YouTube. |
+| `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary sidecar track for local files (default: `false`). Not used for YouTube.                                                       |
 | `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                                                   |

-Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
+These settings come from `config.jsonc` (or built-in defaults); there are no CLI flags or environment variables for subtitle language selection.

 ## Limitations and Troubleshooting

@@ -85,6 +85,7 @@ Notes:
 - Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut. `make clean` preserves `release/prerelease-notes.md` while deleting generated build artifacts.
 - If you need to repair a published release body (for example, a prior version’s section was omitted), regenerate notes from `CHANGELOG.md` and re-edit the release with `gh release edit --notes-file`.
 - Prerelease tags are handled by `.github/workflows/prerelease.yml`, which always publishes a GitHub prerelease with all current release platforms and never runs the AUR sync job.
+- CI, stable release, and prerelease workflows call the shared `.github/workflows/quality-gate.yml`; update that reusable workflow when changing common test coverage. Its environment suite includes the Lua mpv plugin tests.
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.
 - Stable release tags update `https://docs.subminer.moe/` and `https://docs.subminer.moe/v/<version>/` through `.github/workflows/docs-pages.yml`; `/main/` continues to show development docs from `main`.
 - Keep Cloudflare Pages Git auto-deploy disabled for `docs.subminer.moe`. Production docs are direct-uploaded by Wrangler from GitHub Actions with `--branch main`.
@@ -31,6 +31,8 @@ The desktop app keeps `src/main.ts` as composition root and pushes behavior into
 - `src/config/` owns config definitions, defaults, loading, and resolution.
 - `src/types/` owns shared cross-runtime contracts via domain entrypoints; `src/types.ts` stays a compatibility barrel.
 - `src/main/runtime/composers/` owns larger domain compositions.
+- `src/main.ts` call sites invoke configured runtime handlers and runtime-object methods directly;
+  do not add local pass-through wrappers around them.

 ## Architecture Intent

@@ -3,7 +3,7 @@
 # Domain Ownership

 Status: active
-Last verified: 2026-05-23
+Last verified: 2026-07-15
 Owner: Kyle Yasuda
 Read when: you need to find the owner module for a behavior or test surface

@@ -16,7 +16,9 @@ Read when: you need to find the owner module for a behavior or test surface

 ## Product / Integration Domains

- Config system: `src/config/`
+- Config system: `src/config/`; Anki resolution is composed by
+  `src/config/resolve/anki-connect.ts` from focused resolvers in
+  `src/config/resolve/anki-connect/`
 - Overlay/window state: `src/core/services/overlay-*`, `src/main/overlay-*.ts`
 - MPV runtime and protocol: `src/core/services/mpv*.ts`
 - Subtitle/token pipeline: `src/core/services/subtitle-*.ts`, `src/core/services/tokenizer*`, `src/core/services/tokenizer/`, `src/subsync/`
@@ -26,7 +28,9 @@ Read when: you need to find the owner module for a behavior or test surface
 - AniList tracking + character dictionary: `src/core/services/anilist/`, `src/main/runtime/composers/anilist-*`, `src/main/character-dictionary-runtime.ts`, `src/main/character-dictionary-runtime/`
 - Jellyfin integration: `src/core/services/jellyfin*.ts`, `src/main/runtime/composers/jellyfin-*`
 - Window trackers: `src/window-trackers/`
- Stats app: `stats/`
+- Stats HTTP app: `src/core/services/stats-server.ts`, with route groups and shared route support
+  in `src/core/services/stats-server/`
+- Stats SPA: `stats/`
 - Public docs site: `docs-site/`

 ## Shared Contract Entry Points
@@ -39,6 +43,7 @@ Read when: you need to find the owner module for a behavior or test surface
 - Runtime-option contracts: `src/types/runtime-options.ts`
 - Settings UI contracts: `src/types/settings.ts`
 - Session-binding contracts: `src/types/session-bindings.ts`
+- Stats HTTP wire contracts: `src/types/stats-wire.ts`, `src/types/stats-http-contract.ts`
 - Compatibility-only barrel: `src/types.ts`

 ## Ownership Heuristics
@@ -33,6 +33,10 @@ Trend charts now consume one chart-oriented backend payload from `/api/stats/tre

 ## Contract

+Stats data crosses the process boundary over HTTP only. Shared JSON models live in `src/types/stats-wire.ts`; endpoint request/response mappings and the client interface live in `src/types/stats-http-contract.ts`. The server and stats client both type-check against those files. `stats/src/types/stats.ts` is a compatibility re-export, not an independent contract copy.
+
+The stats preload bridge remains limited to native window behavior such as confirmation-dialog layering. Do not add stats data request channels back to Electron IPC.
+
 The stats UI should treat the trends payload as chart-ready data. Presentation-only work in the client is fine, but rebuilding the main trend datasets from raw sessions should stay out of the render path.

 For session detail timelines, omitting `limit` now means "return the full retained session telemetry/history". Explicit `limit` remains available for bounded callers, but the default stats UI path should not trim long sessions to the newest 200 samples.
@@ -17,7 +17,12 @@ Read when: selecting the right verification lane for a change
  one file cannot cascade into the rest of the lane. `--jobs N` parallelizes;
  `--single-process` restores the shared-process mode for debugging.
 - `bun run test:fast` is the full source gate: discovered `src/**`, launcher
-  unit, `scripts/**`, and the compiled runtime-compat slice.
+  unit, and `scripts/**`.
+- `.github/workflows/quality-gate.yml` is the reusable `workflow_call` gate for
+  pull requests, stable tags, and prerelease tags. Keep common quality steps
+  there instead of copying them into caller workflows.
+- The reusable gate installs Lua and runs `bun run test:env`, so the shipped mpv
+  plugin tests run for every pull request and tagged release.

 ## Default Handoff Gate

@@ -52,7 +57,14 @@ bun run docs:build

 - `bun run test:coverage:src` runs the maintained `test:src` lane through a sharded coverage runner: one Bun coverage process per test file, then merged LCOV output.
 - Machine-readable output lands at `coverage/test-src/lcov.info`.
- CI and release quality-gate runs upload that LCOV file as the `coverage-test-src` artifact.
+- Every reusable quality-gate run uploads that LCOV file as the
+  `coverage-test-src` artifact.
+
+## Dependency Audit Policy
+
+- `bun audit --audit-level high` blocks the reusable quality gate.
+- Keep security overrides and dependency patches at the minimum fixed version.
+  Remove them after the owning package ships and adopts a compatible fix.

 ## Rules

@@ -1,4 +1,5 @@
 import {
+  launchAppCommandDetached,
  launchAppBackgroundDetached,
  launchTexthookerOnly,
  runAppCommandWithInherit,
@@ -7,6 +8,10 @@ import type { LauncherCommandContext } from './context.js';

 type AppCommandDeps = {
  runAppCommandWithInherit: (appPath: string, appArgs: string[]) => void;
+  launchSyncUiDetached: (
+    appPath: string,
+    logLevel: LauncherCommandContext['args']['logLevel'],
+  ) => void;
  launchAppBackgroundDetached: (
    appPath: string,
    logLevel: LauncherCommandContext['args']['logLevel'],
@@ -15,6 +20,8 @@ type AppCommandDeps = {

 const defaultAppCommandDeps: AppCommandDeps = {
  runAppCommandWithInherit,
+  launchSyncUiDetached: (appPath, logLevel) =>
+    launchAppCommandDetached(appPath, ['--sync-window'], logLevel, 'sync-ui'),
  launchAppBackgroundDetached,
 };

@@ -30,6 +37,10 @@ export function runAppPassthroughCommand(
    deps.runAppCommandWithInherit(appPath, ['--settings']);
    return true;
  }
+  if (args.syncUi) {
+    deps.launchSyncUiDetached(appPath, args.logLevel);
+    return true;
+  }
  if (!args.appPassthrough) {
    return false;
  }
@@ -206,6 +206,7 @@ test('app command starts default macOS background app detached from launcher', (
    runAppCommandWithInherit: () => {
      calls.push('attached');
    },
+    launchSyncUiDetached: () => calls.push('sync-ui'),
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -225,6 +226,7 @@ test('app command starts default Linux background app detached from launcher', (
    runAppCommandWithInherit: () => {
      calls.push('attached');
    },
+    launchSyncUiDetached: () => calls.push('sync-ui'),
    launchAppBackgroundDetached: (appPath, logLevel) => {
      calls.push(`detached:${appPath}:${logLevel}`);
    },
@@ -245,6 +247,7 @@ test('app command keeps explicit passthrough args attached', () => {
    runAppCommandWithInherit: (_appPath, appArgs) => {
      forwarded.push(appArgs);
    },
+    launchSyncUiDetached: () => detached.push('sync-ui'),
    launchAppBackgroundDetached: () => {
      detached.push('detached');
    },
@@ -255,6 +258,21 @@ test('app command keeps explicit passthrough args attached', () => {
  assert.deepEqual(detached, []);
 });

+test('sync UI command launches the app detached from the terminal', () => {
+  const context = createContext();
+  context.args.syncUi = true;
+  const calls: string[] = [];
+
+  const handled = runAppPassthroughCommand(context, {
+    runAppCommandWithInherit: () => calls.push('piped'),
+    launchSyncUiDetached: (appPath, logLevel) => calls.push(`sync-ui:${appPath}:${logLevel}`),
+    launchAppBackgroundDetached: () => calls.push('detached'),
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, ['sync-ui:/tmp/subminer.app:warn']);
+});
+
 test('mpv pre-app command exits non-zero when socket is not ready', async () => {
  const context = createContext();
  context.args.mpvStatus = true;
@@ -7,11 +7,13 @@ import {
  collectVideos,
  findRofiTheme,
  formatPickerLaunchError,
+  formatRofiPrompt,
  showFzfMenu,
  showRofiMenu,
 } from '../picker.js';
 import {
  findNextEpisode,
+  findPreviousEpisode,
  groupHistoryBySeries,
  listSeasonDirs,
  materializeCoverArt,
@@ -23,6 +25,167 @@ import {
 import type { Args } from '../types.js';
 import type { LauncherCommandContext } from './context.js';

+export type HistorySessionAction = 'previous' | 'replay' | 'next' | 'browse' | 'quit';
+
+export interface HistoryPlaybackSelection {
+  entry: HistorySeriesEntry;
+  videoPath: string;
+  themePath?: string | null;
+  entryIcon?: string | null;
+}
+
+interface HistorySessionMenuAction {
+  kind: HistorySessionAction;
+  label: string;
+}
+
+export function buildHistorySessionActions(
+  justPlayedPath: string,
+  previousEpisodePath: string | null,
+  nextEpisodePath: string | null,
+): HistorySessionMenuAction[] {
+  const actions: HistorySessionMenuAction[] = [];
+  if (previousEpisodePath) {
+    actions.push({
+      kind: 'previous',
+      label: `Previous episode: ${path.basename(previousEpisodePath)}`,
+    });
+  }
+  actions.push({
+    kind: 'replay',
+    label: `Rewatch episode: ${path.basename(justPlayedPath)}`,
+  });
+  if (nextEpisodePath) {
+    actions.push({
+      kind: 'next',
+      label: `Play next episode: ${path.basename(nextEpisodePath)}`,
+    });
+  }
+  actions.push(
+    { kind: 'browse', label: 'Select / browse episode' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  );
+  return actions;
+}
+
+export function buildHistoryEntryActions(
+  lastWatchedPath: string | null,
+  previousEpisodePath: string | null,
+  nextEpisodePath: string | null,
+): HistorySessionMenuAction[] {
+  const actions: HistorySessionMenuAction[] = [];
+  if (previousEpisodePath) {
+    actions.push({
+      kind: 'previous',
+      label: `Previous episode: ${path.basename(previousEpisodePath)}`,
+    });
+  }
+  if (lastWatchedPath) {
+    actions.push({
+      kind: 'replay',
+      label: `Replay last watched: ${path.basename(lastWatchedPath)}`,
+    });
+  }
+  if (nextEpisodePath) {
+    actions.push({ kind: 'next', label: `Next episode: ${path.basename(nextEpisodePath)}` });
+  }
+  actions.push(
+    { kind: 'browse', label: 'Browse episodes' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  );
+  return actions;
+}
+
+interface HistoryPlaybackLoopDeps {
+  play: (videoPath: string) => Promise<void>;
+  pickPostPlaybackAction: (input: {
+    entry: HistorySeriesEntry;
+    justPlayedPath: string;
+    previousEpisodePath: string | null;
+    nextEpisodePath: string | null;
+  }) => Promise<HistorySessionAction | null>;
+  findPreviousEpisode: (videoPath: string) => string | null;
+  findNextEpisode: (videoPath: string) => string | null;
+  browseEpisodes: (entry: HistorySeriesEntry) => Promise<string | null>;
+}
+
+export async function runHistoryPlaybackLoop(
+  initial: HistoryPlaybackSelection,
+  deps: HistoryPlaybackLoopDeps,
+): Promise<void> {
+  let videoPath = initial.videoPath;
+
+  while (true) {
+    await deps.play(videoPath);
+    const previousEpisodePath = deps.findPreviousEpisode(videoPath);
+    const nextEpisodePath = deps.findNextEpisode(videoPath);
+    const action = await deps.pickPostPlaybackAction({
+      entry: initial.entry,
+      justPlayedPath: videoPath,
+      previousEpisodePath,
+      nextEpisodePath,
+    });
+
+    switch (action) {
+      case 'replay':
+        break;
+      case 'previous':
+        if (!previousEpisodePath) return;
+        videoPath = previousEpisodePath;
+        break;
+      case 'next':
+        if (!nextEpisodePath) return;
+        videoPath = nextEpisodePath;
+        break;
+      case 'browse': {
+        const browsedPath = await deps.browseEpisodes(initial.entry);
+        if (!browsedPath) return;
+        videoPath = browsedPath;
+        break;
+      }
+      case 'quit':
+      case null:
+        return;
+    }
+  }
+}
+
+export async function runHistorySession(
+  context: LauncherCommandContext,
+  play: (videoPath: string) => Promise<void>,
+): Promise<boolean> {
+  const initial = await runHistoryCommand(context);
+  if (!initial) return false;
+
+  await runHistoryPlaybackLoop(initial, {
+    play,
+    findPreviousEpisode,
+    findNextEpisode,
+    browseEpisodes: async (entry) => browseEpisodes(entry, context, initial.themePath ?? null),
+    pickPostPlaybackAction: async ({
+      entry,
+      justPlayedPath,
+      previousEpisodePath,
+      nextEpisodePath,
+    }) => {
+      const actions = buildHistorySessionActions(
+        justPlayedPath,
+        previousEpisodePath,
+        nextEpisodePath,
+      );
+      const actionIdx = pickIndex(
+        actions.map((action) => action.label),
+        entry.displayName,
+        context.args.useRofi,
+        initial.themePath ?? null,
+        actions.map(() => initial.entryIcon ?? null),
+      );
+      return actionIdx < 0 ? null : actions[actionIdx]!.kind;
+    },
+  });
+  return true;
+}
+
 function checkPickerDependencies(args: Args): void {
  if (args.useRofi) {
    if (!commandExists('rofi')) fail('Missing dependency: rofi');
@@ -37,7 +200,16 @@ function showRofiIndexMenu(
  themePath: string | null,
  icons: Array<string | null> = [],
 ): number {
-  const rofiArgs = ['-dmenu', '-i', '-matching', 'fuzzy', '-format', 'i', '-p', prompt];
+  const rofiArgs = [
+    '-dmenu',
+    '-i',
+    '-matching',
+    'fuzzy',
+    '-format',
+    'i',
+    '-p',
+    formatRofiPrompt(prompt),
+  ];
  const hasIcons = icons.some(Boolean);
  if (hasIcons) rofiArgs.push('-show-icons');
  if (themePath) {
@@ -142,7 +314,7 @@ function browseEpisodes(
  if (seasons.length > 1) {
    const idx = pickIndex(
      seasons.map((season) => season.name),
-      `${entry.displayName} — Season`,
+      `${entry.displayName}: Season`,
      args.useRofi,
      themePath,
    );
@@ -155,7 +327,9 @@ function browseEpisodes(
  return pickEpisodeFromDir(dir, context);
 }

-export async function runHistoryCommand(context: LauncherCommandContext): Promise<string | null> {
+export async function runHistoryCommand(
+  context: LauncherCommandContext,
+): Promise<HistoryPlaybackSelection | null> {
  const { args, scriptPath } = context;

  checkPickerDependencies(args);
@@ -196,16 +370,14 @@ export async function runHistoryCommand(context: LauncherCommandContext): Promis

  const lastPath = path.resolve(entry.lastWatched.sourcePath);
  const lastExists = fs.existsSync(lastPath);
+  const previousEpisode = findPreviousEpisode(lastPath);
  const nextEpisode = findNextEpisode(lastPath);

-  const actions: Array<{ kind: 'replay' | 'next' | 'browse'; label: string }> = [];
-  if (lastExists) {
-    actions.push({ kind: 'replay', label: `Replay last watched — ${path.basename(lastPath)}` });
-  }
-  if (nextEpisode) {
-    actions.push({ kind: 'next', label: `Next episode — ${path.basename(nextEpisode)}` });
-  }
-  actions.push({ kind: 'browse', label: 'Browse episodes' });
+  const actions = buildHistoryEntryActions(
+    lastExists ? lastPath : null,
+    previousEpisode,
+    nextEpisode,
+  );

  const entryIcon = seriesIcons[seriesIdx] ?? null;
  const actionIdx = pickIndex(
@@ -219,10 +391,16 @@ export async function runHistoryCommand(context: LauncherCommandContext): Promis

  switch (actions[actionIdx]!.kind) {
    case 'replay':
-      return lastPath;
+      return { entry, videoPath: lastPath, themePath, entryIcon };
+    case 'previous':
+      return previousEpisode ? { entry, videoPath: previousEpisode, themePath, entryIcon } : null;
    case 'next':
-      return nextEpisode;
-    case 'browse':
-      return browseEpisodes(entry, context, themePath);
+      return nextEpisode ? { entry, videoPath: nextEpisode, themePath, entryIcon } : null;
+    case 'browse': {
+      const videoPath = browseEpisodes(entry, context, themePath);
+      return videoPath ? { entry, videoPath, themePath, entryIcon } : null;
+    }
+    case 'quit':
+      return null;
  }
 }
@@ -0,0 +1,294 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {
+  buildHistoryEntryActions,
+  buildHistorySessionActions,
+  runHistoryPlaybackLoop,
+} from './history-command.js';
+import type { HistorySeriesEntry } from '../history.js';
+
+type HistoryLoop = (
+  initial: { entry: HistorySeriesEntry; videoPath: string },
+  deps: {
+    play: (videoPath: string) => Promise<void>;
+    pickPostPlaybackAction: (input: {
+      entry: HistorySeriesEntry;
+      justPlayedPath: string;
+      previousEpisodePath: string | null;
+      nextEpisodePath: string | null;
+    }) => Promise<'previous' | 'replay' | 'next' | 'browse' | 'quit' | null>;
+    findPreviousEpisode: (videoPath: string) => string | null;
+    findNextEpisode: (videoPath: string) => string | null;
+    browseEpisodes: (entry: HistorySeriesEntry) => Promise<string | null>;
+  },
+) => Promise<void>;
+
+const typedRunHistoryPlaybackLoop: HistoryLoop = runHistoryPlaybackLoop;
+
+function makeEntry(lastWatchedPath: string): HistorySeriesEntry {
+  return {
+    seriesRoot: path.dirname(lastWatchedPath),
+    displayName: 'Test Show',
+    coverBlobHash: null,
+    lastWatched: {
+      videoId: 1,
+      sourcePath: lastWatchedPath,
+      parsedTitle: 'Test Show',
+      parsedSeason: 1,
+      parsedEpisode: 1,
+      animeTitle: 'Test Show',
+      lastWatchedMs: 1,
+      coverBlobHash: null,
+    },
+  };
+}
+
+test('history loop plays an initial selection, browsed selection, then quits', async () => {
+  assert.equal(
+    typeof runHistoryPlaybackLoop,
+    'function',
+    'history playback loop is not implemented',
+  );
+  const entry = makeEntry('/shows/test-show/episode-01.mkv');
+  const played: string[] = [];
+  const menuEntries: HistorySeriesEntry[] = [];
+  let menuCount = 0;
+
+  await typedRunHistoryPlaybackLoop(
+    { entry, videoPath: '/shows/test-show/episode-02.mkv' },
+    {
+      play: async (videoPath) => {
+        played.push(videoPath);
+      },
+      pickPostPlaybackAction: async ({ entry: menuEntry }) => {
+        menuEntries.push(menuEntry);
+        return menuCount++ === 0 ? 'browse' : 'quit';
+      },
+      findPreviousEpisode: () => null,
+      findNextEpisode: () => null,
+      browseEpisodes: async (browseEntry) => {
+        assert.equal(browseEntry, entry);
+        return '/shows/test-show/episode-04.mkv';
+      },
+    },
+  );
+
+  assert.deepEqual(played, ['/shows/test-show/episode-02.mkv', '/shows/test-show/episode-04.mkv']);
+  assert.deepEqual(menuEntries, [entry, entry]);
+});
+
+test('history replay uses the actual just-played path instead of the database row', async () => {
+  assert.equal(
+    typeof runHistoryPlaybackLoop,
+    'function',
+    'history playback loop is not implemented',
+  );
+  const entry = makeEntry('/shows/test-show/stale-episode-01.mkv');
+  const played: string[] = [];
+  const menuPaths: string[] = [];
+  let menuCount = 0;
+
+  await typedRunHistoryPlaybackLoop(
+    { entry, videoPath: '/shows/test-show/episode-07.mkv' },
+    {
+      play: async (videoPath) => {
+        played.push(videoPath);
+      },
+      pickPostPlaybackAction: async ({ justPlayedPath }) => {
+        menuPaths.push(justPlayedPath);
+        return menuCount++ === 0 ? 'replay' : 'quit';
+      },
+      findPreviousEpisode: () => null,
+      findNextEpisode: () => '/shows/test-show/episode-08.mkv',
+      browseEpisodes: async () => null,
+    },
+  );
+
+  assert.deepEqual(played, ['/shows/test-show/episode-07.mkv', '/shows/test-show/episode-07.mkv']);
+  assert.deepEqual(menuPaths, [
+    '/shows/test-show/episode-07.mkv',
+    '/shows/test-show/episode-07.mkv',
+  ]);
+});
+
+test('history next is computed from the actual just-played path', async () => {
+  assert.equal(
+    typeof runHistoryPlaybackLoop,
+    'function',
+    'history playback loop is not implemented',
+  );
+  const entry = makeEntry('/shows/test-show/stale-episode-01.mkv');
+  const played: string[] = [];
+  const nextInputs: string[] = [];
+  let menuCount = 0;
+
+  await typedRunHistoryPlaybackLoop(
+    { entry, videoPath: '/shows/test-show/episode-07.mkv' },
+    {
+      play: async (videoPath) => {
+        played.push(videoPath);
+      },
+      pickPostPlaybackAction: async ({ nextEpisodePath }) => {
+        if (menuCount++ === 0) {
+          assert.equal(nextEpisodePath, '/shows/test-show/episode-08.mkv');
+          return 'next';
+        }
+        assert.equal(nextEpisodePath, null);
+        return 'quit';
+      },
+      findPreviousEpisode: () => null,
+      findNextEpisode: (videoPath) => {
+        nextInputs.push(videoPath);
+        return videoPath.endsWith('episode-07.mkv') ? '/shows/test-show/episode-08.mkv' : null;
+      },
+      browseEpisodes: async () => null,
+    },
+  );
+
+  assert.deepEqual(played, ['/shows/test-show/episode-07.mkv', '/shows/test-show/episode-08.mkv']);
+  assert.deepEqual(nextInputs, [
+    '/shows/test-show/episode-07.mkv',
+    '/shows/test-show/episode-08.mkv',
+  ]);
+});
+
+test('history show menu offers previous, rewatch, next, browse, and quit in order', () => {
+  assert.equal(
+    typeof buildHistorySessionActions,
+    'function',
+    'history session actions are not implemented',
+  );
+
+  assert.deepEqual(
+    buildHistorySessionActions(
+      '/shows/test-show/episode-07.mkv',
+      '/shows/test-show/episode-06.mkv',
+      '/shows/test-show/episode-08.mkv',
+    ),
+    [
+      { kind: 'previous', label: 'Previous episode: episode-06.mkv' },
+      { kind: 'replay', label: 'Rewatch episode: episode-07.mkv' },
+      { kind: 'next', label: 'Play next episode: episode-08.mkv' },
+      { kind: 'browse', label: 'Select / browse episode' },
+      { kind: 'quit', label: 'Quit SubMiner' },
+    ],
+  );
+});
+
+test('history show menu omits previous and next when the just-played episode has neither', () => {
+  assert.equal(
+    typeof buildHistorySessionActions,
+    'function',
+    'history session actions are not implemented',
+  );
+
+  assert.deepEqual(buildHistorySessionActions('/shows/test-show/finale.mkv', null, null), [
+    { kind: 'replay', label: 'Rewatch episode: finale.mkv' },
+    { kind: 'browse', label: 'Select / browse episode' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  ]);
+});
+
+test('history entry menu offers previous, replay, and next before playback starts', () => {
+  assert.equal(
+    typeof buildHistoryEntryActions,
+    'function',
+    'history entry actions not implemented',
+  );
+
+  assert.deepEqual(
+    buildHistoryEntryActions(
+      '/shows/test-show/episode-03.mkv',
+      '/shows/test-show/episode-02.mkv',
+      '/shows/test-show/episode-04.mkv',
+    ),
+    [
+      { kind: 'previous', label: 'Previous episode: episode-02.mkv' },
+      { kind: 'replay', label: 'Replay last watched: episode-03.mkv' },
+      { kind: 'next', label: 'Next episode: episode-04.mkv' },
+      { kind: 'browse', label: 'Browse episodes' },
+      { kind: 'quit', label: 'Quit SubMiner' },
+    ],
+  );
+});
+
+test('history entry menu omits replay when the last watched file is gone', () => {
+  assert.deepEqual(buildHistoryEntryActions(null, null, '/shows/test-show/episode-04.mkv'), [
+    { kind: 'next', label: 'Next episode: episode-04.mkv' },
+    { kind: 'browse', label: 'Browse episodes' },
+    { kind: 'quit', label: 'Quit SubMiner' },
+  ]);
+});
+
+test('history playback loop selects previous based on the just-played path, then re-derives previous from the new current episode', async () => {
+  assert.equal(
+    typeof runHistoryPlaybackLoop,
+    'function',
+    'history playback loop is not implemented',
+  );
+  const entry = makeEntry('/shows/test-show/stale-episode-09.mkv');
+  const played: string[] = [];
+  const previousInputs: string[] = [];
+  const previousSeenByMenu: Array<string | null> = [];
+  let menuCount = 0;
+
+  await typedRunHistoryPlaybackLoop(
+    { entry, videoPath: '/shows/test-show/episode-07.mkv' },
+    {
+      play: async (videoPath) => {
+        played.push(videoPath);
+      },
+      pickPostPlaybackAction: async ({ previousEpisodePath }) => {
+        previousSeenByMenu.push(previousEpisodePath);
+        return menuCount++ === 0 ? 'previous' : 'quit';
+      },
+      findPreviousEpisode: (videoPath) => {
+        previousInputs.push(videoPath);
+        if (videoPath.endsWith('episode-07.mkv')) return '/shows/test-show/episode-06.mkv';
+        if (videoPath.endsWith('episode-06.mkv')) return '/shows/test-show/episode-05.mkv';
+        return null;
+      },
+      findNextEpisode: () => null,
+      browseEpisodes: async () => null,
+    },
+  );
+
+  assert.deepEqual(played, ['/shows/test-show/episode-07.mkv', '/shows/test-show/episode-06.mkv']);
+  assert.deepEqual(previousInputs, [
+    '/shows/test-show/episode-07.mkv',
+    '/shows/test-show/episode-06.mkv',
+  ]);
+  assert.deepEqual(previousSeenByMenu, [
+    '/shows/test-show/episode-06.mkv',
+    '/shows/test-show/episode-05.mkv',
+  ]);
+});
+
+test('history playback loop stops advancing when previous is chosen with no prior episode', async () => {
+  assert.equal(
+    typeof runHistoryPlaybackLoop,
+    'function',
+    'history playback loop is not implemented',
+  );
+  const entry = makeEntry('/shows/test-show/episode-01.mkv');
+  const played: string[] = [];
+
+  await typedRunHistoryPlaybackLoop(
+    { entry, videoPath: '/shows/test-show/episode-01.mkv' },
+    {
+      play: async (videoPath) => {
+        played.push(videoPath);
+      },
+      pickPostPlaybackAction: async ({ previousEpisodePath }) => {
+        assert.equal(previousEpisodePath, null);
+        return 'previous';
+      },
+      findPreviousEpisode: () => null,
+      findNextEpisode: () => null,
+      browseEpisodes: async () => null,
+    },
+  );
+
+  assert.deepEqual(played, ['/shows/test-show/episode-01.mkv']);
+});
@@ -5,7 +5,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import type { LauncherCommandContext } from './context.js';
-import { runPlaybackCommandWithDeps } from './playback-command.js';
+import { registerCleanup, runPlaybackCommandWithDeps } from './playback-command.js';
 import { state } from '../mpv.js';

 function createContext(): LauncherCommandContext {
@@ -36,6 +36,9 @@ function createContext(): LauncherCommandContext {
      texthookerOpenBrowser: false,
      useRofi: false,
      history: false,
+      sync: false,
+      syncCliTokens: [],
+      syncUi: false,
      logLevel: 'info',
      logRotation: 7,
      passwordStore: '',
@@ -100,6 +103,20 @@ function createContext(): LauncherCommandContext {
  };
 }

+test('playback cleanup signal handlers are registered once across repeated sessions', () => {
+  assert.equal(typeof registerCleanup, 'function', 'cleanup registration is not exported');
+  const context = createContext();
+  const registeredSignals: NodeJS.Signals[] = [];
+  context.processAdapter.onSignal = (signal) => {
+    registeredSignals.push(signal);
+  };
+
+  registerCleanup(context);
+  registerCleanup(context);
+
+  assert.deepEqual(registeredSignals, ['SIGINT', 'SIGTERM']);
+});
+
 test('youtube playback launches overlay with app-owned youtube flow args', async () => {
  const calls: string[] = [];
  const context = createContext();
@@ -30,6 +30,7 @@ import { hasLauncherExternalYomitanProfileConfig } from '../config.js';

 const SETUP_WAIT_TIMEOUT_MS = 10 * 60 * 1000;
 const SETUP_POLL_INTERVAL_MS = 500;
+const cleanupRegisteredProcessAdapters = new WeakSet<LauncherCommandContext['processAdapter']>();

 function getLauncherConfigDir(): string {
  return getDefaultConfigDir({
@@ -92,8 +93,10 @@ async function chooseTarget(
  return { target: selected, kind: 'file' };
 }

-function registerCleanup(context: LauncherCommandContext): void {
+export function registerCleanup(context: LauncherCommandContext): void {
  const { args, processAdapter } = context;
+  if (cleanupRegisteredProcessAdapters.has(processAdapter)) return;
+
  processAdapter.onSignal('SIGINT', () => {
    stopOverlay(args);
    processAdapter.exit(130);
@@ -102,6 +105,7 @@ function registerCleanup(context: LauncherCommandContext): void {
    stopOverlay(args);
    processAdapter.exit(143);
  });
+  cleanupRegisteredProcessAdapters.add(processAdapter);
 }

 async function ensurePlaybackSetupReady(context: LauncherCommandContext): Promise<void> {
@@ -0,0 +1,108 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import type { Args } from '../types.js';
+import type { LauncherCommandContext } from './context.js';
+import { runSyncCommand, type SyncCommandDeps } from './sync-command.js';
+
+function makeContext(
+  overrides: Partial<Args>,
+  appPath: string | null = '/opt/SubMiner/subminer-app',
+): LauncherCommandContext {
+  return {
+    args: {
+      sync: true,
+      syncCliTokens: [],
+      logLevel: 'warn',
+      ...overrides,
+    } as Args,
+    scriptPath: '/tmp/subminer',
+    scriptName: 'subminer',
+    mpvSocketPath: '',
+    pluginRuntimeConfig: {},
+    appPath,
+    launcherJellyfinConfig: {},
+    processAdapter: { platform: () => 'linux' },
+  } as unknown as LauncherCommandContext;
+}
+
+test('runSyncCommand proxies sync argv to the app in --sync-cli mode', async () => {
+  const spawned: Array<{ appPath: string; appArgs: string[] }> = [];
+  const deps: Partial<SyncCommandDeps> = {
+    runAppCommand: (appPath, appArgs) => {
+      spawned.push({ appPath, appArgs });
+    },
+  };
+
+  assert.equal(
+    await runSyncCommand(makeContext({ syncCliTokens: ['media-box', '--json'] }), deps),
+    true,
+  );
+  assert.deepEqual(spawned, [
+    {
+      appPath: '/opt/SubMiner/subminer-app',
+      appArgs: ['--sync-cli', 'sync', 'media-box', '--json', '--log-level', 'warn'],
+    },
+  ]);
+
+  assert.equal(await runSyncCommand(makeContext({ sync: false }), deps), false);
+  assert.equal(spawned.length, 1);
+});
+
+test('runSyncCommand forwards tokens verbatim and appends the effective log level', async () => {
+  const spawned: string[][] = [];
+  const deps: Partial<SyncCommandDeps> = {
+    runAppCommand: (_appPath, appArgs) => {
+      spawned.push(appArgs);
+    },
+  };
+
+  await runSyncCommand(
+    makeContext({
+      syncCliTokens: [
+        'media-box',
+        '--pull',
+        '--remote-cmd',
+        '/opt/SubMiner.AppImage',
+        '--db',
+        '/tmp/db.sqlite',
+        '--force',
+        '--json',
+      ],
+      logLevel: 'debug',
+    }),
+    deps,
+  );
+
+  assert.deepEqual(spawned, [
+    [
+      '--sync-cli',
+      'sync',
+      'media-box',
+      '--pull',
+      '--remote-cmd',
+      '/opt/SubMiner.AppImage',
+      '--db',
+      '/tmp/db.sqlite',
+      '--force',
+      '--json',
+      '--log-level',
+      'debug',
+    ],
+  ]);
+});
+
+test('runSyncCommand fails with a clear message when the app binary is missing', async () => {
+  const deps: Partial<SyncCommandDeps> = {
+    runAppCommand: () => {
+      throw new Error('should not spawn');
+    },
+    fail: (message: string): never => {
+      throw new Error(message);
+    },
+  };
+
+  await assert.rejects(
+    () => runSyncCommand(makeContext({ syncCliTokens: ['media-box'] }, null), deps),
+    /SubMiner app binary not found \(sync runs inside the app\)/,
+  );
+});
@@ -0,0 +1,45 @@
+import { SYNC_CLI_FLAG } from '../../src/core/services/stats-sync/cli-args.js';
+import { fail } from '../log.js';
+import { runAppCommandInteractive } from '../mpv.js';
+import type { LauncherCommandContext } from './context.js';
+
+export interface SyncCommandDeps {
+  runAppCommand: (appPath: string, appArgs: string[]) => void;
+  fail: (message: string) => never;
+}
+
+const defaultSyncCommandDeps: SyncCommandDeps = {
+  runAppCommand: runAppCommandInteractive,
+  fail,
+};
+
+/**
+ * `subminer sync` is a thin proxy: the sync engine only executes inside the
+ * SubMiner app (--sync-cli mode, libsql). The launcher contributes its
+ * parser/help and app discovery; the app's parseSyncCliTokens owns validation,
+ * so its errors reach the terminal through the child's inherited stdio. The
+ * child owns the terminal and its exit code becomes the launcher's.
+ */
+export async function runSyncCommand(
+  context: LauncherCommandContext,
+  inputDeps: Partial<SyncCommandDeps> = {},
+): Promise<boolean> {
+  const deps = { ...defaultSyncCommandDeps, ...inputDeps };
+  if (!context.args.sync) return false;
+  if (!context.appPath) {
+    deps.fail(
+      context.processAdapter.platform() === 'darwin'
+        ? 'SubMiner app binary not found (sync runs inside the app). Install SubMiner.app to /Applications or ~/Applications, or set SUBMINER_APPIMAGE_PATH.'
+        : 'SubMiner app binary not found (sync runs inside the app). Install the SubMiner app, or set SUBMINER_APPIMAGE_PATH.',
+    );
+    return true; // fail() never returns; this only satisfies control-flow analysis
+  }
+  deps.runAppCommand(context.appPath, [
+    SYNC_CLI_FLAG,
+    'sync',
+    ...context.args.syncCliTokens,
+    '--log-level',
+    context.args.logLevel,
+  ]);
+  return true;
+}
@@ -135,6 +135,11 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncCliTokens: [],
+    syncLogLevel: null,
+    syncUiTriggered: false,
+    syncUiLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -181,6 +186,11 @@ test('applyInvocationsToArgs maps settings invocation to settings window', () =>
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncCliTokens: [],
+    syncLogLevel: null,
+    syncUiTriggered: false,
+    syncUiLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -220,6 +230,11 @@ test('applyInvocationsToArgs fails when config invocation has no action', () =>
      statsCleanupVocab: false,
      statsCleanupLifetime: false,
      statsLogLevel: null,
+      syncTriggered: false,
+      syncCliTokens: [],
+      syncLogLevel: null,
+      syncUiTriggered: false,
+      syncUiLogLevel: null,
      doctorTriggered: false,
      doctorLogLevel: null,
      doctorRefreshKnownWords: false,
@@ -257,6 +272,11 @@ test('applyInvocationsToArgs maps texthooker browser-open request', () => {
    statsCleanupVocab: false,
    statsCleanupLifetime: false,
    statsLogLevel: null,
+    syncTriggered: false,
+    syncCliTokens: [],
+    syncLogLevel: null,
+    syncUiTriggered: false,
+    syncUiLogLevel: null,
    doctorTriggered: false,
    doctorLogLevel: null,
    doctorRefreshKnownWords: false,
@@ -199,6 +199,9 @@ export function createDefaultArgs(
    texthookerOpenBrowser: false,
    useRofi: false,
    history: false,
+    sync: false,
+    syncCliTokens: [],
+    syncUi: false,
    logLevel: loggingConfig.level ?? 'warn',
    logRotation: loggingConfig.rotation ?? 7,
    passwordStore: '',
@@ -264,6 +267,15 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
  ) {
    fail('Dictionary target path is required.');
  }
+  if (invocations.syncTriggered) {
+    parsed.sync = true;
+    parsed.syncCliTokens = invocations.syncCliTokens;
+    if (invocations.syncLogLevel) parsed.logLevel = parseLogLevel(invocations.syncLogLevel);
+  }
+  if (invocations.syncUiTriggered) {
+    parsed.syncUi = true;
+    if (invocations.syncUiLogLevel) parsed.logLevel = parseLogLevel(invocations.syncUiLogLevel);
+  }
  if (invocations.doctorTriggered) parsed.doctor = true;
  if (invocations.doctorRefreshKnownWords) parsed.doctorRefreshKnownWords = true;
  if (invocations.logsTriggered && !invocations.logsExport) {
@@ -42,3 +42,89 @@ test('parseCliPrograms captures texthooker browser-open flag', () => {
  assert.equal(result.invocations.texthookerTriggered, true);
  assert.equal(result.invocations.texthookerOpenBrowser, true);
 });
+
+test('parseCliPrograms lowers sync options into app-owned CLI tokens', () => {
+  const push = parseCliPrograms(['sync', 'media-box', '--push'], 'subminer');
+  assert.equal(push.invocations.syncTriggered, true);
+  assert.deepEqual(push.invocations.syncCliTokens, ['media-box', '--push']);
+
+  const pull = parseCliPrograms(['sync', 'media-box', '--pull'], 'subminer');
+  assert.deepEqual(pull.invocations.syncCliTokens, ['media-box', '--pull']);
+
+  const check = parseCliPrograms(['sync', 'media-box', '--check', '--json'], 'subminer');
+  assert.deepEqual(check.invocations.syncCliTokens, ['media-box', '--check', '--json']);
+
+  const full = parseCliPrograms(
+    [
+      'sync',
+      'media-box',
+      '--remote-cmd',
+      '/opt/SubMiner.AppImage',
+      '--db',
+      '/tmp/db.sqlite',
+      '--force',
+      '--log-level',
+      'debug',
+    ],
+    'subminer',
+  );
+  assert.deepEqual(full.invocations.syncCliTokens, [
+    'media-box',
+    '--remote-cmd',
+    '/opt/SubMiner.AppImage',
+    '--db',
+    '/tmp/db.sqlite',
+    '--force',
+  ]);
+  assert.equal(full.invocations.syncLogLevel, 'debug');
+
+  const snapshot = parseCliPrograms(['sync', '--snapshot', '/tmp/out.sqlite'], 'subminer');
+  assert.deepEqual(snapshot.invocations.syncCliTokens, ['--snapshot', '/tmp/out.sqlite']);
+
+  const merge = parseCliPrograms(['sync', '--merge', '/tmp/in.sqlite'], 'subminer');
+  assert.deepEqual(merge.invocations.syncCliTokens, ['--merge', '/tmp/in.sqlite']);
+
+  const makeTemp = parseCliPrograms(['sync', '--make-temp'], 'subminer');
+  assert.deepEqual(makeTemp.invocations.syncCliTokens, ['--make-temp']);
+
+  const removeTemp = parseCliPrograms(
+    ['sync', '--remove-temp', '/tmp/subminer-sync-x'],
+    'subminer',
+  );
+  assert.deepEqual(removeTemp.invocations.syncCliTokens, ['--remove-temp', '/tmp/subminer-sync-x']);
+});
+
+test('parseCliPrograms leaves sync validation to the app parser', () => {
+  // Invalid combinations are forwarded; the app's parseSyncCliTokens rejects them.
+  const invalid = parseCliPrograms(['sync', 'media-box', '--push', '--pull'], 'subminer');
+  assert.equal(invalid.invocations.syncTriggered, true);
+  assert.deepEqual(invalid.invocations.syncCliTokens, ['media-box', '--push', '--pull']);
+
+  const empty = parseCliPrograms(['sync'], 'subminer');
+  assert.equal(empty.invocations.syncTriggered, true);
+  assert.deepEqual(empty.invocations.syncCliTokens, []);
+});
+
+test('parseCliPrograms captures sync --ui', () => {
+  const result = parseCliPrograms(['sync', '--ui'], 'subminer');
+  assert.equal(result.invocations.syncUiTriggered, true);
+  assert.equal(result.invocations.syncTriggered, false);
+
+  assert.throws(
+    () => parseCliPrograms(['sync', 'media-box', '--ui'], 'subminer'),
+    /--ui cannot be combined/,
+  );
+});
+
+test('parseCliPrograms rejects sync --ui with --remote-cmd', () => {
+  assert.throws(
+    () => parseCliPrograms(['sync', '--ui', '--remote-cmd', '/opt/SubMiner.AppImage'], 'subminer'),
+    { message: 'Sync --ui cannot be combined with other sync options.' },
+  );
+});
+
+test('parseCliPrograms rejects sync --ui with --db', () => {
+  assert.throws(() => parseCliPrograms(['sync', '--ui', '--db', '/tmp/db.sqlite'], 'subminer'), {
+    message: 'Sync --ui cannot be combined with other sync options.',
+  });
+});
@@ -38,6 +38,11 @@ export interface CliInvocations {
  statsCleanupVocab: boolean;
  statsCleanupLifetime: boolean;
  statsLogLevel: string | null;
+  syncTriggered: boolean;
+  syncCliTokens: string[];
+  syncLogLevel: string | null;
+  syncUiTriggered: boolean;
+  syncUiLogLevel: string | null;
  doctorTriggered: boolean;
  doctorLogLevel: string | null;
  doctorRefreshKnownWords: boolean;
@@ -66,7 +71,11 @@ function applyRootOptions(program: Command): void {
    .option('-R, --rofi', 'Use rofi picker')
    .option('-H, --history', 'Browse local watch history')
    .option('-S, --start-overlay', 'Auto-start overlay')
-    .option('-T, --no-texthooker', 'Disable texthooker-ui server');
+    .option('-T, --no-texthooker', 'Disable texthooker-ui server')
+    // The SubMiner app answers sync commands when invoked with --sync-cli.
+    // Remote-command resolution may address the launcher the same way, so
+    // accept the flag as a no-op to keep both invocation shapes equivalent.
+    .option('--sync-cli', 'Compatibility no-op (sync commands work with or without it)');
 }

 function buildSubcommandHelpText(program: Command): string {
@@ -98,6 +107,7 @@ function getTopLevelCommand(argv: string[]): { name: string; index: number } | n
    'dictionary',
    'dict',
    'stats',
+    'sync',
    'texthooker',
    'app',
    'bin',
@@ -160,6 +170,11 @@ export function parseCliPrograms(
  let statsCleanupVocab = false;
  let statsCleanupLifetime = false;
  let statsLogLevel: string | null = null;
+  let syncTriggered = false;
+  let syncCliTokens: string[] = [];
+  let syncLogLevel: string | null = null;
+  let syncUiTriggered = false;
+  let syncUiLogLevel: string | null = null;
  let doctorLogLevel: string | null = null;
  let doctorRefreshKnownWords = false;
  let logsTriggered = false;
@@ -289,6 +304,75 @@ export function parseCliPrograms(
      statsLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
    });

+  commandProgram
+    .command('sync')
+    .description('Sync stats and watch history with another machine over SSH')
+    .argument('[host]', 'SSH destination (user@host or an ssh config alias)')
+    .option('--snapshot <file>', 'Write a consistent snapshot of the local stats database')
+    .option('--merge <file>', 'Merge a snapshot database file into the local stats database')
+    .option('--push', 'Only merge local stats into the SSH host')
+    .option('--pull', 'Only merge stats from the SSH host into the local database')
+    .option('--db <file>', 'Override the local stats database path')
+    .option('--remote-cmd <cmd>', 'subminer command to run on the remote host')
+    .option('-f, --force', 'Skip the running-app safety check')
+    .option('--check', 'Test the SSH connection and remote subminer availability')
+    .option('--json', 'Emit machine-readable NDJSON progress output')
+    .option('--make-temp', 'Create a sync temp directory and print its path (used over SSH)')
+    .option('--remove-temp <dir>', 'Remove a sync temp directory created by --make-temp')
+    .option('--ui', 'Open the SubMiner sync window')
+    .option('--log-level <level>', 'Log level')
+    .action((rawHost: string | undefined, options: Record<string, unknown>) => {
+      const host = typeof rawHost === 'string' ? rawHost.trim() : '';
+      const snapshot = typeof options.snapshot === 'string' ? options.snapshot.trim() : '';
+      const merge = typeof options.merge === 'string' ? options.merge.trim() : '';
+      const push = options.push === true;
+      const pull = options.pull === true;
+      const check = options.check === true;
+      const makeTemp = options.makeTemp === true;
+      const removeTemp = typeof options.removeTemp === 'string' ? options.removeTemp.trim() : '';
+      if (options.ui === true) {
+        if (
+          host ||
+          snapshot ||
+          merge ||
+          push ||
+          pull ||
+          check ||
+          makeTemp ||
+          removeTemp ||
+          options.remoteCmd !== undefined ||
+          options.db !== undefined ||
+          options.json === true ||
+          options.force === true
+        ) {
+          throw new Error('Sync --ui cannot be combined with other sync options.');
+        }
+        syncUiTriggered = true;
+        syncUiLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
+        return;
+      }
+      // No validation here: the app's parseSyncCliTokens owns the sync rules
+      // and its error text reaches the terminal through the child's stdio.
+      const remoteCmd = typeof options.remoteCmd === 'string' ? options.remoteCmd.trim() : '';
+      const dbPath = typeof options.db === 'string' ? options.db.trim() : '';
+      const tokens: string[] = [];
+      if (host) tokens.push(host);
+      if (snapshot) tokens.push('--snapshot', snapshot);
+      if (merge) tokens.push('--merge', merge);
+      if (makeTemp) tokens.push('--make-temp');
+      if (removeTemp) tokens.push('--remove-temp', removeTemp);
+      if (push) tokens.push('--push');
+      if (pull) tokens.push('--pull');
+      if (check) tokens.push('--check');
+      if (remoteCmd) tokens.push('--remote-cmd', remoteCmd);
+      if (dbPath) tokens.push('--db', dbPath);
+      if (options.force === true) tokens.push('--force');
+      if (options.json === true) tokens.push('--json');
+      syncTriggered = true;
+      syncCliTokens = tokens;
+      syncLogLevel = typeof options.logLevel === 'string' ? options.logLevel : null;
+    });
+
  commandProgram
    .command('doctor')
    .description('Run dependency and environment checks')
@@ -400,6 +484,11 @@ export function parseCliPrograms(
      statsCleanupVocab,
      statsCleanupLifetime,
      statsLogLevel,
+      syncTriggered,
+      syncCliTokens,
+      syncLogLevel,
+      syncUiTriggered,
+      syncUiLogLevel,
      doctorTriggered,
      doctorLogLevel,
      doctorRefreshKnownWords,
@@ -1,32 +1,12 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 import { Database } from 'bun:sqlite';
-import { resolveConfigDir } from '../src/config/path-resolution.js';
-import { readLauncherMainConfigObject } from './config/shared-config-reader.js';
 import type { HistoryVideoRow } from './history-types.js';
-import { resolvePathMaybe } from './util.js';
+import { resolveImmersionDbPath } from '../src/core/services/stats-sync/db-path.js';
+import {
+  isReadonlyWalRetryError,
+  withReadonlyWalRetry,
+} from '../src/core/services/stats-sync/wal-retry.js';

-export function resolveImmersionDbPath(): string {
-  const root = readLauncherMainConfigObject();
-  const tracking =
-    root?.immersionTracking &&
-    typeof root.immersionTracking === 'object' &&
-    !Array.isArray(root.immersionTracking)
-      ? (root.immersionTracking as Record<string, unknown>)
-      : null;
-  const configured = typeof tracking?.dbPath === 'string' ? tracking.dbPath.trim() : '';
-  if (configured) return resolvePathMaybe(configured);
-
-  const configDir = resolveConfigDir({
-    platform: process.platform,
-    appDataDir: process.env.APPDATA,
-    xdgConfigHome: process.env.XDG_CONFIG_HOME,
-    homeDir: os.homedir(),
-    existsSync: fs.existsSync,
-  });
-  return path.join(configDir, 'immersion.sqlite');
-}
+export { isReadonlyWalRetryError, resolveImmersionDbPath, withReadonlyWalRetry };

 interface RawHistoryRow {
  video_id: number;
@@ -43,49 +23,6 @@ export function queryLocalWatchHistory(dbPath: string): HistoryVideoRow[] {
  return withReadonlyWalRetry(dbPath, (options) => readHistoryRows(dbPath, options));
 }

-export function withReadonlyWalRetry<T>(
-  dbPath: string,
-  query: (options: { readonly?: boolean; readwrite?: boolean; create?: boolean }) => T,
-): T {
-  try {
-    return query({ readonly: true });
-  } catch (error) {
-    if (!isReadonlyWalRetryError(error, dbPath)) throw error;
-    return query({ readwrite: true, create: false });
-  }
-}
-
-export function isReadonlyWalRetryError(error: unknown, dbPath: string): boolean {
-  if (!isWalModeSqliteDatabase(dbPath)) return false;
-  const code =
-    typeof error === 'object' && error !== null && 'code' in error
-      ? String((error as { code?: unknown }).code ?? '')
-      : '';
-  const message = error instanceof Error ? error.message : String(error);
-  const text = `${code} ${message}`.toLowerCase();
-  return (
-    text.includes('readonly') ||
-    text.includes('read-only') ||
-    text.includes('attempt to write a readonly database') ||
-    text.includes('sqlite_cantopen') ||
-    text.includes('unable to open database file')
-  );
-}
-
-function isWalModeSqliteDatabase(dbPath: string): boolean {
-  const header = Buffer.alloc(20);
-  let fd: number | null = null;
-  try {
-    fd = fs.openSync(dbPath, 'r');
-    if (fs.readSync(fd, header, 0, header.length, 0) < header.length) return false;
-  } catch {
-    return false;
-  } finally {
-    if (fd !== null) fs.closeSync(fd);
-  }
-  return header.subarray(0, 16).toString('ascii') === 'SQLite format 3\0' && header[18] === 2;
-}
-
 function tableExists(db: Database, tableName: string): boolean {
  return Boolean(
    db.query(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`).get(tableName),
@@ -130,3 +130,46 @@ export function findNextEpisode(lastPath: string): string | null {

  return findFirstEpisodeInNextSeason(resolvedLast, dir);
 }
+
+function findLastEpisodeInPreviousSeason(resolvedCurrent: string, dir: string): string | null {
+  const seriesRoot = resolveSeriesRoot(resolvedCurrent);
+  if (seriesRoot === dir) return null;
+  const seasons = listSeasonDirs(seriesRoot);
+  const currentIdx = seasons.findIndex((season) => path.resolve(season.path) === dir);
+  const currentSeason = seasonNumberFromDirName(path.basename(dir));
+  const previousSeasonEntry =
+    currentIdx >= 0
+      ? seasons[currentIdx - 1]
+      : seasons
+          .filter(
+            (season) =>
+              currentSeason !== null && season.season !== null && season.season < currentSeason,
+          )
+          .at(-1);
+  if (!previousSeasonEntry) return null;
+  const previousSeason = sortVideosByEpisode(collectVideos(previousSeasonEntry.path, false));
+  return previousSeason.at(-1) ?? null;
+}
+
+export function findPreviousEpisode(currentPath: string): string | null {
+  const resolvedCurrent = path.resolve(currentPath);
+  const dir = path.dirname(resolvedCurrent);
+  const episodes = sortVideosByEpisode(collectVideos(dir, false));
+  const idx = episodes.indexOf(resolvedCurrent);
+
+  if (idx >= 0) {
+    if (idx - 1 >= 0) return episodes[idx - 1]!;
+  } else {
+    const currentInfo = parseMediaInfo(resolvedCurrent);
+    if (currentInfo.episode !== null) {
+      const candidates = episodes.filter((episode) => {
+        const info = parseMediaInfo(episode);
+        return info.episode !== null && info.episode < currentInfo.episode!;
+      });
+      const candidate = candidates[candidates.length - 1];
+      if (candidate) return candidate;
+    }
+  }
+
+  return findLastEpisodeInPreviousSeason(resolvedCurrent, dir);
+}
@@ -7,6 +7,7 @@ import { Database } from 'bun:sqlite';
 import {
  detectImageExtension,
  findNextEpisode,
+  findPreviousEpisode,
  groupHistoryBySeries,
  isReadonlyWalRetryError,
  listSeasonDirs,
@@ -198,6 +199,55 @@ test('findNextEpisode advances seasons when a deleted file was the last episode'
  }
 });

+test('findPreviousEpisode steps back within a season and across seasons', () => {
+  assert.equal(typeof findPreviousEpisode, 'function', 'findPreviousEpisode is not implemented');
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const season2 = path.join(seriesRoot, 'Season-2');
+
+    assert.equal(
+      findPreviousEpisode(path.join(season1, 'Show - S01E03.mkv')),
+      path.join(season1, 'Show - S01E02.mkv'),
+    );
+    assert.equal(
+      findPreviousEpisode(path.join(season1, 'Show - S01E02.mkv')),
+      path.join(season1, 'Show - S01E01.mkv'),
+    );
+    assert.equal(findPreviousEpisode(path.join(season1, 'Show - S01E01.mkv')), null);
+    assert.equal(
+      findPreviousEpisode(path.join(season2, 'Show - S02E01.mkv')),
+      path.join(season1, 'Show - S01E03.mkv'),
+    );
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+test('findPreviousEpisode falls back to episode numbers when file was removed', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const missing = path.join(season1, 'Show - S01E02 - Deleted Cut.mkv');
+    assert.equal(findPreviousEpisode(missing), path.join(season1, 'Show - S01E01.mkv'));
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
+test('findPreviousEpisode falls back to prior season when a deleted file was the first episode', () => {
+  const seriesRoot = createSeriesTree();
+  try {
+    const season1 = path.join(seriesRoot, 'Season-1');
+    const season2 = path.join(seriesRoot, 'Season-2');
+    fs.rmSync(path.join(season2, 'Show - S02E01.mkv'));
+    const missing = path.join(season2, 'Show - S02E01 - Deleted Cut.mkv');
+    assert.equal(findPreviousEpisode(missing), path.join(season1, 'Show - S01E03.mkv'));
+  } finally {
+    fs.rmSync(path.dirname(seriesRoot), { recursive: true, force: true });
+  }
+});
+
 const PNG_MAGIC = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');

 function createHistoryDb(
@@ -30,6 +30,9 @@ function createArgs(): Args {
    texthookerOpenBrowser: false,
    useRofi: false,
    history: false,
+    sync: false,
+    syncCliTokens: [],
+    syncUi: false,
    logLevel: 'info',
    logRotation: 7,
    passwordStore: '',
@@ -21,7 +21,8 @@ import { runDictionaryCommand } from './commands/dictionary-command.js';
 import { runLogsCommand } from './commands/logs-command.js';
 import { runStatsCommand } from './commands/stats-command.js';
 import { runJellyfinCommand } from './commands/jellyfin-command.js';
-import { runHistoryCommand } from './commands/history-command.js';
+import { runHistorySession } from './commands/history-command.js';
+import { runSyncCommand } from './commands/sync-command.js';
 import { runPlaybackCommand } from './commands/playback-command.js';
 import { runUpdateCommand } from './commands/update-command.js';

@@ -107,6 +108,10 @@ async function main(): Promise<void> {
    return;
  }

+  if (await runSyncCommand(context)) {
+    return;
+  }
+
  const resolvedAppPath = ensureAppPath(context);
  state.appPath = resolvedAppPath;
  log('debug', args.logLevel, `Using SubMiner app binary: ${resolvedAppPath}`);
@@ -144,13 +149,15 @@ async function main(): Promise<void> {
  }

  if (appContext.args.history) {
-    const selected = await runHistoryCommand(appContext);
-    if (!selected) {
+    const played = await runHistorySession(appContext, async (videoPath) => {
+      appContext.args.target = videoPath;
+      appContext.args.targetKind = 'file';
+      await runPlaybackCommand(appContext);
+    });
+    if (!played) {
      log('info', args.logLevel, 'No watch history selection made, exiting');
-      return;
    }
-    appContext.args.target = selected;
-    appContext.args.targetKind = 'file';
+    return;
  }

  await runPlaybackCommand(appContext);
@@ -119,6 +119,37 @@ test('runAppCommandCaptureOutput transports Linux AppImage args through environm
  }
 });

+test('runAppCommandCaptureOutput runs Linux AppImage sync in Node-only mode', () => {
+  const { dir } = createTempSocketPath();
+  const appPath = path.join(dir, 'SubMiner.AppImage');
+  fs.writeFileSync(
+    appPath,
+    [
+      '#!/bin/sh',
+      'printf "args:%s\\n" "$*"',
+      'printf "electron-node:%s\\n" "$ELECTRON_RUN_AS_NODE"',
+      'printf "argc:%s\\n" "$SUBMINER_APP_ARGC"',
+      'printf "arg0:%s\\n" "$SUBMINER_APP_ARG_0"',
+      '',
+    ].join('\n'),
+  );
+  fs.chmodSync(appPath, 0o755);
+
+  try {
+    const result = withPlatform('linux', () =>
+      runAppCommandCaptureOutput(appPath, ['--sync-cli', 'sync', '--snapshot', '/tmp/out']),
+    );
+
+    assert.equal(result.status, 0);
+    assert.match(result.stdout, /^args:-e /m);
+    assert.match(result.stdout, /^electron-node:1$/m);
+    assert.match(result.stdout, /^argc:4$/m);
+    assert.match(result.stdout, /^arg0:--sync-cli$/m);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('parseMpvArgString preserves empty quoted tokens', () => {
  assert.deepEqual(parseMpvArgString('--title "" --force-media-title \'\' --pause'), [
    '--title',
@@ -571,6 +602,9 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
    texthookerOpenBrowser: false,
    useRofi: false,
    history: false,
+    sync: false,
+    syncCliTokens: [],
+    syncUi: false,
    logLevel: 'error',
    logRotation: 7,
    passwordStore: '',
@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import net from 'node:net';
 import { spawn, spawnSync } from 'node:child_process';
+import type { StdioOptions } from 'node:child_process';
 import { buildMpvLaunchModeArgs } from '../src/shared/mpv-launch-mode.js';
 import { buildMpvLoggingArgs } from '../src/shared/mpv-logging-args.js';
 import {
@@ -1276,6 +1277,15 @@ function shouldTransportAppArgsForAppImage(appPath: string): boolean {
  return process.platform === 'linux' && /\.AppImage$/i.test(appPath);
 }

+const APPIMAGE_SYNC_NODE_RUNNER = [
+  'const root=process.env.APPDIR+"/resources/app.asar";',
+  'const {runSyncCliFromProcess}=require(root+"/dist/main/sync-cli.js");',
+  'const count=Number(process.env.SUBMINER_APP_ARGC);',
+  'const argv=[process.execPath,...Array.from({length:count},(_,i)=>process.env["SUBMINER_APP_ARG_"+i]??"")];',
+  'runSyncCliFromProcess(argv,require(root+"/package.json").version)',
+  '.then(code=>process.exit(code),error=>{console.error(error);process.exit(1)});',
+].join('');
+
 function buildAppEnv(
  baseEnv: NodeJS.ProcessEnv = process.env,
  extraEnv: NodeJS.ProcessEnv = {},
@@ -1431,6 +1441,16 @@ function maybeCaptureAppArgs(appArgs: string[]): boolean {

 function resolveAppSpawnTarget(appPath: string, appArgs: string[]): SpawnTarget {
  if (shouldTransportAppArgsForAppImage(appPath)) {
+    if (appArgs[0] === '--sync-cli') {
+      return {
+        command: appPath,
+        args: ['-e', APPIMAGE_SYNC_NODE_RUNNER],
+        env: {
+          ...buildTransportedAppArgsEnv(appArgs),
+          ELECTRON_RUN_AS_NODE: '1',
+        },
+      };
+    }
    return {
      command: appPath,
      args: [],
@@ -1444,16 +1464,37 @@ function resolveAppSpawnTarget(appPath: string, appArgs: string[]): SpawnTarget
 }

 export function runAppCommandWithInherit(appPath: string, appArgs: string[]): void {
+  runAppCommand(appPath, appArgs, ['ignore', 'pipe', 'pipe'], true);
+}
+
+/**
+ * Like runAppCommandWithInherit, but with the terminal fully attached: the
+ * child owns stdin (ssh password/host-key prompts must reach the user) and
+ * writes stdout/stderr directly (NDJSON --json output must stay unwrapped).
+ * Used for `subminer sync`, which proxies to the app's --sync-cli mode.
+ */
+export function runAppCommandInteractive(appPath: string, appArgs: string[]): void {
+  runAppCommand(appPath, appArgs, ['inherit', 'inherit', 'inherit'], false);
+}
+
+function runAppCommand(
+  appPath: string,
+  appArgs: string[],
+  stdio: StdioOptions,
+  attachLogging: boolean,
+): void {
  if (maybeCaptureAppArgs(appArgs)) {
    process.exit(0);
  }

  const target = resolveAppSpawnTarget(appPath, appArgs);
  const proc = spawn(target.command, target.args, {
-    stdio: ['ignore', 'pipe', 'pipe'],
+    stdio,
    env: buildAppEnv(process.env, target.env),
  });
-  attachAppProcessLogging(proc, { mirrorStdout: true, mirrorStderr: true });
+  if (attachLogging) {
+    attachAppProcessLogging(proc, { mirrorStdout: true, mirrorStderr: true });
+  }
  proc.once('error', (error) => {
    fail(`Failed to run app command: ${error.message}`);
  });
@@ -1683,7 +1724,7 @@ async function sleepMs(ms: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, ms));
 }

-async function canConnectUnixSocket(socketPath: string): Promise<boolean> {
+export async function canConnectUnixSocket(socketPath: string): Promise<boolean> {
  return await new Promise<boolean>((resolve) => {
    const socket = net.createConnection(socketPath);
    let settled = false;
@@ -3,7 +3,22 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { findRofiTheme } from './picker';
+import { findRofiTheme, formatRofiPrompt } from './picker';
+
+// ── formatRofiPrompt: spacing between prompt and input field ──────────────────
+
+test('formatRofiPrompt appends a single trailing space', () => {
+  assert.equal(formatRofiPrompt('Select Video'), 'Select Video ');
+});
+
+test('formatRofiPrompt collapses existing trailing whitespace to one space', () => {
+  assert.equal(formatRofiPrompt('Watch History   '), 'Watch History ');
+});
+
+test('formatRofiPrompt leaves an empty prompt empty', () => {
+  assert.equal(formatRofiPrompt(''), '');
+  assert.equal(formatRofiPrompt('   '), '');
+});

 // ── findRofiTheme: Linux packaged path discovery ──────────────────────────────

@@ -17,13 +17,22 @@ export function escapeShellSingle(value: string): string {
  return `'${value.replace(/'/g, `'\\''`)}'`;
 }

+/**
+ * Rofi renders the prompt flush against the input field, so keep exactly one
+ * trailing space to separate them.
+ */
+export function formatRofiPrompt(prompt: string): string {
+  const trimmed = prompt.trimEnd();
+  return trimmed ? `${trimmed} ` : '';
+}
+
 export function showRofiFlatMenu(
  items: string[],
  prompt: string,
  initialQuery = '',
  themePath: string | null = null,
 ): string {
-  const args = ['-dmenu', '-i', '-matching', 'fuzzy', '-p', prompt];
+  const args = ['-dmenu', '-i', '-matching', 'fuzzy', '-p', formatRofiPrompt(prompt)];
  if (themePath) {
    args.push('-theme', themePath);
  } else {
@@ -110,7 +119,7 @@ export async function promptOptionalJellyfinSearch(
  themePath: string | null = null,
 ): Promise<string> {
  if (useRofi && commandExists('rofi')) {
-    const rofiArgs = ['-dmenu', '-i', '-p', 'Jellyfin Search (optional)'];
+    const rofiArgs = ['-dmenu', '-i', '-p', formatRofiPrompt('Jellyfin Search (optional)')];
    if (themePath) {
      rofiArgs.push('-theme', themePath);
    } else {
@@ -157,7 +166,7 @@ function showRofiIconMenu(
  themePath: string | null = null,
 ): number {
  if (entries.length === 0) return -1;
-  const rofiArgs = ['-dmenu', '-i', '-show-icons', '-format', 'i', '-p', prompt];
+  const rofiArgs = ['-dmenu', '-i', '-show-icons', '-format', 'i', '-p', formatRofiPrompt(prompt)];
  if (initialQuery) rofiArgs.push('-filter', initialQuery);
  if (themePath) {
    rofiArgs.push('-theme', themePath);
@@ -391,7 +400,7 @@ export function showRofiMenu(
    '-dmenu',
    '-i',
    '-p',
-    'Select Video ',
+    formatRofiPrompt('Select Video'),
    '-show-icons',
    '-theme-str',
    'configuration { font: "Noto Sans CJK JP Regular 8";}',
@@ -0,0 +1,664 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database } from 'bun:sqlite';
+// The engine executes on libsql in production; these merge tests run through
+// that same driver. bun:sqlite is used only to build fixtures and inspect
+// results.
+import { createDbSnapshot } from '../../src/core/services/stats-sync/shared.js';
+import { mergeSnapshotIntoDb } from '../../src/core/services/stats-sync/merge.js';
+import {
+  createImmersionDbFixture,
+  insertFixtureSession,
+} from '../test-support/immersion-db-fixture.js';
+
+const DAY_MS = 86_400_000;
+const BASE_MS = Date.UTC(2026, 5, 1, 12, 0, 0);
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-sync-test-'));
+}
+
+function makeDbPair(): { dir: string; localPath: string; remotePath: string } {
+  const dir = makeTmpDir();
+  const localPath = path.join(dir, 'local.sqlite');
+  const remotePath = path.join(dir, 'remote.sqlite');
+  createImmersionDbFixture(localPath);
+  createImmersionDbFixture(remotePath);
+  return { dir, localPath, remotePath };
+}
+
+function queryOne<T extends Record<string, unknown>>(
+  dbPath: string,
+  sql: string,
+  params: unknown[] = [],
+): T | undefined {
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    return db.query<T>(sql).get(...params) as T | undefined;
+  } finally {
+    db.close();
+  }
+}
+
+function count(dbPath: string, sql: string, params: unknown[] = []): number {
+  return Number(queryOne<{ n: number }>(dbPath, sql, params)?.n ?? 0);
+}
+
+function withWritableDb<T>(dbPath: string, fn: (db: Database) => T): T {
+  const db = new Database(dbPath, { readwrite: true });
+  try {
+    return fn(db);
+  } finally {
+    db.close();
+  }
+}
+
+test('merges remote-only sessions with catalog, lifetime, and rollups', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+      words: [{ headword: '見る', word: '見た', reading: 'みた', count: 2 }],
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showb-e1',
+      animeTitleKey: 'showb',
+      startedAtMs: BASE_MS + DAY_MS,
+      activeWatchedMs: 900_000,
+      cardsMined: 3,
+      applyLifetime: true,
+      words: [
+        { headword: '見る', word: '見た', reading: 'みた', count: 5 },
+        { headword: '食べる', word: '食べた', reading: 'たべた', count: 1 },
+      ],
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.sessionsMerged, 1);
+    assert.equal(summary.animeAdded, 1);
+    assert.equal(summary.videosAdded, 1);
+    assert.equal(summary.wordsAdded, 1);
+    assert.equal(summary.subtitleLinesAdded, 2);
+    assert.equal(summary.telemetryRowsAdded, 1);
+
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_sessions'), 2);
+    const global = queryOne<{
+      total_sessions: number;
+      total_active_ms: number;
+      total_cards: number;
+      active_days: number;
+      episodes_started: number;
+    }>(
+      localPath,
+      'SELECT total_sessions, total_active_ms, total_cards, active_days, episodes_started FROM imm_lifetime_global WHERE global_id = 1',
+    );
+    assert.equal(global?.total_sessions, 2);
+    assert.equal(global?.total_active_ms, 1_200_000 + 900_000);
+    assert.equal(global?.total_cards, 2 + 3);
+    assert.equal(global?.active_days, 2);
+    assert.equal(global?.episodes_started, 2);
+
+    // Existing word: local 2 + merged 5; new word carries remote frequency.
+    const sharedWord = queryOne<{ frequency: number }>(
+      localPath,
+      `SELECT frequency FROM imm_words WHERE word = '見た'`,
+    );
+    assert.equal(sharedWord?.frequency, 7);
+    const newWord = queryOne<{ frequency: number }>(
+      localPath,
+      `SELECT frequency FROM imm_words WHERE word = '食べた'`,
+    );
+    assert.equal(newWord?.frequency, 1);
+
+    // The merged session's rollup group was recomputed.
+    assert.equal(summary.rollupGroupsRecomputed, 1);
+    const mergedVideoId = Number(
+      queryOne<{ video_id: number }>(
+        localPath,
+        `SELECT video_id FROM imm_videos WHERE video_key = 'showb-e1'`,
+      )?.video_id,
+    );
+    assert.equal(
+      count(localPath, 'SELECT COUNT(*) AS n FROM imm_daily_rollups WHERE video_id = ?', [
+        mergedVideoId,
+      ]),
+      1,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('is idempotent: re-merging the same snapshot changes nothing', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+      words: [{ headword: '見る', word: '見た', reading: 'みた', count: 4 }],
+    });
+
+    mergeSnapshotIntoDb(localPath, remotePath);
+    const globalAfterFirst = queryOne<Record<string, unknown>>(
+      localPath,
+      'SELECT * FROM imm_lifetime_global WHERE global_id = 1',
+    );
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+
+    assert.equal(summary.sessionsMerged, 0);
+    assert.equal(summary.sessionsAlreadyPresent, 1);
+    assert.equal(summary.wordsAdded, 0);
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_sessions'), 1);
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_subtitle_lines'), 1);
+    const globalAfterSecond = queryOne<Record<string, unknown>>(
+      localPath,
+      'SELECT * FROM imm_lifetime_global WHERE global_id = 1',
+    );
+    assert.deepEqual(
+      { ...globalAfterSecond, LAST_UPDATE_DATE: null },
+      { ...globalAfterFirst, LAST_UPDATE_DATE: null },
+    );
+    assert.equal(
+      Number(
+        queryOne<{ frequency: number }>(
+          localPath,
+          `SELECT frequency FROM imm_words WHERE word = '見た'`,
+        )?.frequency,
+      ),
+      4,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('preserves anilist_id when inserting a new anime from the snapshot', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showb-e1',
+      animeTitleKey: 'showb',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    withWritableDb(remotePath, (remoteDb) => {
+      remoteDb
+        .prepare(`UPDATE imm_anime SET anilist_id = 12345 WHERE normalized_title_key = 'showb'`)
+        .run();
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.animeAdded, 1);
+    const anime = queryOne<{ anilist_id: number }>(
+      localPath,
+      `SELECT anilist_id FROM imm_anime WHERE normalized_title_key = 'showb'`,
+    );
+    assert.equal(anime?.anilist_id, 12345);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('matches an existing local anime by anilist_id even when the title key differs', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'show-romaji',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showa-e2',
+      animeTitleKey: 'show-native',
+      startedAtMs: BASE_MS + DAY_MS,
+      applyLifetime: true,
+    });
+    withWritableDb(localPath, (localDb) => {
+      localDb
+        .prepare(`UPDATE imm_anime SET anilist_id = 999 WHERE normalized_title_key = 'show-romaji'`)
+        .run();
+    });
+    withWritableDb(remotePath, (remoteDb) => {
+      remoteDb
+        .prepare(`UPDATE imm_anime SET anilist_id = 999 WHERE normalized_title_key = 'show-native'`)
+        .run();
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    // Same anilist_id → one anime, not two.
+    assert.equal(summary.animeAdded, 0);
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_anime'), 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('matches shared videos by video_key and merges the watched flag', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS + DAY_MS,
+      watched: true,
+      applyLifetime: true,
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.videosAdded, 0);
+    assert.equal(summary.animeAdded, 0);
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_videos'), 1);
+    const video = queryOne<{ watched: number }>(
+      localPath,
+      `SELECT watched FROM imm_videos WHERE video_key = 'showa-e1'`,
+    );
+    assert.equal(video?.watched, 1);
+
+    // Both sessions now credit the same video; episode was started once and
+    // completed once (by the remote session that watched it to the end).
+    const global = queryOne<{
+      episodes_started: number;
+      episodes_completed: number;
+      total_sessions: number;
+    }>(
+      localPath,
+      'SELECT episodes_started, episodes_completed, total_sessions FROM imm_lifetime_global WHERE global_id = 1',
+    );
+    assert.equal(global?.total_sessions, 2);
+    assert.equal(global?.episodes_started, 1);
+    assert.equal(global?.episodes_completed, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('backfills media metadata for matched videos when local metadata is absent', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showa-e1',
+      animeTitleKey: 'showa',
+      startedAtMs: BASE_MS + DAY_MS,
+      applyLifetime: true,
+    });
+    const remoteDb = new Database(remotePath, { readwrite: true });
+    try {
+      const remoteVideoId = Number(
+        remoteDb
+          .query<{
+            video_id: number;
+          }>(`SELECT video_id FROM imm_videos WHERE video_key = 'showa-e1'`)
+          .get()?.video_id,
+      );
+      remoteDb
+        .prepare(
+          `INSERT INTO imm_media_art (video_id, anilist_id, cover_url, title_romaji, fetched_at_ms)
+           VALUES (?, 123, 'https://example.test/cover.jpg', 'Show A', ?)`,
+        )
+        .run(remoteVideoId, String(BASE_MS));
+      remoteDb
+        .prepare(
+          `INSERT INTO imm_youtube_videos (video_id, youtube_video_id, video_url, video_title, fetched_at_ms)
+           VALUES (?, 'yt-1', 'https://youtube.test/watch?v=yt-1', 'Remote Video', ?)`,
+        )
+        .run(remoteVideoId, String(BASE_MS));
+    } finally {
+      remoteDb.close();
+    }
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.videosAdded, 0);
+    const localVideoId = Number(
+      queryOne<{ video_id: number }>(
+        localPath,
+        `SELECT video_id FROM imm_videos WHERE video_key = 'showa-e1'`,
+      )?.video_id,
+    );
+    const art = queryOne<{ cover_url: string; title_romaji: string }>(
+      localPath,
+      'SELECT cover_url, title_romaji FROM imm_media_art WHERE video_id = ?',
+      [localVideoId],
+    );
+    assert.equal(art?.cover_url, 'https://example.test/cover.jpg');
+    assert.equal(art?.title_romaji, 'Show A');
+    const youtube = queryOne<{ youtube_video_id: string; video_title: string }>(
+      localPath,
+      'SELECT youtube_video_id, video_title FROM imm_youtube_videos WHERE video_id = ?',
+      [localVideoId],
+    );
+    assert.equal(youtube?.youtube_video_id, 'yt-1');
+    assert.equal(youtube?.video_title, 'Remote Video');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('does not double-count active_days when a merged session starts earlier on an already-credited day', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'showa-e1',
+      startedAtMs: BASE_MS + 3_600_000,
+      applyLifetime: true,
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showb-e1',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+
+    mergeSnapshotIntoDb(localPath, remotePath);
+    const global = queryOne<{ active_days: number; total_sessions: number }>(
+      localPath,
+      'SELECT active_days, total_sessions FROM imm_lifetime_global WHERE global_id = 1',
+    );
+    assert.equal(global?.total_sessions, 2);
+    assert.equal(global?.active_days, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('skips unfinished sessions', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-active',
+      videoKey: 'showa-e1',
+      startedAtMs: BASE_MS,
+      endedAtMs: null,
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.sessionsMerged, 0);
+    assert.equal(summary.activeSessionsSkipped, 1);
+    assert.equal(count(localPath, 'SELECT COUNT(*) AS n FROM imm_sessions'), 0);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('copies remote-only historical rollups but never sums shared groups', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    // Remote has a video plus an old rollup row whose sessions were pruned.
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'old-show-e1',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    withWritableDb(remotePath, (remoteDb) => {
+      const remoteVideoId = Number(
+        remoteDb
+          .query<{
+            video_id: number;
+          }>(`SELECT video_id FROM imm_videos WHERE video_key = 'old-show-e1'`)
+          .get()?.video_id,
+      );
+      remoteDb
+        .prepare(
+          `INSERT INTO imm_daily_rollups (rollup_day, video_id, total_sessions, total_active_min, total_lines_seen, total_tokens_seen, total_cards)
+           VALUES (10000, ?, 4, 120.5, 400, 3200, 9)`,
+        )
+        .run(remoteVideoId);
+    });
+
+    // Local already has its own rollup row for a shared group.
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'old-show-e1',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    const localVideoId = withWritableDb(localPath, (localDb) => {
+      const videoId = Number(
+        localDb
+          .query<{
+            video_id: number;
+          }>(`SELECT video_id FROM imm_videos WHERE video_key = 'old-show-e1'`)
+          .get()?.video_id,
+      );
+      localDb
+        .prepare(
+          `INSERT INTO imm_daily_rollups (rollup_day, video_id, total_sessions, total_active_min, total_lines_seen, total_tokens_seen, total_cards)
+           VALUES (10000, ?, 2, 60.0, 200, 1600, 4)`,
+        )
+        .run(videoId);
+      return videoId;
+    });
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    // Shared group (day 10000) untouched; the remote-only session's own group
+    // was recomputed, not copied.
+    assert.equal(summary.dailyRollupsCopied, 0);
+    const shared = queryOne<{ total_sessions: number }>(
+      localPath,
+      'SELECT total_sessions FROM imm_daily_rollups WHERE rollup_day = 10000 AND video_id = ?',
+      [localVideoId],
+    );
+    assert.equal(shared?.total_sessions, 2);
+
+    // Now a rollup for a video with no local sessions at all gets copied.
+    withWritableDb(remotePath, (remoteDb2) => {
+      const orphanVideoId = Number(
+        remoteDb2
+          .prepare(
+            `INSERT INTO imm_videos (video_key, canonical_title, source_type, watched, duration_ms)
+             VALUES ('pruned-show-e1', 'pruned-show-e1', 1, 1, 1440000)`,
+          )
+          .run().lastInsertRowid,
+      );
+      remoteDb2
+        .prepare(
+          `INSERT INTO imm_daily_rollups (rollup_day, video_id, total_sessions, total_active_min, total_lines_seen, total_tokens_seen, total_cards)
+           VALUES (9000, ?, 3, 90.0, 300, 2400, 6)`,
+        )
+        .run(orphanVideoId);
+    });
+
+    const summary2 = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary2.dailyRollupsCopied, 1);
+    const copiedVideoId = Number(
+      queryOne<{ video_id: number }>(
+        localPath,
+        `SELECT video_id FROM imm_videos WHERE video_key = 'pruned-show-e1'`,
+      )?.video_id,
+    );
+    const copied = queryOne<{ total_sessions: number; total_active_min: number }>(
+      localPath,
+      'SELECT total_sessions, total_active_min FROM imm_daily_rollups WHERE rollup_day = 9000 AND video_id = ?',
+      [copiedVideoId],
+    );
+    assert.equal(copied?.total_sessions, 3);
+    assert.equal(copied?.total_active_min, 90.0);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('does not copy remote-only daily rollups into months with local sessions', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(localPath, {
+      uuid: 'local-1',
+      videoKey: 'mixed-month-e1',
+      animeTitleKey: 'mixed-month',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    const remoteDb = new Database(remotePath, { readwrite: true });
+    try {
+      const remoteVideoId = Number(
+        remoteDb
+          .prepare(
+            `INSERT INTO imm_videos (video_key, canonical_title, source_type, watched, duration_ms)
+             VALUES ('mixed-month-e1', 'mixed-month-e1', 1, 1, 1440000)`,
+          )
+          .run().lastInsertRowid,
+      );
+      remoteDb
+        .prepare(
+          `INSERT INTO imm_daily_rollups (rollup_day, video_id, total_sessions, total_active_min, total_lines_seen, total_tokens_seen, total_cards)
+           VALUES (20615, ?, 3, 90.0, 300, 2400, 6)`,
+        )
+        .run(remoteVideoId);
+      remoteDb
+        .prepare(
+          `INSERT INTO imm_monthly_rollups (rollup_month, video_id, total_sessions, total_active_min, total_lines_seen, total_tokens_seen, total_cards)
+           VALUES (202606, ?, 3, 90.0, 300, 2400, 6)`,
+        )
+        .run(remoteVideoId);
+    } finally {
+      remoteDb.close();
+    }
+
+    const summary = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(summary.dailyRollupsCopied, 0);
+    assert.equal(summary.monthlyRollupsCopied, 0);
+    const localVideoId = Number(
+      queryOne<{ video_id: number }>(
+        localPath,
+        `SELECT video_id FROM imm_videos WHERE video_key = 'mixed-month-e1'`,
+      )?.video_id,
+    );
+    assert.equal(
+      count(
+        localPath,
+        'SELECT COUNT(*) AS n FROM imm_daily_rollups WHERE rollup_day = 20615 AND video_id = ?',
+        [localVideoId],
+      ),
+      0,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('rejects snapshots at a different schema version', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    withWritableDb(remotePath, (remoteDb) => {
+      remoteDb.prepare('UPDATE imm_schema_version SET schema_version = 17').run();
+    });
+
+    assert.throws(() => mergeSnapshotIntoDb(localPath, remotePath), /schema version 17/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('createDbSnapshot produces a mergeable copy', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-1',
+      videoKey: 'showa-e1',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+    });
+    const snapshotPath = path.join(dir, 'snapshot.sqlite');
+    createDbSnapshot(remotePath, snapshotPath);
+    assert.ok(fs.existsSync(snapshotPath));
+
+    const summary = mergeSnapshotIntoDb(localPath, snapshotPath);
+    assert.equal(summary.sessionsMerged, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('adopted word frequency excludes active-session counts that merge later', () => {
+  const { dir, localPath, remotePath } = makeDbPair();
+  try {
+    // Remote has an ended session and a stale ACTIVE one (e.g. app crashed).
+    // The remote tracker increments frequency live, so the word's frequency (5)
+    // already includes the active session's 4 occurrences even though that
+    // session's lines are skipped by the merge.
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-ended',
+      videoKey: 'showb-e1',
+      animeTitleKey: 'showb',
+      startedAtMs: BASE_MS,
+      applyLifetime: true,
+      words: [{ headword: '食べる', word: '食べた', reading: 'たべた', count: 1 }],
+    });
+    insertFixtureSession(remotePath, {
+      uuid: 'remote-active',
+      videoKey: 'showb-e2',
+      animeTitleKey: 'showb',
+      startedAtMs: BASE_MS + DAY_MS,
+      endedAtMs: null,
+      words: [{ headword: '食べる', word: '食べた', reading: 'たべた', count: 4 }],
+    });
+
+    const first = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(first.sessionsMerged, 1);
+    assert.equal(first.activeSessionsSkipped, 1);
+    assert.equal(first.wordsAdded, 1);
+    // Only the ended session's count is adopted; the active session's slice
+    // is re-added when that session finalizes and syncs.
+    assert.equal(
+      queryOne<{ frequency: number }>(
+        localPath,
+        `SELECT frequency FROM imm_words WHERE word = '食べた'`,
+      )?.frequency,
+      1,
+    );
+
+    // The remote app restarts and finalizes the stale session.
+    withWritableDb(remotePath, (db) => {
+      db.prepare(
+        `UPDATE imm_sessions SET ended_at_ms = ?, status = 2
+         WHERE session_uuid = 'remote-active'`,
+      ).run(String(BASE_MS + DAY_MS + 1_500_000));
+    });
+
+    const second = mergeSnapshotIntoDb(localPath, remotePath);
+    assert.equal(second.sessionsMerged, 1);
+    assert.equal(second.sessionsAlreadyPresent, 1);
+    // 1 (ended session) + 4 (finalized session), not 5 + 4 = 9.
+    assert.equal(
+      queryOne<{ frequency: number }>(
+        localPath,
+        `SELECT frequency FROM imm_words WHERE word = '食べた'`,
+      )?.frequency,
+      5,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
@@ -0,0 +1,323 @@
+import { Database } from 'bun:sqlite';
+import { SCHEMA_VERSION } from '../../src/core/services/immersion-tracker/types.js';
+import { IMMERSION_DB_FIXTURE_DDL } from './immersion-db-schema.js';
+
+export function createImmersionDbFixture(dbPath: string): void {
+  const db = new Database(dbPath, { create: true });
+  try {
+    db.run('PRAGMA foreign_keys = ON');
+    db.run('PRAGMA journal_mode = WAL');
+    for (const statement of IMMERSION_DB_FIXTURE_DDL.split(';')) {
+      const sql = statement.trim();
+      if (sql) db.run(sql);
+    }
+    db.prepare('INSERT INTO imm_schema_version (schema_version, applied_at_ms) VALUES (?, ?)').run(
+      SCHEMA_VERSION,
+      String(Date.now()),
+    );
+    db.prepare(
+      `INSERT INTO imm_rollup_state(state_key, state_value) VALUES ('last_rollup_sample_ms', 0)`,
+    ).run();
+    db.prepare(
+      `INSERT INTO imm_lifetime_global(global_id, CREATED_DATE, LAST_UPDATE_DATE) VALUES (1, ?, ?)`,
+    ).run(String(Date.now()), String(Date.now()));
+  } finally {
+    db.close();
+  }
+}
+
+let uniqueCounter = 0;
+
+export interface FixtureSessionInput {
+  uuid: string;
+  videoKey: string;
+  animeTitleKey?: string | null;
+  animeEpisodesTotal?: number | null;
+  startedAtMs: number;
+  endedAtMs?: number | null;
+  activeWatchedMs?: number;
+  cardsMined?: number;
+  linesSeen?: number;
+  tokensSeen?: number;
+  watched?: boolean;
+  words?: Array<{ headword: string; word: string; reading: string; count: number }>;
+  applyLifetime?: boolean;
+}
+
+/**
+ * Insert a session (with video/anime/subtitle-line/occurrence rows) the way
+ * the app would have recorded it, optionally crediting lifetime aggregates
+ * the way applySessionLifetimeSummary does for locally-recorded sessions.
+ */
+export function insertFixtureSession(dbPath: string, input: FixtureSessionInput): void {
+  const db = new Database(dbPath, { readwrite: true });
+  const stamp = String(input.startedAtMs);
+  try {
+    db.run('PRAGMA foreign_keys = ON');
+    let animeId: number | null = null;
+    if (input.animeTitleKey) {
+      const existing = db
+        .query<{
+          anime_id: number;
+        }>('SELECT anime_id FROM imm_anime WHERE normalized_title_key = ?')
+        .get(input.animeTitleKey);
+      animeId = existing
+        ? existing.anime_id
+        : Number(
+            db
+              .prepare(
+                `INSERT INTO imm_anime (normalized_title_key, canonical_title, episodes_total, CREATED_DATE, LAST_UPDATE_DATE)
+                 VALUES (?, ?, ?, ?, ?)`,
+              )
+              .run(
+                input.animeTitleKey,
+                input.animeTitleKey,
+                input.animeEpisodesTotal ?? null,
+                stamp,
+                stamp,
+              ).lastInsertRowid,
+          );
+    }
+
+    const existingVideo = db
+      .query<{ video_id: number }>('SELECT video_id FROM imm_videos WHERE video_key = ?')
+      .get(input.videoKey);
+    const videoId = existingVideo
+      ? existingVideo.video_id
+      : Number(
+          db
+            .prepare(
+              `INSERT INTO imm_videos (video_key, anime_id, canonical_title, source_type, source_path, watched, duration_ms, CREATED_DATE, LAST_UPDATE_DATE)
+               VALUES (?, ?, ?, 1, ?, ?, 1440000, ?, ?)`,
+            )
+            .run(
+              input.videoKey,
+              animeId,
+              input.videoKey,
+              `/videos/${input.videoKey}.mkv`,
+              input.watched ? 1 : 0,
+              stamp,
+              stamp,
+            ).lastInsertRowid,
+        );
+    if (input.watched) {
+      db.prepare('UPDATE imm_videos SET watched = 1 WHERE video_id = ?').run(videoId);
+    }
+
+    const endedAtMs =
+      input.endedAtMs === undefined ? input.startedAtMs + 1_500_000 : input.endedAtMs;
+    const activeWatchedMs = input.activeWatchedMs ?? 1_200_000;
+    const cardsMined = input.cardsMined ?? 2;
+    const linesSeen = input.linesSeen ?? 100;
+    const tokensSeen = input.tokensSeen ?? 800;
+    const sessionId = Number(
+      db
+        .prepare(
+          `INSERT INTO imm_sessions (
+             session_uuid, video_id, started_at_ms, ended_at_ms, status,
+             total_watched_ms, active_watched_ms, lines_seen, tokens_seen, cards_mined,
+             CREATED_DATE, LAST_UPDATE_DATE
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        )
+        .run(
+          input.uuid,
+          videoId,
+          String(input.startedAtMs),
+          endedAtMs === null ? null : String(endedAtMs),
+          endedAtMs === null ? 1 : 2,
+          activeWatchedMs,
+          activeWatchedMs,
+          linesSeen,
+          tokensSeen,
+          cardsMined,
+          stamp,
+          stamp,
+        ).lastInsertRowid,
+    );
+
+    db.prepare(
+      `INSERT INTO imm_session_telemetry (
+         session_id, sample_ms, total_watched_ms, active_watched_ms, lines_seen, tokens_seen,
+         cards_mined, CREATED_DATE, LAST_UPDATE_DATE
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      sessionId,
+      String(endedAtMs ?? input.startedAtMs),
+      activeWatchedMs,
+      activeWatchedMs,
+      linesSeen,
+      tokensSeen,
+      cardsMined,
+      stamp,
+      stamp,
+    );
+
+    for (const word of input.words ?? []) {
+      const existing = db
+        .query<{
+          id: number;
+        }>('SELECT id FROM imm_words WHERE headword = ? AND word = ? AND reading = ?')
+        .get(word.headword, word.word, word.reading);
+      const wordId = existing
+        ? existing.id
+        : Number(
+            db
+              .prepare(
+                `INSERT INTO imm_words (headword, word, reading, first_seen, last_seen, frequency)
+                 VALUES (?, ?, ?, ?, ?, 0)`,
+              )
+              .run(
+                word.headword,
+                word.word,
+                word.reading,
+                Math.floor(input.startedAtMs / 1000),
+                Math.floor(input.startedAtMs / 1000),
+              ).lastInsertRowid,
+          );
+      uniqueCounter += 1;
+      const lineId = Number(
+        db
+          .prepare(
+            `INSERT INTO imm_subtitle_lines (session_id, video_id, anime_id, line_index, text, CREATED_DATE, LAST_UPDATE_DATE)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`,
+          )
+          .run(
+            sessionId,
+            videoId,
+            animeId,
+            uniqueCounter,
+            `line ${word.word}`,
+            input.startedAtMs,
+            input.startedAtMs,
+          ).lastInsertRowid,
+      );
+      db.prepare(
+        'INSERT INTO imm_word_line_occurrences (line_id, word_id, occurrence_count) VALUES (?, ?, ?)',
+      ).run(lineId, wordId, word.count);
+      db.prepare('UPDATE imm_words SET frequency = frequency + ? WHERE id = ?').run(
+        word.count,
+        wordId,
+      );
+    }
+
+    if (input.applyLifetime && endedAtMs !== null) {
+      applyFixtureLifetime(db, sessionId, videoId, animeId, {
+        endedAtMs,
+        startedAtMs: input.startedAtMs,
+        activeWatchedMs,
+        cardsMined,
+        linesSeen,
+        tokensSeen,
+        watched: Boolean(input.watched),
+        episodesTotal: input.animeEpisodesTotal ?? null,
+      });
+    }
+  } finally {
+    db.close();
+  }
+}
+
+function applyFixtureLifetime(
+  db: Database,
+  sessionId: number,
+  videoId: number,
+  animeId: number | null,
+  data: {
+    endedAtMs: number;
+    startedAtMs: number;
+    activeWatchedMs: number;
+    cardsMined: number;
+    linesSeen: number;
+    tokensSeen: number;
+    watched: boolean;
+    episodesTotal: number | null;
+  },
+): void {
+  const stamp = String(data.endedAtMs);
+  db.prepare(
+    `INSERT INTO imm_lifetime_applied_sessions (session_id, applied_at_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, ?, ?, ?)`,
+  ).run(sessionId, String(data.endedAtMs), stamp, stamp);
+
+  const mediaLifetime = db
+    .query<{ completed: number }>('SELECT completed FROM imm_lifetime_media WHERE video_id = ?')
+    .get(videoId);
+  const isFirstSessionForVideo = !mediaLifetime;
+  const isFirstCompleted = data.watched && Number(mediaLifetime?.completed ?? 0) <= 0;
+  const dayExpr = `CAST(julianday(CAST(started_at_ms AS REAL) / 1000, 'unixepoch', 'localtime') - 2440587.5 AS INTEGER)`;
+  const otherOnDay = db
+    .query(
+      `SELECT 1 FROM imm_sessions WHERE session_id != ? AND ${dayExpr} =
+         CAST(julianday(CAST(? AS REAL) / 1000, 'unixepoch', 'localtime') - 2440587.5 AS INTEGER) LIMIT 1`,
+    )
+    .get(sessionId, String(data.startedAtMs));
+
+  db.prepare(
+    `UPDATE imm_lifetime_global SET
+       total_sessions = total_sessions + 1,
+       total_active_ms = total_active_ms + ?,
+       total_cards = total_cards + ?,
+       active_days = active_days + ?,
+       episodes_started = episodes_started + ?,
+       episodes_completed = episodes_completed + ?
+     WHERE global_id = 1`,
+  ).run(
+    data.activeWatchedMs,
+    data.cardsMined,
+    otherOnDay ? 0 : 1,
+    isFirstSessionForVideo ? 1 : 0,
+    isFirstCompleted ? 1 : 0,
+  );
+
+  db.prepare(
+    `INSERT INTO imm_lifetime_media (video_id, total_sessions, total_active_ms, total_cards, total_lines_seen, total_tokens_seen, completed, first_watched_ms, last_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+     VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(video_id) DO UPDATE SET
+       total_sessions = total_sessions + 1,
+       total_active_ms = total_active_ms + excluded.total_active_ms,
+       total_cards = total_cards + excluded.total_cards,
+       total_lines_seen = total_lines_seen + excluded.total_lines_seen,
+       total_tokens_seen = total_tokens_seen + excluded.total_tokens_seen,
+       completed = MAX(completed, excluded.completed),
+       last_watched_ms = excluded.last_watched_ms`,
+  ).run(
+    videoId,
+    data.activeWatchedMs,
+    data.cardsMined,
+    data.linesSeen,
+    data.tokensSeen,
+    data.watched ? 1 : 0,
+    String(data.startedAtMs),
+    String(data.endedAtMs),
+    stamp,
+    stamp,
+  );
+
+  if (animeId !== null) {
+    db.prepare(
+      `INSERT INTO imm_lifetime_anime (anime_id, total_sessions, total_active_ms, total_cards, total_lines_seen, total_tokens_seen, episodes_started, episodes_completed, first_watched_ms, last_watched_ms, CREATED_DATE, LAST_UPDATE_DATE)
+       VALUES (?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(anime_id) DO UPDATE SET
+         total_sessions = total_sessions + 1,
+         total_active_ms = total_active_ms + excluded.total_active_ms,
+         total_cards = total_cards + excluded.total_cards,
+         total_lines_seen = total_lines_seen + excluded.total_lines_seen,
+         total_tokens_seen = total_tokens_seen + excluded.total_tokens_seen,
+         episodes_started = episodes_started + excluded.episodes_started,
+         episodes_completed = episodes_completed + excluded.episodes_completed,
+         last_watched_ms = excluded.last_watched_ms`,
+    ).run(
+      animeId,
+      data.activeWatchedMs,
+      data.cardsMined,
+      data.linesSeen,
+      data.tokensSeen,
+      isFirstSessionForVideo ? 1 : 0,
+      isFirstCompleted ? 1 : 0,
+      String(data.startedAtMs),
+      String(data.endedAtMs),
+      stamp,
+      stamp,
+    );
+  }
+}
@@ -0,0 +1,141 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Database as BunDatabase } from 'bun:sqlite';
+import { ensureSchema } from '../../src/core/services/immersion-tracker/storage.js';
+import { createImmersionDbFixture, insertFixtureSession } from './immersion-db-fixture.js';
+
+type SchemaRow = { type: string; name: string; tbl_name: string; sql: string | null };
+
+const SYNC_SCHEMA_OBJECTS = [
+  'imm_anime',
+  'imm_videos',
+  'imm_sessions',
+  'imm_session_telemetry',
+  'imm_session_events',
+  'imm_daily_rollups',
+  'imm_monthly_rollups',
+  'imm_words',
+  'imm_kanji',
+  'imm_subtitle_lines',
+  'imm_word_line_occurrences',
+  'imm_kanji_line_occurrences',
+  'imm_media_art',
+  'imm_youtube_videos',
+  'imm_cover_art_blobs',
+  'imm_lifetime_global',
+  'imm_lifetime_anime',
+  'imm_lifetime_media',
+  'imm_lifetime_applied_sessions',
+  'imm_stats_excluded_words',
+  'idx_anime_normalized_title',
+  'idx_anime_anilist_id',
+  'idx_videos_anime_id',
+  'idx_sessions_video_started',
+  'idx_sessions_status_started',
+  'idx_sessions_started_at',
+  'idx_sessions_ended_at',
+  'idx_telemetry_session_sample',
+  'idx_telemetry_sample_ms',
+  'idx_events_session_ts',
+  'idx_events_type_ts',
+  'idx_rollups_day_video',
+  'idx_rollups_month_video',
+  'idx_words_headword_word_reading',
+  'idx_words_frequency',
+  'idx_kanji_kanji',
+  'idx_kanji_frequency',
+  'idx_subtitle_lines_session_line',
+  'idx_subtitle_lines_video_line',
+  'idx_subtitle_lines_anime_line',
+  'idx_word_line_occurrences_word',
+  'idx_kanji_line_occurrences_kanji',
+  'idx_media_art_cover_blob_hash',
+  'idx_media_art_anilist_id',
+  'idx_media_art_cover_url',
+  'idx_youtube_videos_channel_id',
+  'idx_youtube_videos_youtube_video_id',
+] as const;
+
+function normalizeSql(sql: string | null): string {
+  return (sql ?? '')
+    .replace(/\bIF NOT EXISTS\b/gi, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([(),])/g, '$1')
+    .replace(/,\s+/g, ', ')
+    .trim();
+}
+
+function readSchema(dbPath: string): Map<string, string> {
+  const db = new BunDatabase(dbPath, { readonly: true });
+  try {
+    const rows = db
+      .query<SchemaRow>(
+        `SELECT type, name, tbl_name, sql
+         FROM sqlite_schema
+         WHERE name IN (${SYNC_SCHEMA_OBJECTS.map(() => '?').join(',')})
+         ORDER BY type, name`,
+      )
+      .all(...SYNC_SCHEMA_OBJECTS);
+    return new Map(rows.map((row) => [row.name, normalizeSql(row.sql)]));
+  } finally {
+    db.close();
+  }
+}
+
+test('fixture schema stays aligned with production sync-touched tables and indexes', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-schema-'));
+  const fixturePath = path.join(dir, 'fixture.sqlite');
+  const productionPath = path.join(dir, 'production.sqlite');
+  const productionDb = new BunDatabase(productionPath, { create: true });
+  try {
+    createImmersionDbFixture(fixturePath);
+    ensureSchema(productionDb as never);
+    productionDb.close();
+
+    const fixtureSchema = readSchema(fixturePath);
+    const productionSchema = readSchema(productionPath);
+    assert.deepEqual(fixtureSchema, productionSchema);
+  } finally {
+    try {
+      productionDb.close();
+    } catch {
+      // already closed
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('fixture session inserts enforce foreign keys', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-fixture-foreign-keys-'));
+  const fixturePath = path.join(dir, 'fixture.sqlite');
+  try {
+    createImmersionDbFixture(fixturePath);
+    const db = new BunDatabase(fixturePath, { readwrite: true });
+    try {
+      db.run(`
+        CREATE TRIGGER remove_fixture_video
+        BEFORE INSERT ON imm_sessions
+        BEGIN
+          DELETE FROM imm_videos WHERE video_id = NEW.video_id;
+        END
+      `);
+    } finally {
+      db.close();
+    }
+
+    assert.throws(
+      () =>
+        insertFixtureSession(fixturePath, {
+          uuid: 'foreign-key-check',
+          videoKey: 'foreign-key-check',
+          startedAtMs: Date.UTC(2026, 6, 9),
+        }),
+      /FOREIGN KEY constraint failed/,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
@@ -0,0 +1,323 @@
+// Schema-version-18 shape of the tables the sync merge touches (plus the
+// app's indexes), mirroring ensureSchema / ensureLifetimeSummaryTables /
+// ensureStatsExcludedWordsTable in src/core/services/immersion-tracker/storage.ts.
+export const IMMERSION_DB_FIXTURE_DDL = `
+  CREATE TABLE imm_schema_version (
+    schema_version INTEGER PRIMARY KEY,
+    applied_at_ms TEXT NOT NULL
+  );
+  CREATE TABLE imm_rollup_state(
+    state_key TEXT PRIMARY KEY,
+    state_value TEXT NOT NULL
+  );
+  CREATE TABLE imm_anime(
+    anime_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    normalized_title_key TEXT NOT NULL UNIQUE,
+    canonical_title TEXT NOT NULL,
+    anilist_id INTEGER UNIQUE,
+    title_romaji TEXT,
+    title_english TEXT,
+    title_native TEXT,
+    episodes_total INTEGER,
+    description TEXT,
+    metadata_json TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT
+  );
+  CREATE TABLE imm_videos(
+    video_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    video_key TEXT NOT NULL UNIQUE,
+    anime_id INTEGER,
+    canonical_title TEXT NOT NULL,
+    source_type INTEGER NOT NULL,
+    source_path TEXT,
+    source_url TEXT,
+    parsed_basename TEXT,
+    parsed_title TEXT,
+    parsed_season INTEGER,
+    parsed_episode INTEGER,
+    parser_source TEXT,
+    parser_confidence REAL,
+    parse_metadata_json TEXT,
+    watched INTEGER NOT NULL DEFAULT 0,
+    duration_ms INTEGER NOT NULL CHECK(duration_ms>=0),
+    file_size_bytes INTEGER CHECK(file_size_bytes>=0),
+    codec_id INTEGER, container_id INTEGER,
+    width_px INTEGER, height_px INTEGER, fps_x100 INTEGER,
+    bitrate_kbps INTEGER, audio_codec_id INTEGER,
+    hash_sha256 TEXT, screenshot_path TEXT,
+    metadata_json TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(anime_id) REFERENCES imm_anime(anime_id) ON DELETE SET NULL
+  );
+  CREATE TABLE imm_sessions(
+    session_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_uuid TEXT NOT NULL UNIQUE,
+    video_id INTEGER NOT NULL,
+    started_at_ms TEXT NOT NULL, ended_at_ms TEXT,
+    status INTEGER NOT NULL,
+    locale_id INTEGER, target_lang_id INTEGER,
+    difficulty_tier INTEGER, subtitle_mode INTEGER,
+    ended_media_ms INTEGER,
+    total_watched_ms INTEGER NOT NULL DEFAULT 0,
+    active_watched_ms INTEGER NOT NULL DEFAULT 0,
+    lines_seen INTEGER NOT NULL DEFAULT 0,
+    tokens_seen INTEGER NOT NULL DEFAULT 0,
+    cards_mined INTEGER NOT NULL DEFAULT 0,
+    lookup_count INTEGER NOT NULL DEFAULT 0,
+    lookup_hits INTEGER NOT NULL DEFAULT 0,
+    yomitan_lookup_count INTEGER NOT NULL DEFAULT 0,
+    pause_count INTEGER NOT NULL DEFAULT 0,
+    pause_ms INTEGER NOT NULL DEFAULT 0,
+    seek_forward_count INTEGER NOT NULL DEFAULT 0,
+    seek_backward_count INTEGER NOT NULL DEFAULT 0,
+    media_buffer_events INTEGER NOT NULL DEFAULT 0,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(video_id) REFERENCES imm_videos(video_id)
+  );
+  CREATE TABLE imm_session_telemetry(
+    telemetry_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    sample_ms TEXT NOT NULL,
+    total_watched_ms INTEGER NOT NULL DEFAULT 0,
+    active_watched_ms INTEGER NOT NULL DEFAULT 0,
+    lines_seen INTEGER NOT NULL DEFAULT 0,
+    tokens_seen INTEGER NOT NULL DEFAULT 0,
+    cards_mined INTEGER NOT NULL DEFAULT 0,
+    lookup_count INTEGER NOT NULL DEFAULT 0,
+    lookup_hits INTEGER NOT NULL DEFAULT 0,
+    yomitan_lookup_count INTEGER NOT NULL DEFAULT 0,
+    pause_count INTEGER NOT NULL DEFAULT 0,
+    pause_ms INTEGER NOT NULL DEFAULT 0,
+    seek_forward_count INTEGER NOT NULL DEFAULT 0,
+    seek_backward_count INTEGER NOT NULL DEFAULT 0,
+    media_buffer_events INTEGER NOT NULL DEFAULT 0,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(session_id) REFERENCES imm_sessions(session_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_session_events(
+    event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    ts_ms TEXT NOT NULL,
+    event_type INTEGER NOT NULL,
+    line_index INTEGER,
+    segment_start_ms INTEGER,
+    segment_end_ms INTEGER,
+    tokens_delta INTEGER NOT NULL DEFAULT 0,
+    cards_delta INTEGER NOT NULL DEFAULT 0,
+    payload_json TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(session_id) REFERENCES imm_sessions(session_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_daily_rollups(
+    rollup_day INTEGER NOT NULL,
+    video_id INTEGER,
+    total_sessions INTEGER NOT NULL DEFAULT 0,
+    total_active_min REAL NOT NULL DEFAULT 0,
+    total_lines_seen INTEGER NOT NULL DEFAULT 0,
+    total_tokens_seen INTEGER NOT NULL DEFAULT 0,
+    total_cards INTEGER NOT NULL DEFAULT 0,
+    cards_per_hour REAL,
+    tokens_per_min REAL,
+    lookup_hit_rate REAL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    PRIMARY KEY (rollup_day, video_id)
+  );
+  CREATE TABLE imm_monthly_rollups(
+    rollup_month INTEGER NOT NULL,
+    video_id INTEGER,
+    total_sessions INTEGER NOT NULL DEFAULT 0,
+    total_active_min REAL NOT NULL DEFAULT 0,
+    total_lines_seen INTEGER NOT NULL DEFAULT 0,
+    total_tokens_seen INTEGER NOT NULL DEFAULT 0,
+    total_cards INTEGER NOT NULL DEFAULT 0,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    PRIMARY KEY (rollup_month, video_id)
+  );
+  CREATE TABLE imm_words(
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    headword TEXT,
+    word TEXT,
+    reading TEXT,
+    part_of_speech TEXT,
+    pos1 TEXT,
+    pos2 TEXT,
+    pos3 TEXT,
+    first_seen REAL,
+    last_seen REAL,
+    frequency INTEGER,
+    frequency_rank INTEGER,
+    UNIQUE(headword, word, reading)
+  );
+  CREATE TABLE imm_kanji(
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    kanji TEXT,
+    first_seen REAL,
+    last_seen REAL,
+    frequency INTEGER,
+    UNIQUE(kanji)
+  );
+  CREATE TABLE imm_subtitle_lines(
+    line_id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+    event_id INTEGER,
+    video_id INTEGER NOT NULL,
+    anime_id INTEGER,
+    line_index INTEGER NOT NULL,
+    segment_start_ms INTEGER,
+    segment_end_ms INTEGER,
+    text TEXT NOT NULL,
+    secondary_text TEXT,
+    CREATED_DATE INTEGER,
+    LAST_UPDATE_DATE INTEGER,
+    FOREIGN KEY(session_id) REFERENCES imm_sessions(session_id) ON DELETE CASCADE,
+    FOREIGN KEY(event_id) REFERENCES imm_session_events(event_id) ON DELETE SET NULL,
+    FOREIGN KEY(video_id) REFERENCES imm_videos(video_id) ON DELETE CASCADE,
+    FOREIGN KEY(anime_id) REFERENCES imm_anime(anime_id) ON DELETE SET NULL
+  );
+  CREATE TABLE imm_word_line_occurrences(
+    line_id INTEGER NOT NULL,
+    word_id INTEGER NOT NULL,
+    occurrence_count INTEGER NOT NULL,
+    PRIMARY KEY(line_id, word_id),
+    FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
+    FOREIGN KEY(word_id) REFERENCES imm_words(id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_kanji_line_occurrences(
+    line_id INTEGER NOT NULL,
+    kanji_id INTEGER NOT NULL,
+    occurrence_count INTEGER NOT NULL,
+    PRIMARY KEY(line_id, kanji_id),
+    FOREIGN KEY(line_id) REFERENCES imm_subtitle_lines(line_id) ON DELETE CASCADE,
+    FOREIGN KEY(kanji_id) REFERENCES imm_kanji(id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_media_art(
+    video_id INTEGER PRIMARY KEY,
+    anilist_id INTEGER,
+    cover_url TEXT,
+    cover_blob BLOB,
+    cover_blob_hash TEXT,
+    title_romaji TEXT,
+    title_english TEXT,
+    episodes_total INTEGER,
+    fetched_at_ms TEXT NOT NULL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(video_id) REFERENCES imm_videos(video_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_youtube_videos(
+    video_id INTEGER PRIMARY KEY,
+    youtube_video_id TEXT NOT NULL,
+    video_url TEXT NOT NULL,
+    video_title TEXT,
+    video_thumbnail_url TEXT,
+    channel_id TEXT,
+    channel_name TEXT,
+    channel_url TEXT,
+    channel_thumbnail_url TEXT,
+    uploader_id TEXT,
+    uploader_url TEXT,
+    description TEXT,
+    metadata_json TEXT,
+    fetched_at_ms TEXT NOT NULL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(video_id) REFERENCES imm_videos(video_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_cover_art_blobs(
+    blob_hash TEXT PRIMARY KEY,
+    cover_blob BLOB NOT NULL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT
+  );
+  CREATE TABLE imm_lifetime_global(
+    global_id INTEGER PRIMARY KEY CHECK(global_id = 1),
+    total_sessions INTEGER NOT NULL DEFAULT 0,
+    total_active_ms INTEGER NOT NULL DEFAULT 0,
+    total_cards INTEGER NOT NULL DEFAULT 0,
+    active_days INTEGER NOT NULL DEFAULT 0,
+    episodes_started INTEGER NOT NULL DEFAULT 0,
+    episodes_completed INTEGER NOT NULL DEFAULT 0,
+    anime_completed INTEGER NOT NULL DEFAULT 0,
+    last_rebuilt_ms TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT
+  );
+  CREATE TABLE imm_lifetime_anime(
+    anime_id INTEGER PRIMARY KEY,
+    total_sessions INTEGER NOT NULL DEFAULT 0,
+    total_active_ms INTEGER NOT NULL DEFAULT 0,
+    total_cards INTEGER NOT NULL DEFAULT 0,
+    total_lines_seen INTEGER NOT NULL DEFAULT 0,
+    total_tokens_seen INTEGER NOT NULL DEFAULT 0,
+    episodes_started INTEGER NOT NULL DEFAULT 0,
+    episodes_completed INTEGER NOT NULL DEFAULT 0,
+    first_watched_ms TEXT,
+    last_watched_ms TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(anime_id) REFERENCES imm_anime(anime_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_lifetime_media(
+    video_id INTEGER PRIMARY KEY,
+    total_sessions INTEGER NOT NULL DEFAULT 0,
+    total_active_ms INTEGER NOT NULL DEFAULT 0,
+    total_cards INTEGER NOT NULL DEFAULT 0,
+    total_lines_seen INTEGER NOT NULL DEFAULT 0,
+    total_tokens_seen INTEGER NOT NULL DEFAULT 0,
+    completed INTEGER NOT NULL DEFAULT 0,
+    first_watched_ms TEXT,
+    last_watched_ms TEXT,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(video_id) REFERENCES imm_videos(video_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_lifetime_applied_sessions(
+    session_id INTEGER PRIMARY KEY,
+    applied_at_ms TEXT NOT NULL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    FOREIGN KEY(session_id) REFERENCES imm_sessions(session_id) ON DELETE CASCADE
+  );
+  CREATE TABLE imm_stats_excluded_words(
+    headword TEXT NOT NULL,
+    word TEXT NOT NULL,
+    reading TEXT NOT NULL,
+    CREATED_DATE TEXT,
+    LAST_UPDATE_DATE TEXT,
+    PRIMARY KEY(headword, word, reading)
+  );
+  CREATE INDEX idx_anime_normalized_title ON imm_anime(normalized_title_key);
+  CREATE INDEX idx_anime_anilist_id ON imm_anime(anilist_id);
+  CREATE INDEX idx_videos_anime_id ON imm_videos(anime_id);
+  CREATE INDEX idx_sessions_video_started ON imm_sessions(video_id, started_at_ms DESC);
+  CREATE INDEX idx_sessions_status_started ON imm_sessions(status, started_at_ms DESC);
+  CREATE INDEX idx_sessions_started_at ON imm_sessions(started_at_ms DESC);
+  CREATE INDEX idx_sessions_ended_at ON imm_sessions(ended_at_ms DESC);
+  CREATE INDEX idx_telemetry_session_sample ON imm_session_telemetry(session_id, sample_ms DESC);
+  CREATE INDEX idx_telemetry_sample_ms ON imm_session_telemetry(sample_ms DESC);
+  CREATE INDEX idx_events_session_ts ON imm_session_events(session_id, ts_ms DESC);
+  CREATE INDEX idx_events_type_ts ON imm_session_events(event_type, ts_ms DESC);
+  CREATE INDEX idx_rollups_day_video ON imm_daily_rollups(rollup_day, video_id);
+  CREATE INDEX idx_rollups_month_video ON imm_monthly_rollups(rollup_month, video_id);
+  CREATE INDEX idx_words_headword_word_reading ON imm_words(headword, word, reading);
+  CREATE INDEX idx_words_frequency ON imm_words(frequency DESC);
+  CREATE INDEX idx_kanji_kanji ON imm_kanji(kanji);
+  CREATE INDEX idx_kanji_frequency ON imm_kanji(frequency DESC);
+  CREATE INDEX idx_subtitle_lines_session_line ON imm_subtitle_lines(session_id, line_index);
+  CREATE INDEX idx_subtitle_lines_video_line ON imm_subtitle_lines(video_id, line_index);
+  CREATE INDEX idx_subtitle_lines_anime_line ON imm_subtitle_lines(anime_id, line_index);
+  CREATE INDEX idx_word_line_occurrences_word ON imm_word_line_occurrences(word_id, line_id);
+  CREATE INDEX idx_kanji_line_occurrences_kanji ON imm_kanji_line_occurrences(kanji_id, line_id);
+  CREATE INDEX idx_media_art_cover_blob_hash ON imm_media_art(cover_blob_hash);
+  CREATE INDEX idx_media_art_anilist_id ON imm_media_art(anilist_id);
+  CREATE INDEX idx_media_art_cover_url ON imm_media_art(cover_url);
+  CREATE INDEX idx_youtube_videos_channel_id ON imm_youtube_videos(channel_id);
+  CREATE INDEX idx_youtube_videos_youtube_video_id ON imm_youtube_videos(youtube_video_id);
+`;
@@ -113,6 +113,10 @@ export interface Args {
  texthookerOpenBrowser: boolean;
  useRofi: boolean;
  history: boolean;
+  sync: boolean;
+  /** App-owned sync argv tokens forwarded verbatim to `--sync-cli sync`. */
+  syncCliTokens: string[];
+  syncUi: boolean;
  logLevel: LogLevel;
  logRotation: LogRotation;
  passwordStore: string;
@@ -2,7 +2,7 @@
  "name": "subminer",
  "productName": "SubMiner",
  "desktopName": "SubMiner.desktop",
-  "version": "0.18.0",
+  "version": "0.19.0-beta.3",
  "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
  "packageManager": "bun@1.3.5",
  "main": "dist/main-entry.js",
@@ -13,14 +13,17 @@
    "get-frequency:electron": "bun run build:yomitan && bun build scripts/get_frequency.ts --format=cjs --target=node --outfile dist/scripts/get_frequency.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/get_frequency.js --pretty --color-top-x 10000 --yomitan-user-data ~/.config/SubMiner --colorized-line",
    "test-yomitan-parser": "bun run scripts/test-yomitan-parser.ts",
    "test-yomitan-parser:electron": "bun run build:yomitan && bun build scripts/test-yomitan-parser.ts --format=cjs --target=node --outfile dist/scripts/test-yomitan-parser.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/test-yomitan-parser.js",
+    "record-tokenizer-fixture:electron": "bun run build:yomitan && bun build scripts/record-tokenizer-fixture.ts --format=cjs --target=node --outfile dist/scripts/record-tokenizer-fixture.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/record-tokenizer-fixture.js",
+    "compare-yomitan-api:electron": "bun run build:yomitan && bun build scripts/compare-yomitan-api.ts --format=cjs --target=node --outfile dist/scripts/compare-yomitan-api.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/compare-yomitan-api.js",
    "build:yomitan": "bun scripts/build-yomitan.mjs",
    "build:assets": "bun scripts/prepare-build-assets.mjs",
    "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --banner='#!/usr/bin/env bun' --outfile=dist/launcher/subminer",
    "build:stats": "cd stats && bun run build",
    "dev:stats": "cd stats && bun run dev",
-    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:launcher && bun run build:assets",
+    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:syncui && bun run build:launcher && bun run build:assets",
    "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
    "build:settings": "esbuild src/settings/settings.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/settings/settings.js --sourcemap",
+    "build:syncui": "esbuild src/syncui/syncui.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/syncui/syncui.js --sourcemap && esbuild src/preload-syncui.ts --bundle --platform=node --format=cjs --target=node20 --external:electron --outfile=dist/preload-syncui.js --sourcemap",
    "changelog:build": "bun run scripts/build-changelog.ts build-release",
    "changelog:check": "bun run scripts/build-changelog.ts check",
    "changelog:docs": "bun run scripts/build-changelog.ts docs",
@@ -44,13 +47,9 @@
    "docs:preview": "bun run --cwd docs-site docs:preview",
    "docs:test": "bun run --cwd docs-site test",
    "test:docs:kb": "bun test scripts/docs-knowledge-base.test.ts",
-    "test:config:src": "bun scripts/run-test-lane.mjs config",
-    "test:config:smoke:dist": "bun test dist/config/path-resolution.test.js",
    "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-process-start-retries.lua && lua scripts/test-plugin-restart-feedback.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
    "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
-    "test:launcher:src": "bun scripts/run-test-lane.mjs launcher && bun run test:plugin:src",
-    "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
-    "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
+    "test:smoke:dist": "bun scripts/run-test-lane.mjs bun-src-full",
    "test:subtitle:src": "bun test src/core/services/subsync.test.ts src/subsync/utils.test.ts",
    "test:immersion:sqlite:src": "bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts",
    "test:immersion:sqlite:dist": "bun test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js",
@@ -61,15 +60,13 @@
    "test:launcher:unit:src": "bun scripts/run-test-lane.mjs bun-launcher-unit",
    "test:scripts": "bun scripts/run-test-lane.mjs scripts",
    "test:stats": "bun scripts/run-test-lane.mjs stats",
-    "test:launcher:env:src": "bun run test:launcher:smoke:src && bun run test:plugin:src",
-    "test:env": "bun run test:launcher:env:src && bun run test:immersion:sqlite:src",
-    "test:runtime:compat": "bun run tsc && bun test dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/overlay-manager.test.js dist/main/config-validation.test.js dist/main/runtime/registry.test.js dist/main/runtime/startup-config.test.js",
-    "test:node:compat": "bun run test:runtime:compat",
+    "test:env": "bun run test:launcher:smoke:src && bun run test:plugin:src && bun run test:immersion:sqlite:src",
+    "test:runtime:compat": "bun run tsc && bun scripts/run-test-lane.mjs bun-src-full",
    "test": "bun run test:fast",
-    "test:config": "bun run test:config:src",
-    "test:launcher": "bun run test:launcher:src",
+    "test:config": "bun scripts/run-test-lane.mjs config",
+    "test:launcher": "bun scripts/run-test-lane.mjs launcher && bun run test:plugin:src",
    "test:subtitle": "bun run test:subtitle:src",
-    "test:fast": "bun run test:src && bun run test:launcher:unit:src && bun run test:scripts && bun run test:runtime:compat",
+    "test:fast": "bun run test:src && bun run test:launcher:unit:src && bun run test:scripts",
    "generate:config-example": "bun run src/generate-config-example.ts",
    "verify:config-example": "bun run src/verify-config-example.ts",
    "start": "bun run build && electron . --start",
@@ -84,13 +81,18 @@
    "build:win:unsigned": "bun run build && node scripts/build-win-unsigned.mjs"
  },
  "overrides": {
-    "@xmldom/xmldom": "0.8.12",
+    "@xmldom/xmldom": "0.8.13",
    "app-builder-lib": "26.8.2",
+    "brace-expansion": "5.0.7",
    "electron-builder-squirrel-windows": "26.8.2",
+    "form-data": "4.0.6",
+    "ip-address": "10.2.0",
+    "js-yaml": "4.3.0",
    "lodash": "4.18.0",
    "minimatch": "10.2.3",
    "picomatch": "4.0.4",
-    "tar": "7.5.11"
+    "tar": "7.5.21",
+    "tmp": "0.2.7"
  },
  "keywords": [
    "anki",
@@ -107,21 +109,22 @@
  "dependencies": {
    "@fontsource-variable/geist": "^5.2.8",
    "@fontsource-variable/geist-mono": "^5.2.7",
-    "@xhayper/discord-rpc": "^1.3.3",
-    "axios": "^1.13.5",
+    "@xhayper/discord-rpc": "^1.3.4",
+    "axios": "^1.18.1",
    "commander": "^14.0.3",
    "electron-updater": "^6.8.3",
-    "hono": "^4.12.7",
+    "hono": "^4.12.28",
    "jsonc-parser": "^3.3.1",
    "koffi": "^2.15.6",
    "libsql": "^0.5.22",
-    "ws": "^8.19.0"
+    "ws": "^8.21.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@types/ws": "^8.18.1",
-    "electron": "42.2.0",
+    "electron": "42.6.0",
    "electron-builder": "26.8.2",
+    "undici": "7.28.0",
    "esbuild": "^0.25.12",
    "eslint": "^10.4.0",
    "prettier": "^3.8.1",
@@ -256,5 +259,8 @@
        "to": "launcher/subminer"
      }
    ]
+  },
+  "patchedDependencies": {
+    "@discordjs/rest@2.6.1": "patches/@discordjs%2Frest@2.6.1.patch"
  }
 }
@@ -0,0 +1,13 @@
+diff --git a/package.json b/package.json
+index 02d2d8809a98c5d32b889fceba11458660f1fa6a..72cd7004d92809689daaeec1cd8a274e1cabdff5 100644
+--- a/package.json
+++ b/package.json
+@@ -77,7 +77,7 @@
+     "discord-api-types": "^0.38.40",
+     "magic-bytes.js": "^1.13.0",
+     "tslib": "^2.6.3",
+-    "undici": "6.24.1",
+    "undici": "6.27.0",
+     "@discordjs/collection": "^2.1.1",
+     "@discordjs/util": "^1.2.0"
+   },
@@ -254,6 +254,8 @@ function M.create(ctx)
 			return { "--open-runtime-options" }
 		elseif action_id == "openJimaku" then
 			return { "--open-jimaku" }
+		elseif action_id == "openTsukihime" or action_id == "openAnimetosho" then
+			return { "--open-tsukihime" }
 		elseif action_id == "openYoutubePicker" then
 			return { "--open-youtube-picker" }
 		elseif action_id == "openSessionHelp" then
@@ -1,73 +1,55 @@
 > This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.

-<!-- prerelease-base-version: 0.18.0 -->
+<!-- prerelease-base-version: 0.19.0 -->

 ## Highlights
 ### Added
- **Watch History Browser**
-  - New `subminer -H` / `--history` command lets you browse your local watch history, replay the last episode, jump to the next one, or pick an episode via fzf or rofi.
-  - The rofi picker now shows AniList cover art for each show, making it easier to spot the right title at a glance.
- **Card Audio Normalization**
-  - Audio extracted for Anki cards is now volume-normalized by default, giving more consistent playback loudness across cards.
-  - Prefer the original source volume? Disable it via the new `ankiConnect.media.normalizeAudio` setting.
+
+- **Sync Stats & History**
+  - New **Sync Stats & History** window (tray menu) and `subminer sync <host>` command keep mining stats and watch history in sync between machines over SSH, with saved devices, per-host sync direction, and live stage-by-stage progress.
+  - Merges are safe to repeat: data combines without duplicates, and hosts with auto-sync enabled sync automatically in the background on a schedule, reporting results as overlay notifications.
+  - Manual snapshot tools (create, merge, reveal, delete) and connection testing cover one-off transfers; Windows machines running the built-in OpenSSH Server work as sync remotes too, with no setup needed beyond SSH access. Power users can script transfers directly with `--push`/`--pull`, `--check`, `--snapshot`/`--merge`, and `--json` flags.
+
+- **TsukiHime Subtitle Downloads**
+  - Download Japanese and secondary-language subtitles for the current video directly from TsukiHime, mirroring the existing Jimaku flow.
+  - Press `Ctrl+Shift+T` to search by tabs for the primary and secondary languages; the matching release is found automatically from the video filename and loads straight into mpv, no API key required.
+
+- **Post-Playback History Menu**
+  - After a watch-history episode ends or mpv closes, the fzf/rofi launcher returns to that series with options to play the previous or next episode, rewatch, pick another episode, or quit SubMiner.
+  - Previous/Next continue across season directories, so you can binge a show without manually browsing folders.

 ### Changed
- **New App Icon**
-  - SubMiner now ships pixel-art submarine artwork contributed by an anonymous community member.
-  - Applied across the app icon, tray icon, notifications, README, docs site, and stats page.
- **Launcher Preview Layout**
-  - fzf previews in the launcher now sit below the menu instead of beside it, giving long titles and metadata more horizontal room.
+
+- **Clipboard-Video Shortcut**
+  - The "append clipboard video to queue" shortcut is now configurable via `shortcuts.appendClipboardVideoToQueue` instead of being fixed.

 ### Fixed
- **Character Name Highlighting in Subtitles**
-  - Fixed unspaced Japanese names (e.g. 東紫乃, 渡辺真奈美) being split at the wrong point, which left surnames like 東 and 渡辺 without their character portrait or hover lookup.
-  - Fixed names getting cut off or losing their highlight when caught by the subtitle scanner's punctuation handling, misclassified by grammar tagging, or swallowed entirely by a longer generic dictionary match (e.g. ヨータ disappearing inside a false とヨー match).
-  - Fixed a single unrecognized word in a subtitle line (like a stray interjection) causing character-name highlighting to drop for the whole line instead of just that word.
-  - No action needed — existing data upgrades automatically the next time a matching name is seen.
- **Known-Word Highlighting**
-  - Words are no longer marked "known" (green) just because they share spelling with a known Anki card that actually teaches a different reading (e.g. 床 read as とこ no longer falsely matches a known 床/ゆか card).
-  - Kanji words are also no longer marked known just because a different mined word happens to share their reading (e.g. 渓谷/けいこく no longer falsely matches a known 警告/けいこく card).
-  - Single-kana grammar tokens (particles like よ, え) no longer borrow an unrelated card's reading and get falsely painted as known.
-  - Stats sessions now correctly reflect known-word counts again after the reading-aware matching upgrade, instead of showing 0 everywhere.
- **Annotation Highlighting Refinements**
-  - Restored frequency/JLPT highlighting and vocabulary-stat counting for words like 確かに and やはり, which were wrongly treated as grammar noise.
-  - Kanji nouns that MeCab tags as "non-independent" (e.g. 日, 点, 以外) also keep their highlighting and stats counting again.
-  - Suffix-only tokens (e.g. さん, れる) are now excluded from JLPT/frequency highlighting by default to match how particles and interjections are treated; known-word highlighting for them still works, and this is configurable.
- **Unparsed Subtitle Text**
-  - Subtitle text the dictionary can't recognize (like a truncated verb form) is now still hoverable for lookup and correctly counted toward a sentence's difficulty, instead of showing as dead, non-interactive text.
- **Kiku Manual Field Grouping**
-  - Fixed the field-grouping dialog getting stuck invisible behind fullscreen video on Hyprland/Wayland, and failing silently on repeated attempts after the first use.
-  - Fixed a timed-out or failed grouping request leaving an invisible, stuck dialog covering the video; it now closes automatically so the overlay recovers.
-  - Fixed a duplicate "Field grouping cancelled" notification appearing when grouping was cancelled via the trigger shortcut, and added a proper error message for the previously-silent case where the original card can no longer be loaded.
- **Secondary Subtitles**
-  - Karaoke-style secondary subtitles (common in opening/ending songs) no longer spam dozens of lines down the screen; repeated lines are now collapsed and the subtitle area is capped to a strip at the top.
- **YouTube Extraction**
-  - Fixed direct YouTube stream extraction occasionally corrupting the stream URL and causing failed audio/video capture.
- **Background Stats Server**
-  - Launching SubMiner in the background now correctly auto-starts the stats server when enabled, and won't start a duplicate if one's already running.
- **Stats Trend Charts**
-  - All trend chart titles now show by default, with the ability to hide specific titles (remembered across sessions) and cap how many top titles a chart displays.
- **Stats Cover Art**
-  - Cover art now loads as soon as a series starts playing instead of waiting for your first visit to its detail page, so the stats timeline shows artwork right away.
-  - Existing series missing art are backfilled automatically the next time you open the stats page.
+
+- **Word Highlighting Accuracy**
+  - Fixed several incorrect word highlighting and annotation cases: inconsistent part-of-speech exclusions on merged quote-particle tokens, missing annotations for rare kanji, katakana punctuation wrongly treated as non-kana noise, and certain kanji vocabulary skipped for next-level ("N+1") highlighting.
+
+- **Startup Playback Pausing Too Early**
+  - Fixed playback resuming before subtitle processing finished warming up, which could briefly show untranslated subtitles right after opening a video.
+  - Most noticeable when resuming mid-episode or when a subtitle cue starts within the first couple of seconds.
+
+- **Linux AppImage Crash Notification on Quit**
+  - Fixed a spurious "Service Crash" desktop notification appearing after closing a video when running the Linux AppImage.
+  - If needed, the mount-keepalive behavior behind this fix can be disabled with `SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1`.
+
+- **AnkiConnect Proxy Port Conflict**
+  - Fixed video playback failing to start when another process already held the configured AnkiConnect proxy port; SubMiner now shows a notification explaining how to resolve the conflict instead of crashing.
+
+- **Stats & Settings Reliability**
+  - Hardened the stats server against malformed requests, stalled AniList lookups, media mismatches during word mining, and missing Yomitan connections.
+  - AnkiConnect settings validation now preserves valid custom configurations while safely falling back on invalid values instead of failing.

 ## What's Changed

- fix(youtube): parse mpv EDL stream URLs with byte-length guards by @ksyasuda in #134
- Normalize generated Anki audio by default by @ksyasuda in #135
- feat(launcher): add -H/--history command to browse local watch history by @ksyasuda in #136
- fix(overlay): prevent field grouping modal from freezing overlay on Hyprland by @ksyasuda in #138
- fix(overlay): collapse karaoke syllable spam in secondary subtitles by @ksyasuda in #139
- feat(stats): Trends dashboard overhaul — title visibility, ranking modes, calendar-accurate windows, tooltips by @ksyasuda in #140
- feat(branding): replace app icon with contributed pixel-art set by @ksyasuda in #141
- feat(anki): reading-aware known-word matching (cache v3) by @ksyasuda in #142
- fix(stats): start stats server on background app launch by @ksyasuda in #144
- fix(tokenizer): keep unparsed Yomitan tokens hoverable by @ksyasuda in #145
- fix(overlay): resolve unspaced Japanese name splits and scan recovery by @ksyasuda in #146
- fix(tokenizer): prevent grammar tokens from borrowing known-word highlight via unrelated readings by @ksyasuda in #147
- fix(stats): fetch cover art eagerly at session start instead of on series page visit by @ksyasuda in #148
- fix(overlay): keep frequency/JLPT highlight for kanji non-independent nouns by @ksyasuda in #150
- fix(tokenizer): greedy name pre-pass to prevent generic matches swallowing character names by @ksyasuda in #151
+- feat(shortcuts): make clipboard-video-append shortcut configurable by @ksyasuda in #158
+- refactor(tokenizer): extract subtitle annotation filter into rule table by @ksyasuda in #162
+- refactor(tsukihime): swap Animetosho backend for TsukiHime API by @ksyasuda in #165
+- refactor: split anki-connect and stats-server resolvers into modules by @ksyasuda in #169
+- feat(launcher): add post-playback history menu with previous episode by @ksyasuda in #170

 ## Installation

@@ -1,89 +0,0 @@
-## Highlights
-### Added
-
- **Sentence Audio Normalization**
-  - Generated sentence audio is now normalized to -23 LUFS by default, giving mined clips consistent volume across shows.
-  - Clips captured from playback can also mirror mpv's software volume curve, with a limiter to prevent clipping when boosted.
-  - Both behaviors are controlled independently and can be turned off in the Anki Connect media settings.
-
- **Watch History Browser**
-  - Added `subminer -H` / `--history` to browse local watch history, replay the last episode, continue to the next one, or jump to any past episode.
-  - Works with fzf or rofi; the rofi picker shows AniList cover art already stored in the stats database.
-
-### Changed
-
- **Known-Word Highlighting Accuracy**
-  - Highlighting now compares subtitle and Anki-card readings, so it no longer confuses homographs like 床/とこ vs 床/ゆか or unrelated kanji that happen to share a reading.
-  - Standalone suffix words such as さん or れる are now excluded from JLPT/frequency/N+1 annotations by default, matching how particles and interjections are already treated (configurable if you'd rather keep them annotated).
-  - Cards without readings still fall back to word-only matching; the highlighting cache upgrades automatically with no action needed.
-
- **Stats Trend Charts**
-  - Overhauled trend charts with persisted title visibility, per-chart title limits, "top" and "most recent" ranking modes, an option to show or hide empty days, calendar-aligned periods, and sortable multi-column tooltips.
-
- **New App Icon**
-  - Replaced the SubMiner icon with new pixel-art submarine artwork contributed by an anonymous community member, now used across the app icon, tray, notifications, README, docs site, and stats page.
-
- **Launcher Preview Layout**
-  - fzf previews now sit below the launcher menu instead of beside it, giving long titles and metadata more horizontal room.
-
-### Fixed
-
- **Character Name Recognition**
-  - Character dictionaries now correctly split unspaced AniList native names and validate readings, so overlay portraits, highlights, and hover lookups work reliably even without MeCab installed.
-  - Name matches survive punctuation and unmatched text and no longer get overridden by generic dictionary matches or wrongly split from longer words like 空気.
-  - Existing installs regenerate automatically and upgrade to exact splits once MeCab is available — no action needed.
-
- **Frequency & JLPT Highlighting Coverage**
-  - Content adverbs (確かに, やはり) and kanji nouns MeCab tags as non-independent (日, 点, 以外) are now correctly included in frequency/JLPT highlighting and vocabulary stats.
-  - Lexicalized kana expressions like かといって keep their frequency annotations, while interjections, pronouns, and pure grammar fragments are still filtered out as noise.
-
- **Unparsed Text Hover Lookup**
-  - Subtitle text Yomitan can't fully parse — truncated inflections like とこ戻ろ… or elongation runs like ぅ～ — is hoverable again for dictionary lookup.
-  - These runs stay excluded from frequency/JLPT highlighting and vocabulary stats, same as bracketed captions and punctuation-only text.
-
- **Karaoke-Style Secondary Subtitles**
-  - Secondary subtitles no longer flood the screen with dozens of one-syllable lines during karaoke-style openings and endings.
-  - Repeated events now collapse into a single line, and the secondary subtitle area stays capped to a strip at the top.
-
- **Kiku Field Grouping Reliability**
-  - The manual field-grouping dialog now stays above fullscreen mpv on Hyprland/Wayland and keeps working across repeated attempts.
-  - Abandoned grouping windows close automatically after a timeout or failure, and each attempt now reports a clear success or error, including when the original card can no longer be loaded.
-
- **Background Stats Server Startup**
-  - Background `subminer app` launches now start the stats server automatically when enabled, and skip startup if one is already running.
-
- **AniList Cover Art Timing**
-  - Stats now fetches the best-match AniList cover as soon as a new series starts playing, so artwork appears in the timeline immediately instead of only after visiting the series page.
-  - Existing series missing art get backfilled automatically on the next Stats page visit.
-
- **YouTube Direct Stream Playback**
-  - Fixed direct YouTube stream extraction so mpv's EDL stream URLs are parsed correctly, preventing corrupted signed video URLs and the resulting ffmpeg 403 errors.
-
-## What's Changed
-
- fix(youtube): parse mpv EDL stream URLs with byte-length guards by @ksyasuda in #134
- Normalize generated Anki audio by default by @ksyasuda in #135
- feat(launcher): add -H/--history command to browse local watch history by @ksyasuda in #136
- fix(overlay): prevent field grouping modal from freezing overlay on Hyprland by @ksyasuda in #138
- fix(overlay): collapse karaoke syllable spam in secondary subtitles by @ksyasuda in #139
- feat(stats): Trends dashboard overhaul — title visibility, ranking modes, calendar-accurate windows, tooltips by @ksyasuda in #140
- feat(branding): replace app icon with contributed pixel-art set by @ksyasuda in #141
- feat(anki): reading-aware known-word matching (cache v3) by @ksyasuda in #142
- fix(stats): start stats server on background app launch by @ksyasuda in #144
- fix(tokenizer): keep unparsed Yomitan tokens hoverable by @ksyasuda in #145
- fix(overlay): resolve unspaced Japanese name splits and scan recovery by @ksyasuda in #146
- fix(tokenizer): prevent grammar tokens from borrowing known-word highlight via unrelated readings by @ksyasuda in #147
- fix(stats): fetch cover art eagerly at session start instead of on series page visit by @ksyasuda in #148
-
-## Installation
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
- Linux: `SubMiner.AppImage`
- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
-
-Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+const source = readFileSync('scripts/compare-yomitan-api.ts', 'utf8');
+
+test('creates the configured Yomitan user-data directory before Electron uses it', () => {
+  const setPathIndex = source.indexOf(
+    "electronModule.app.setPath('userData', options.yomitanUserDataPath)",
+  );
+  assert.notEqual(setPathIndex, -1);
+
+  const mkdirIndex = source.lastIndexOf(
+    'fs.mkdirSync(options.yomitanUserDataPath, { recursive: true })',
+    setPathIndex,
+  );
+  assert.ok(mkdirIndex > -1, 'must create the user-data directory');
+  assert.ok(mkdirIndex < setPathIndex, 'must create the directory before app.setPath');
+});
+
+test('lets output drain by using exitCode in the top-level completion handlers', () => {
+  const completionHandlers = source.slice(source.lastIndexOf('\nmain()'));
+  assert.match(completionHandlers, /process\.exitCode = process\.exitCode \?\? 0/);
+  assert.match(completionHandlers, /process\.exitCode = 1/);
+  assert.doesNotMatch(completionHandlers, /process\.exit\(/);
+});
@@ -0,0 +1,589 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+import { createTokenizerDepsRuntime, tokenizeSubtitle } from '../src/core/services/tokenizer.js';
+import { selectYomitanParseTokens } from '../src/core/services/tokenizer/parser-selection-stage.js';
+import { enrichTokensWithMecabPos1 } from '../src/core/services/tokenizer/parser-enrichment-stage.js';
+import { resolveYomitanExtensionPath as resolveBuiltYomitanExtensionPath } from '../src/core/services/yomitan-extension-paths.js';
+import { MecabTokenizer } from '../src/mecab-tokenizer.js';
+import type { MergedToken } from '../src/types.js';
+
+import { fetchYomitanApi } from './yomitan-api-request.js';
+
+// Compares SubMiner's full tokenization pipeline against a stock Yomitan
+// instance reached through the yomitan-api native-messaging bridge
+// (https://github.com/yomidevs/yomitan-api, default http://127.0.0.1:19633).
+// The API response is raw parseText output; it is mapped through SubMiner's
+// own selectYomitanParseTokens so both sides share identical mapping
+// semantics and the diff isolates real segmentation/headword divergence.
+
+const DEFAULT_YOMITAN_USER_DATA_PATH = path.join(os.homedir(), '.config', 'SubMiner');
+const DEFAULT_API_URL = 'http://127.0.0.1:19633';
+const DEFAULT_SCAN_LENGTH = 40;
+const FIXTURE_DIR = path.join('src', 'core', 'services', 'tokenizer', '__fixtures__', 'golden');
+
+interface CliOptions {
+  sentences: string[];
+  fromFixtures: boolean;
+  apiUrl: string;
+  scanLength: number;
+  emitJson: boolean;
+  nameMatch: boolean;
+  yomitanExtensionPath?: string;
+  yomitanUserDataPath: string;
+  mecabCommand?: string;
+  mecabDictionaryPath?: string;
+}
+
+function printUsage(): void {
+  process.stdout.write(`Usage:
+  bun run compare-yomitan-api:electron -- [options] [sentence ...]
+
+  Compares SubMiner tokenization against a stock Yomitan instance via the
+  yomitan-api bridge. Without sentences, compares every golden-corpus fixture
+  text plus any --file lines.
+
+  --from-fixtures            Include golden-corpus fixture texts (default when
+                             no sentences are given).
+  --file <path>              Read additional sentences, one per line.
+  --api-url <url>            yomitan-api base URL (default: ${DEFAULT_API_URL}).
+  --scan-length <n>          Scan length for the API request (default: ${DEFAULT_SCAN_LENGTH}).
+  --name-match               Keep SubMiner's character-name pre-pass enabled.
+                             Off by default: stock Yomitan has no name regions,
+                             so it would only add noise to the diff.
+  --json                     Emit machine-readable JSON instead of a report.
+  --yomitan-extension <path> Path to built Yomitan extension directory.
+  --yomitan-user-data <path> Electron userData directory (default: ~/.config/SubMiner).
+  --mecab-command <path>     MeCab binary (default: mecab).
+  --mecab-dictionary <path>  MeCab dictionary directory.
+  -h, --help                 Show usage.
+
+  Exits 1 when any sentence diverges, 0 when everything matches.
+`);
+}
+
+function requireValue(args: string[], flag: string): string {
+  const next = args.shift();
+  if (!next) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return next;
+}
+
+function parseCliArgs(argv: string[]): CliOptions {
+  const args = [...argv];
+  const sentences: string[] = [];
+  let fromFixtures = false;
+  let apiUrl = DEFAULT_API_URL;
+  let scanLength = DEFAULT_SCAN_LENGTH;
+  let emitJson = false;
+  let nameMatch = false;
+  let yomitanExtensionPath: string | undefined;
+  let yomitanUserDataPath = DEFAULT_YOMITAN_USER_DATA_PATH;
+  let mecabCommand: string | undefined;
+  let mecabDictionaryPath: string | undefined;
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (!arg) break;
+
+    if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+    if (arg === '--from-fixtures') {
+      fromFixtures = true;
+      continue;
+    }
+    if (arg === '--file') {
+      const filePath = requireValue(args, arg);
+      const lines = fs
+        .readFileSync(filePath, 'utf8')
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+      sentences.push(...lines);
+      continue;
+    }
+    if (arg === '--api-url') {
+      apiUrl = requireValue(args, arg).replace(/\/$/, '');
+      continue;
+    }
+    if (arg === '--scan-length') {
+      const value = Number(requireValue(args, arg));
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error('Invalid --scan-length value');
+      }
+      scanLength = value;
+      continue;
+    }
+    if (arg === '--json') {
+      emitJson = true;
+      continue;
+    }
+    if (arg === '--name-match') {
+      nameMatch = true;
+      continue;
+    }
+    if (arg === '--yomitan-extension') {
+      yomitanExtensionPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--yomitan-user-data') {
+      yomitanUserDataPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--mecab-command') {
+      mecabCommand = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--mecab-dictionary') {
+      mecabDictionaryPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg.startsWith('-') && arg !== '-') {
+      throw new Error(`Unknown flag: ${arg}`);
+    }
+    sentences.push(arg);
+  }
+
+  if (sentences.length === 0) {
+    fromFixtures = true;
+  }
+
+  return {
+    sentences,
+    fromFixtures,
+    apiUrl,
+    scanLength,
+    emitJson,
+    nameMatch,
+    yomitanExtensionPath,
+    yomitanUserDataPath,
+    mecabCommand,
+    mecabDictionaryPath,
+  };
+}
+
+function loadFixtureSentences(): string[] {
+  if (!fs.existsSync(FIXTURE_DIR)) {
+    return [];
+  }
+  return fs
+    .readdirSync(FIXTURE_DIR)
+    .filter((entry) => entry.endsWith('.json'))
+    .sort()
+    .map((entry) => {
+      const fixture = JSON.parse(fs.readFileSync(path.join(FIXTURE_DIR, entry), 'utf8')) as {
+        input?: { text?: string };
+      };
+      return fixture.input?.text ?? '';
+    })
+    .filter((text) => text.length > 0);
+}
+
+function normalizeTokenizerText(text: string): string {
+  return text
+    .replace(/\r\n/g, '\n')
+    .replace(/\\N/g, '\n')
+    .replace(/\\n/g, '\n')
+    .trim()
+    .replace(/\n/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+interface FuriganaChunk {
+  startPos: number;
+  endPos: number;
+  reading: string;
+  headword: string;
+}
+
+// Walk the raw parseText content the same way the parse-result mapper does
+// (whole segments, char offsets accumulated across lines) and capture, per
+// chunk, the effective reading (kana chunks read as themselves) and the first
+// dictionary headword term. The mapper's token spans are authoritative for
+// grouping; these chunks supply the complete reading/lemma the legacy mapper
+// does not synthesize.
+function collectFuriganaChunks(parseResults: unknown): FuriganaChunk[] {
+  const chunks: FuriganaChunk[] = [];
+  if (!Array.isArray(parseResults)) {
+    return chunks;
+  }
+  const content = (parseResults[0] as { content?: unknown } | undefined)?.content;
+  if (!Array.isArray(content)) {
+    return chunks;
+  }
+  let charOffset = 0;
+  for (const line of content) {
+    if (!Array.isArray(line)) {
+      continue;
+    }
+    for (const segment of line as Array<Record<string, unknown>>) {
+      const text = typeof segment?.text === 'string' ? segment.text : '';
+      if (!text) {
+        continue;
+      }
+      const reading =
+        typeof segment.reading === 'string' && segment.reading.length > 0 ? segment.reading : text;
+      let headword = '';
+      const headwords = segment.headwords;
+      if (Array.isArray(headwords)) {
+        for (const row of headwords) {
+          const first = Array.isArray(row) ? (row[0] as { term?: unknown } | undefined) : undefined;
+          if (first && typeof first.term === 'string' && first.term.trim().length > 0) {
+            headword = first.term.trim();
+            break;
+          }
+        }
+      }
+      chunks.push({ startPos: charOffset, endPos: charOffset + text.length, reading, headword });
+      charOffset += text.length;
+    }
+  }
+  return chunks;
+}
+
+function overlayChunkMetadata(tokens: MergedToken[], chunks: FuriganaChunk[]): MergedToken[] {
+  return tokens.map((token) => {
+    const covered = chunks.filter(
+      (chunk) => chunk.startPos >= token.startPos && chunk.endPos <= token.endPos,
+    );
+    if (covered.length === 0) {
+      return token;
+    }
+    const reading = covered.map((chunk) => chunk.reading).join('');
+    const headword = covered.find((chunk) => chunk.headword)?.headword ?? token.surface;
+    return { ...token, reading, headword };
+  });
+}
+
+async function fetchApiTokens(
+  apiUrl: string,
+  text: string,
+  scanLength: number,
+): Promise<MergedToken[] | null> {
+  const response = await fetchYomitanApi(`${apiUrl}/tokenize`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text, scanLength, parser: 'scanning-parser' }),
+  });
+  if (!response.ok) {
+    throw new Error(`yomitan-api /tokenize responded ${response.status}`);
+  }
+  const parseResults = (await response.json()) as unknown;
+  const tokens = selectYomitanParseTokens(parseResults, () => false, 'headword');
+  if (!tokens) {
+    return tokens;
+  }
+  return overlayChunkMetadata(tokens, collectFuriganaChunks(parseResults));
+}
+
+interface ComparedToken {
+  surface: string;
+  reading: string;
+  headword: string;
+  startPos: number;
+  endPos: number;
+  frequencyRank?: number;
+}
+
+function toComparedTokens(tokens: MergedToken[] | null): ComparedToken[] {
+  return (tokens ?? []).map((token) => ({
+    surface: token.surface,
+    reading: token.reading,
+    headword: token.headword,
+    startPos: token.startPos,
+    endPos: token.endPos,
+    frequencyRank: token.frequencyRank,
+  }));
+}
+
+interface MismatchRegion {
+  subminer: ComparedToken[];
+  yomitan: ComparedToken[];
+}
+
+interface PairDiff {
+  surface: string;
+  field: 'headword' | 'reading';
+  subminer: string;
+  yomitan: string;
+}
+
+interface SentenceComparison {
+  text: string;
+  subminerTokens: ComparedToken[];
+  yomitanTokens: ComparedToken[];
+  segmentationMatches: boolean;
+  mismatchRegions: MismatchRegion[];
+  pairDiffs: PairDiff[];
+  error?: string;
+}
+
+// Walk both token lists in span order. Tokens whose [startPos, endPos) agree
+// are paired; disagreeing runs are grouped until the boundaries realign.
+function compareTokenLists(
+  subminer: ComparedToken[],
+  yomitan: ComparedToken[],
+): Pick<SentenceComparison, 'segmentationMatches' | 'mismatchRegions' | 'pairDiffs'> {
+  const mismatchRegions: MismatchRegion[] = [];
+  const pairDiffs: PairDiff[] = [];
+  let i = 0;
+  let j = 0;
+
+  while (i < subminer.length || j < yomitan.length) {
+    const a = subminer[i];
+    const b = yomitan[j];
+    if (a && b && a.startPos === b.startPos && a.endPos === b.endPos) {
+      if (a.headword !== b.headword) {
+        pairDiffs.push({
+          surface: a.surface,
+          field: 'headword',
+          subminer: a.headword,
+          yomitan: b.headword,
+        });
+      }
+      // An empty reading means "reads as its surface" (kana tokens, unparsed
+      // runs) — normalize before comparing.
+      if ((a.reading || a.surface) !== (b.reading || b.surface)) {
+        pairDiffs.push({
+          surface: a.surface,
+          field: 'reading',
+          subminer: a.reading,
+          yomitan: b.reading,
+        });
+      }
+      i += 1;
+      j += 1;
+      continue;
+    }
+
+    const region: MismatchRegion = { subminer: [], yomitan: [] };
+    let aEnd = a ? a.startPos : Number.MAX_SAFE_INTEGER;
+    let bEnd = b ? b.startPos : Number.MAX_SAFE_INTEGER;
+    do {
+      if (aEnd <= bEnd && i < subminer.length) {
+        const token = subminer[i];
+        if (token) {
+          region.subminer.push(token);
+          aEnd = token.endPos;
+        }
+        i += 1;
+      } else if (j < yomitan.length) {
+        const token = yomitan[j];
+        if (token) {
+          region.yomitan.push(token);
+          bEnd = token.endPos;
+        }
+        j += 1;
+      } else {
+        break;
+      }
+    } while (aEnd !== bEnd && (i < subminer.length || j < yomitan.length));
+    mismatchRegions.push(region);
+  }
+
+  return {
+    segmentationMatches: mismatchRegions.length === 0,
+    mismatchRegions,
+    pairDiffs,
+  };
+}
+
+function renderTokenRun(tokens: ComparedToken[]): string {
+  if (tokens.length === 0) {
+    return '(no tokens)';
+  }
+  return tokens.map((token) => token.surface).join('|');
+}
+
+function renderReport(comparisons: SentenceComparison[]): void {
+  let divergent = 0;
+  for (const comparison of comparisons) {
+    const clean =
+      !comparison.error && comparison.segmentationMatches && comparison.pairDiffs.length === 0;
+    if (!clean) {
+      divergent += 1;
+    }
+    process.stdout.write(`\n${clean ? 'MATCH' : 'DIFF '} ${comparison.text}\n`);
+    if (comparison.error) {
+      process.stdout.write(`  error: ${comparison.error}\n`);
+      continue;
+    }
+    if (clean) {
+      process.stdout.write(
+        `  ${comparison.subminerTokens.length} tokens: ${renderTokenRun(comparison.subminerTokens)}\n`,
+      );
+      continue;
+    }
+    if (!comparison.segmentationMatches) {
+      process.stdout.write('  segmentation:\n');
+      for (const region of comparison.mismatchRegions) {
+        process.stdout.write(`    subminer: ${renderTokenRun(region.subminer)}\n`);
+        process.stdout.write(`    yomitan:  ${renderTokenRun(region.yomitan)}\n`);
+      }
+    }
+    for (const diff of comparison.pairDiffs) {
+      process.stdout.write(
+        `  ${diff.surface}: ${diff.field} "${diff.subminer}" (subminer) vs "${diff.yomitan}" (yomitan)\n`,
+      );
+    }
+  }
+  process.stdout.write(
+    `\n${comparisons.length - divergent}/${comparisons.length} sentences match stock Yomitan\n`,
+  );
+}
+
+async function main(): Promise<void> {
+  const options = parseCliArgs(process.argv.slice(2));
+  const sentences = [...(options.fromFixtures ? loadFixtureSentences() : []), ...options.sentences];
+  if (sentences.length === 0) {
+    throw new Error('No sentences to compare (no fixtures found and none provided).');
+  }
+
+  // Fail fast with a clear message when the bridge is not running.
+  try {
+    const probe = await fetchYomitanApi(`${options.apiUrl}/serverVersion`, {
+      method: 'POST',
+      body: '{}',
+    });
+    if (!probe.ok) {
+      throw new Error(`status ${probe.status}`);
+    }
+  } catch (error) {
+    throw new Error(
+      `yomitan-api is not reachable at ${options.apiUrl} (${(error as Error).message}). ` +
+        'Ensure the browser is running and "Enable Yomitan API" is on in Yomitan settings.',
+    );
+  }
+
+  const electronModule = await import('electron').catch(() => null);
+  if (!electronModule?.app || !electronModule?.session) {
+    throw new Error('Electron runtime required; run via `bun run compare-yomitan-api:electron`.');
+  }
+
+  const mecabTokenizer = new MecabTokenizer({
+    mecabCommand: options.mecabCommand,
+    dictionaryPath: options.mecabDictionaryPath,
+  });
+  if (!(await mecabTokenizer.checkAvailability())) {
+    throw new Error('MeCab is not available on this system.');
+  }
+
+  if (typeof electronModule.app.setPath === 'function') {
+    fs.mkdirSync(options.yomitanUserDataPath, { recursive: true });
+    electronModule.app.setPath('userData', options.yomitanUserDataPath);
+  }
+  await electronModule.app.whenReady();
+
+  const extensionPath = resolveBuiltYomitanExtensionPath({
+    explicitPath: options.yomitanExtensionPath,
+    cwd: process.cwd(),
+  });
+  if (!extensionPath) {
+    throw new Error('No built Yomitan extension found; run `bun run build:yomitan` first.');
+  }
+  const extension = await electronModule.session.defaultSession.loadExtension(extensionPath, {
+    allowFileAccess: true,
+  });
+
+  let parserWindow: Electron.BrowserWindow | null = null;
+  let parserReadyPromise: Promise<void> | null = null;
+  let parserInitPromise: Promise<boolean> | null = null;
+
+  const runtimeDeps = createTokenizerDepsRuntime({
+    getYomitanExt: () => extension,
+    getYomitanParserWindow: () => parserWindow,
+    setYomitanParserWindow: (window) => {
+      parserWindow = window;
+    },
+    getYomitanParserReadyPromise: () => parserReadyPromise,
+    setYomitanParserReadyPromise: (promise) => {
+      parserReadyPromise = promise;
+    },
+    getYomitanParserInitPromise: () => parserInitPromise,
+    setYomitanParserInitPromise: (promise) => {
+      parserInitPromise = promise;
+    },
+    isKnownWord: () => false,
+    getKnownWordMatchMode: () => 'headword',
+    getJlptLevel: () => null,
+    getNameMatchEnabled: () => options.nameMatch,
+    getMecabTokenizer: () => ({
+      tokenize: (text: string) => mecabTokenizer.tokenize(text),
+    }),
+  });
+  const deps = {
+    ...runtimeDeps,
+    enrichTokensWithMecab: async (
+      tokens: Parameters<typeof enrichTokensWithMecabPos1>[0],
+      mecabTokens: Parameters<typeof enrichTokensWithMecabPos1>[1],
+    ) => enrichTokensWithMecabPos1(tokens, mecabTokens),
+  };
+
+  const comparisons: SentenceComparison[] = [];
+  try {
+    for (const sentence of sentences) {
+      const text = normalizeTokenizerText(sentence);
+      try {
+        const [subtitleData, apiTokens] = await Promise.all([
+          tokenizeSubtitle(text, deps),
+          fetchApiTokens(options.apiUrl, text, options.scanLength),
+        ]);
+        const subminerTokens = toComparedTokens(subtitleData.tokens);
+        const yomitanTokens = toComparedTokens(apiTokens);
+        comparisons.push({
+          text,
+          subminerTokens,
+          yomitanTokens,
+          ...compareTokenLists(subminerTokens, yomitanTokens),
+        });
+      } catch (error) {
+        comparisons.push({
+          text,
+          subminerTokens: [],
+          yomitanTokens: [],
+          segmentationMatches: false,
+          mismatchRegions: [],
+          pairDiffs: [],
+          error: (error as Error).message,
+        });
+      }
+    }
+  } finally {
+    if (parserWindow) {
+      const window = parserWindow as Electron.BrowserWindow;
+      if (!window.isDestroyed()) {
+        window.destroy();
+      }
+    }
+    electronModule.app.quit();
+  }
+
+  if (options.emitJson) {
+    process.stdout.write(`${JSON.stringify(comparisons, null, 2)}\n`);
+  } else {
+    renderReport(comparisons);
+  }
+
+  const anyDivergence = comparisons.some(
+    (comparison) =>
+      comparison.error !== undefined ||
+      !comparison.segmentationMatches ||
+      comparison.pairDiffs.length > 0,
+  );
+  process.exitCode = anyDivergence ? 1 : 0;
+}
+
+main()
+  .then(() => {
+    process.exitCode = process.exitCode ?? 0;
+  })
+  .catch((error) => {
+    console.error(`Error: ${(error as Error).message}`);
+    process.exitCode = 1;
+  });
@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+test('build:syncui bundles the sandboxed preload and keeps Electron external', () => {
+  const packageJson = JSON.parse(
+    fs.readFileSync(path.join(import.meta.dir, '..', 'package.json'), 'utf8'),
+  ) as { scripts: Record<string, string> };
+  const command = packageJson.scripts['build:syncui'] ?? '';
+
+  assert.match(command, /src\/preload-syncui\.ts/);
+  assert.match(command, /--bundle/);
+  assert.match(command, /--external:electron/);
+  assert.match(command, /--outfile=dist\/preload-syncui\.js/);
+});
@@ -9,6 +9,8 @@ const rendererSourceDir = path.join(repoRoot, 'src', 'renderer');
 const rendererOutputDir = path.join(repoRoot, 'dist', 'renderer');
 const settingsSourceDir = path.join(repoRoot, 'src', 'settings');
 const settingsOutputDir = path.join(repoRoot, 'dist', 'settings');
+const syncUiSourceDir = path.join(repoRoot, 'src', 'syncui');
+const syncUiOutputDir = path.join(repoRoot, 'dist', 'syncui');
 const scriptsOutputDir = path.join(repoRoot, 'dist', 'scripts');
 const macosHelperSourcePath = path.join(scriptDir, 'get-mpv-window-macos.swift');
 const macosHelperBinaryPath = path.join(scriptsOutputDir, 'get-mpv-window-macos');
@@ -41,6 +43,10 @@ function copySettingsAssets() {
  copyAssets(settingsSourceDir, settingsOutputDir, 'settings');
 }

+function copySyncUiAssets() {
+  copyAssets(syncUiSourceDir, syncUiOutputDir, 'syncui');
+}
+
 function fallbackToMacosSource() {
  copyFile(macosHelperSourcePath, macosHelperSourceCopyPath);
  process.stdout.write(`Staged macOS helper source fallback: ${macosHelperSourceCopyPath}\n`);
@@ -83,6 +89,7 @@ function buildMacosHelper() {
 function main() {
  copyRendererAssets();
  copySettingsAssets();
+  copySyncUiAssets();
  buildMacosHelper();
 }

@@ -0,0 +1,496 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+import { createTokenizerDepsRuntime, tokenizeSubtitle } from '../src/core/services/tokenizer.js';
+import {
+  buildFixtureLookups,
+  classifyInjectedScript,
+  fixtureConfigGetters,
+  hashInjectedScript,
+  projectGoldenTokens,
+  pruneGoldenMessages,
+} from '../src/core/services/tokenizer/golden-corpus-harness.js';
+import type {
+  GoldenFixture,
+  GoldenFixtureConfig,
+  GoldenRecordedMessage,
+  GoldenRecordedScript,
+} from '../src/core/services/tokenizer/golden-corpus-harness.js';
+import { enrichTokensWithMecabPos1 } from '../src/core/services/tokenizer/parser-enrichment-stage.js';
+import { resolveYomitanExtensionPath as resolveBuiltYomitanExtensionPath } from '../src/core/services/yomitan-extension-paths.js';
+import { MecabTokenizer } from '../src/mecab-tokenizer.js';
+import type { JlptLevel, Token } from '../src/types.js';
+
+const DEFAULT_YOMITAN_USER_DATA_PATH = path.join(os.homedir(), '.config', 'SubMiner');
+const DEFAULT_FIXTURE_DIR = path.join(
+  'src',
+  'core',
+  'services',
+  'tokenizer',
+  '__fixtures__',
+  'golden',
+);
+const JLPT_LEVELS: ReadonlySet<string> = new Set(['N1', 'N2', 'N3', 'N4', 'N5']);
+
+interface CliOptions {
+  name: string;
+  text: string;
+  description?: string;
+  issueRefs: string[];
+  config: GoldenFixtureConfig;
+  outDir: string;
+  force: boolean;
+  yomitanExtensionPath?: string;
+  yomitanUserDataPath: string;
+  mecabCommand?: string;
+  mecabDictionaryPath?: string;
+}
+
+function printUsage(): void {
+  process.stdout.write(`Usage:
+  bun run record-tokenizer-fixture:electron -- --name <slug> [options] <subtitle text>
+
+  Records a golden tokenizer fixture: raw Yomitan backend responses, raw MeCab
+  tokens, and the annotated tokens the full pipeline produced for the text.
+  Review the "expected" block before committing — it becomes the assertion.
+
+  --name <slug>              Fixture name (file becomes <slug>.json). Required.
+  --description <text>       What behavior this fixture pins down.
+  --issue <ref>              Related issue/PR ref, repeatable (e.g. --issue "#156").
+  --known-word <w[:reading]> Mark a word known, repeatable.
+  --jlpt <term=level>        JLPT level for a term, repeatable (level N1..N5).
+  --local-frequency <t=rank> Local frequency-dictionary rank, repeatable.
+  --match-mode <mode>        Known-word match mode: headword|surface.
+  --min-sentence-words <n>   Minimum sentence words for N+1.
+  --no-known-words           Disable known-word annotation.
+  --no-nplusone              Disable N+1 targeting.
+  --no-jlpt                  Disable JLPT annotation.
+  --no-name-match            Disable character-name matching.
+  --no-frequency             Disable frequency annotation.
+  --out-dir <path>           Fixture directory (default: ${DEFAULT_FIXTURE_DIR}).
+  --force                    Overwrite an existing fixture file.
+  --yomitan-extension <path> Path to built Yomitan extension directory.
+  --yomitan-user-data <path> Electron userData directory (default: ~/.config/SubMiner).
+  --mecab-command <path>     MeCab binary (default: mecab).
+  --mecab-dictionary <path>  MeCab dictionary directory.
+  -h, --help                 Show usage.
+`);
+}
+
+function requireValue(args: string[], flag: string): string {
+  const next = args.shift();
+  if (!next) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return next;
+}
+
+function parseCliArgs(argv: string[]): CliOptions {
+  const args = [...argv];
+  const inputParts: string[] = [];
+  const issueRefs: string[] = [];
+  const knownWords: GoldenFixtureConfig['knownWords'] = [];
+  const jlptLevels: Record<string, JlptLevel> = {};
+  const localFrequencyRanks: Record<string, number> = {};
+  const config: GoldenFixtureConfig = {};
+  let name: string | undefined;
+  let description: string | undefined;
+  let outDir = DEFAULT_FIXTURE_DIR;
+  let force = false;
+  let yomitanExtensionPath: string | undefined;
+  let yomitanUserDataPath = DEFAULT_YOMITAN_USER_DATA_PATH;
+  let mecabCommand: string | undefined;
+  let mecabDictionaryPath: string | undefined;
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (!arg) break;
+
+    if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+    if (arg === '--name') {
+      name = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--description') {
+      description = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--issue') {
+      issueRefs.push(requireValue(args, arg));
+      continue;
+    }
+    if (arg === '--known-word') {
+      const value = requireValue(args, arg);
+      const separator = value.indexOf(':');
+      knownWords.push(
+        separator === -1
+          ? value
+          : { text: value.slice(0, separator), reading: value.slice(separator + 1) },
+      );
+      continue;
+    }
+    if (arg === '--jlpt') {
+      const value = requireValue(args, arg);
+      const separator = value.indexOf('=');
+      const level = separator === -1 ? '' : value.slice(separator + 1);
+      if (separator === -1 || !JLPT_LEVELS.has(level)) {
+        throw new Error(`Invalid --jlpt value "${value}"; expected <term>=N1..N5`);
+      }
+      jlptLevels[value.slice(0, separator)] = level as JlptLevel;
+      continue;
+    }
+    if (arg === '--local-frequency') {
+      const value = requireValue(args, arg);
+      const separator = value.indexOf('=');
+      const rank = separator === -1 ? Number.NaN : Number(value.slice(separator + 1));
+      if (!Number.isInteger(rank) || rank <= 0) {
+        throw new Error(`Invalid --local-frequency value "${value}"; expected <term>=<rank>`);
+      }
+      localFrequencyRanks[value.slice(0, separator)] = rank;
+      continue;
+    }
+    if (arg === '--match-mode') {
+      const value = requireValue(args, arg);
+      if (value !== 'headword' && value !== 'surface') {
+        throw new Error(`Invalid --match-mode "${value}"; expected headword|surface`);
+      }
+      config.knownWordMatchMode = value;
+      config.frequencyMatchMode = value;
+      continue;
+    }
+    if (arg === '--min-sentence-words') {
+      const value = Number(requireValue(args, arg));
+      if (!Number.isInteger(value) || value < 0) {
+        throw new Error('Invalid --min-sentence-words value');
+      }
+      config.minSentenceWordsForNPlusOne = value;
+      continue;
+    }
+    if (arg === '--no-known-words') {
+      config.knownWordsEnabled = false;
+      continue;
+    }
+    if (arg === '--no-nplusone') {
+      config.nPlusOneEnabled = false;
+      continue;
+    }
+    if (arg === '--no-jlpt') {
+      config.jlptEnabled = false;
+      continue;
+    }
+    if (arg === '--no-name-match') {
+      config.nameMatchEnabled = false;
+      continue;
+    }
+    if (arg === '--no-frequency') {
+      config.frequencyEnabled = false;
+      continue;
+    }
+    if (arg === '--out-dir') {
+      outDir = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+    if (arg === '--yomitan-extension') {
+      yomitanExtensionPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--yomitan-user-data') {
+      yomitanUserDataPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--mecab-command') {
+      mecabCommand = requireValue(args, arg);
+      continue;
+    }
+    if (arg === '--mecab-dictionary') {
+      mecabDictionaryPath = requireValue(args, arg);
+      continue;
+    }
+    if (arg.startsWith('-') && arg !== '-') {
+      throw new Error(`Unknown flag: ${arg}`);
+    }
+    inputParts.push(arg);
+  }
+
+  if (!name || !/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    throw new Error('A kebab-case --name is required (e.g. --name kureru-lexical-keep)');
+  }
+  const text = inputParts.join(' ').trim();
+  if (!text) {
+    throw new Error('Provide the subtitle text to record as positional arguments.');
+  }
+
+  if (knownWords.length > 0) config.knownWords = knownWords;
+  if (Object.keys(jlptLevels).length > 0) config.jlptLevels = jlptLevels;
+  if (Object.keys(localFrequencyRanks).length > 0) {
+    config.localFrequencyRanks = localFrequencyRanks;
+  }
+
+  return {
+    name,
+    text,
+    description,
+    issueRefs,
+    config,
+    outDir,
+    force,
+    yomitanExtensionPath,
+    yomitanUserDataPath,
+    mecabCommand,
+    mecabDictionaryPath,
+  };
+}
+
+const RECORDER_SHIM_SCRIPT = `
+(() => {
+  const g = globalThis;
+  if (g.__subminerGoldenRecorderInstalled) { return true; }
+  g.__subminerGoldenRecorderInstalled = true;
+  g.__subminerGoldenMessages = [];
+  const runtime = chrome.runtime;
+  const original = runtime.sendMessage.bind(runtime);
+  runtime.sendMessage = (payload, callback) => {
+    return original(payload, (response) => {
+      try {
+        g.__subminerGoldenMessages.push(JSON.parse(JSON.stringify({
+          action: payload && payload.action ? payload.action : '',
+          params: payload && typeof payload.params !== 'undefined' ? payload.params : null,
+          response: typeof response !== 'undefined' ? response : null,
+        })));
+      } catch {}
+      if (callback) { callback(response); }
+    });
+  };
+  return true;
+})();
+`;
+
+const RECORDER_DRAIN_SCRIPT = `
+(() => {
+  const g = globalThis;
+  const log = g.__subminerGoldenMessages || [];
+  g.__subminerGoldenMessages = [];
+  return JSON.stringify(log);
+})();
+`;
+
+interface RecordingSink {
+  messages: GoldenRecordedMessage[];
+  scripts: GoldenRecordedScript[];
+  mecab: Record<string, Token[] | null>;
+}
+
+function patchParserWindowForRecording(
+  window: Electron.BrowserWindow | null,
+  patched: WeakSet<object>,
+  sink: RecordingSink,
+): void {
+  if (!window || window.isDestroyed()) {
+    return;
+  }
+  const webContents = window.webContents as unknown as {
+    executeJavaScript: (script: string, userGesture?: boolean) => Promise<unknown>;
+  };
+  if (patched.has(webContents)) {
+    return;
+  }
+  patched.add(webContents);
+
+  const original = webContents.executeJavaScript.bind(webContents);
+  let shimReady: Promise<unknown> | null = null;
+  const drain = async (): Promise<void> => {
+    try {
+      const raw = (await original(RECORDER_DRAIN_SCRIPT, true)) as string;
+      const drained = JSON.parse(raw) as GoldenRecordedMessage[];
+      sink.messages.push(...drained);
+    } catch (error) {
+      process.stderr.write(
+        `Warning: failed to drain recorded messages: ${(error as Error).message}\n`,
+      );
+    }
+  };
+
+  webContents.executeJavaScript = async (script: string, userGesture?: boolean) => {
+    if (!shimReady) {
+      shimReady = original(RECORDER_SHIM_SCRIPT, true);
+    }
+    try {
+      await shimReady;
+    } catch {
+      shimReady = null;
+    }
+    let result: unknown;
+    try {
+      result = await original(script, userGesture);
+    } finally {
+      await drain();
+    }
+    sink.scripts.push({
+      sha256: hashInjectedScript(script),
+      marker: classifyInjectedScript(script),
+      result: result === undefined ? null : result,
+    });
+    return result;
+  };
+}
+
+async function main(): Promise<void> {
+  const options = parseCliArgs(process.argv.slice(2));
+  const outPath = path.join(options.outDir, `${options.name}.json`);
+  if (fs.existsSync(outPath) && !options.force) {
+    throw new Error(`${outPath} already exists; pass --force to overwrite.`);
+  }
+
+  const electronModule = await import('electron').catch(() => null);
+  if (!electronModule?.app || !electronModule?.session) {
+    throw new Error(
+      'Electron runtime is required; run via `bun run record-tokenizer-fixture:electron`.',
+    );
+  }
+
+  const mecabTokenizer = new MecabTokenizer({
+    mecabCommand: options.mecabCommand,
+    dictionaryPath: options.mecabDictionaryPath,
+  });
+  if (!(await mecabTokenizer.checkAvailability())) {
+    throw new Error('MeCab is not available on this system.');
+  }
+
+  if (typeof electronModule.app.setPath === 'function') {
+    electronModule.app.setPath('userData', options.yomitanUserDataPath);
+  }
+  await electronModule.app.whenReady();
+
+  const extensionPath = resolveBuiltYomitanExtensionPath({
+    explicitPath: options.yomitanExtensionPath,
+    cwd: process.cwd(),
+  });
+  if (!extensionPath) {
+    throw new Error('No built Yomitan extension found; run `bun run build:yomitan` first.');
+  }
+  const extension = await electronModule.session.defaultSession.loadExtension(extensionPath, {
+    allowFileAccess: true,
+  });
+
+  const sink: RecordingSink = { messages: [], scripts: [], mecab: {} };
+  const patched = new WeakSet<object>();
+  let parserWindow: Electron.BrowserWindow | null = null;
+  let parserReadyPromise: Promise<void> | null = null;
+  let parserInitPromise: Promise<boolean> | null = null;
+
+  const lookups = buildFixtureLookups(options.config);
+  const runtimeDeps = createTokenizerDepsRuntime({
+    getYomitanExt: () => extension,
+    getYomitanParserWindow: () => {
+      patchParserWindowForRecording(parserWindow, patched, sink);
+      return parserWindow;
+    },
+    setYomitanParserWindow: (window) => {
+      parserWindow = window;
+      patchParserWindowForRecording(parserWindow, patched, sink);
+    },
+    getYomitanParserReadyPromise: () => parserReadyPromise,
+    setYomitanParserReadyPromise: (promise) => {
+      parserReadyPromise = promise;
+    },
+    getYomitanParserInitPromise: () => parserInitPromise,
+    setYomitanParserInitPromise: (promise) => {
+      parserInitPromise = promise;
+    },
+    isKnownWord: lookups.isKnownWord,
+    getJlptLevel: lookups.getJlptLevel,
+    getFrequencyRank: lookups.getFrequencyRank,
+    ...fixtureConfigGetters(options.config),
+    getMecabTokenizer: () => ({
+      tokenize: async (text: string) => {
+        const rawTokens = await mecabTokenizer.tokenize(text);
+        sink.mecab[text] = rawTokens;
+        return rawTokens;
+      },
+    }),
+  });
+  const deps = {
+    ...runtimeDeps,
+    // Same pinned enrichment implementation the replay harness uses.
+    enrichTokensWithMecab: async (
+      tokens: Parameters<typeof enrichTokensWithMecabPos1>[0],
+      mecabTokens: Parameters<typeof enrichTokensWithMecabPos1>[1],
+    ) => enrichTokensWithMecabPos1(tokens, mecabTokens),
+  };
+
+  try {
+    const subtitleData = await tokenizeSubtitle(options.text, deps);
+    const expectedTokens = projectGoldenTokens(subtitleData.tokens);
+
+    const prunedMessages = pruneGoldenMessages(sink.messages);
+    const fixture: GoldenFixture = {
+      name: options.name,
+      ...(options.description ? { description: options.description } : {}),
+      ...(options.issueRefs.length > 0 ? { issueRefs: options.issueRefs } : {}),
+      recordedAt: new Date().toISOString(),
+      input: { text: options.text },
+      config: options.config,
+      recording: {
+        messages: prunedMessages,
+        scripts: sink.scripts,
+        mecab: sink.mecab,
+      },
+      expected: { tokens: expectedTokens },
+    };
+
+    fs.mkdirSync(options.outDir, { recursive: true });
+    fs.writeFileSync(outPath, `${JSON.stringify(fixture, null, 2)}\n`);
+
+    process.stdout.write(`Recorded ${outPath}\n`);
+    process.stdout.write(
+      `  messages=${prunedMessages.length} scripts=${sink.scripts.length} mecabTexts=${Object.keys(sink.mecab).length}\n`,
+    );
+    process.stdout.write('\nExpected tokens (review before committing):\n');
+    if (!expectedTokens || expectedTokens.length === 0) {
+      process.stdout.write('  (none)\n');
+    } else {
+      for (const token of expectedTokens) {
+        const flags = [
+          token.isKnown ? 'known' : null,
+          token.isNPlusOneTarget ? 'n+1' : null,
+          token.isNameMatch ? 'name' : null,
+          token.isUnparsedRun ? 'unparsed' : null,
+          token.jlptLevel ?? null,
+          token.frequencyRank !== undefined ? `freq=${token.frequencyRank}` : null,
+        ]
+          .filter(Boolean)
+          .join(', ');
+        process.stdout.write(
+          `  ${token.surface} -> ${token.headword} (${token.reading})${flags ? ` [${flags}]` : ''}\n`,
+        );
+      }
+    }
+    process.stdout.write(
+      '\nVerify replay with: bun test src/core/services/tokenizer/golden-corpus.test.ts\n',
+    );
+  } finally {
+    if (parserWindow) {
+      const window = parserWindow as Electron.BrowserWindow;
+      if (!window.isDestroyed()) {
+        window.destroy();
+      }
+    }
+    electronModule.app.quit();
+  }
+}
+
+main()
+  .then(() => process.exit(0))
+  .catch((error) => {
+    console.error(`Error: ${(error as Error).message}`);
+    process.exit(1);
+  });
@@ -16,15 +16,6 @@ export const testLanes: Record<string, TestLane> = {
  'bun-src-full': {
    roots: ['src'],
    include: ['.test.ts', '.type-test.ts'],
-    // Node-compat suites; their dist builds run via test:runtime:compat.
-    exclude: [
-      'src/core/services/anki-jimaku-ipc.test.ts',
-      'src/core/services/ipc.test.ts',
-      'src/core/services/overlay-manager.test.ts',
-      'src/main/config-validation.test.ts',
-      'src/main/runtime/registry.test.ts',
-      'src/main/runtime/startup-config.test.ts',
-    ],
  },
  config: {
    roots: ['src/config'],
@@ -237,6 +237,14 @@ local ctx = {
 						actionType = "session-action",
 						actionId = "openPlaylistBrowser",
 					},
+					{
+						key = {
+							code = "KeyT",
+							modifiers = { "ctrl", "alt" },
+						},
+						actionType = "session-action",
+						actionId = "openAnimetosho",
+					},
 					{
 						key = {
 							code = "KeyH",
@@ -387,6 +395,7 @@ end
 local expected_cli_bindings = {
 	{ keys = "Ctrl+Alt+c", flag = "--open-youtube-picker" },
 	{ keys = "Ctrl+Alt+p", flag = "--open-playlist-browser" },
+	{ keys = "Ctrl+Alt+t", flag = "--open-tsukihime" },
 	{ keys = "Ctrl+H", flag = "--replay-current-subtitle" },
 	{ keys = "Ctrl+L", flag = "--play-next-subtitle" },
 	{ keys = "w", flag = "--mark-watched" },
@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { fetchYomitanApi } from './yomitan-api-request.js';
+
+function createStalledServer(): ReturnType<typeof Bun.serve> {
+  return Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch: () => new Promise<Response>(() => {}),
+  });
+}
+
+test('fetchYomitanApi reports a clear timeout when the bridge stalls', async () => {
+  const server = createStalledServer();
+
+  try {
+    await assert.rejects(
+      () => fetchYomitanApi(`${server.url}tokenize`, { method: 'POST' }, 20),
+      /Yomitan API request timed out after 20ms/,
+    );
+  } finally {
+    server.stop(true);
+  }
+});
+
+test('fetchYomitanApi preserves an init cancellation signal', async () => {
+  const server = createStalledServer();
+  const controller = new AbortController();
+  const reason = new Error('cancelled by caller');
+
+  try {
+    const request = fetchYomitanApi(`${server.url}tokenize`, { signal: controller.signal }, 50);
+    controller.abort(reason);
+    await assert.rejects(request, (error) => error === reason);
+  } finally {
+    server.stop(true);
+  }
+});
+
+test('fetchYomitanApi preserves a Request input cancellation signal', async () => {
+  const server = createStalledServer();
+  const controller = new AbortController();
+  const reason = new Error('cancelled by request');
+  const input = new Request(`${server.url}tokenize`, { signal: controller.signal });
+
+  try {
+    const request = fetchYomitanApi(input, undefined, 50);
+    controller.abort(reason);
+    await assert.rejects(request, (error) => error === reason);
+  } finally {
+    server.stop(true);
+  }
+});
+
+test('fetchYomitanApi accepts a null init cancellation signal', async () => {
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch: () => new Response('ok'),
+  });
+
+  try {
+    const response = await fetchYomitanApi(`${server.url}tokenize`, { signal: null }, 50);
+    assert.equal(response.status, 200);
+  } finally {
+    server.stop(true);
+  }
+});
@@ -0,0 +1,26 @@
+const DEFAULT_YOMITAN_API_TIMEOUT_MS = 10_000;
+
+export async function fetchYomitanApi(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  timeoutMs = DEFAULT_YOMITAN_API_TIMEOUT_MS,
+): Promise<Response> {
+  const controller = new AbortController();
+  const requestSignal = input instanceof Request ? input.signal : undefined;
+  const signals = [controller.signal, init?.signal, requestSignal].filter(
+    (signal): signal is AbortSignal => signal != null,
+  );
+  const signal = signals.length === 1 ? controller.signal : AbortSignal.any(signals);
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetch(input, { ...init, signal });
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new Error(`Yomitan API request timed out after ${timeoutMs}ms`, { cause: error });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
@@ -1,5 +1,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import http from 'node:http';
+import { once } from 'node:events';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -465,6 +467,66 @@ test('AnkiIntegration does not allocate proxy server when proxy transport is dis
  assert.equal(privateState.runtime.proxyServer, null);
 });

+test('AnkiIntegration reports an occupied proxy address through its notification seam', async () => {
+  const occupiedServer = http.createServer();
+  occupiedServer.listen(0, '127.0.0.1');
+  await once(occupiedServer, 'listening');
+  const occupiedAddress = occupiedServer.address();
+  assert.ok(occupiedAddress && typeof occupiedAddress === 'object');
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-anki-proxy-collision-'));
+  const overlayNotifications: TestOverlayNotificationPayload[] = [];
+  const integration = new AnkiIntegration(
+    {
+      enabled: true,
+      url: 'http://127.0.0.1:8765',
+      proxy: {
+        enabled: true,
+        host: '127.0.0.1',
+        port: occupiedAddress.port,
+        upstreamUrl: 'http://127.0.0.1:8765',
+      },
+      behavior: {
+        notificationType: 'overlay',
+      },
+      knownWords: {
+        highlightEnabled: false,
+      },
+      nPlusOne: {
+        enabled: false,
+      },
+    } as never,
+    {} as never,
+    {} as never,
+    undefined,
+    undefined,
+    undefined,
+    path.join(stateDir, 'known-words-cache.json'),
+    {},
+    undefined,
+    (payload) => {
+      overlayNotifications.push(payload as TestOverlayNotificationPayload);
+    },
+  );
+
+  try {
+    integration.start();
+    await integration.waitUntilReady();
+
+    assert.deepEqual(overlayNotifications, [
+      {
+        title: 'SubMiner',
+        body: `AnkiConnect proxy unavailable because http://127.0.0.1:${occupiedAddress.port} is already in use. Change ankiConnect.proxy.port or stop the process using that address.`,
+        variant: 'info',
+      },
+    ]);
+  } finally {
+    integration.stop();
+    occupiedServer.close();
+    await once(occupiedServer, 'close');
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+});
+
 test('AnkiIntegration triggers field grouping after a local duplicate sentence card is created', async () => {
  const integration = new AnkiIntegration(
    {
@@ -461,6 +461,7 @@ export class AnkiIntegration {
      getDeck: () => this.config.deck,
      findNotes: async (query, options) =>
        (await this.client.findNotes(query, options)) as number[],
+      notifyUnavailable: (message) => this.showStatusNotification(message),
      logInfo: (message, ...args) => log.info(message, ...args),
      logWarn: (message, ...args) => log.warn(message, ...args),
      logError: (message, ...args) => log.error(message, ...args),
@@ -543,3 +543,41 @@ test('proxy detects self-referential loop configuration', () => {

  assert.equal(result, true);
 });
+
+test('proxy continues without a local listener when its address is already bound', async () => {
+  const occupiedServer = http.createServer();
+  occupiedServer.listen(0, '127.0.0.1');
+  await once(occupiedServer, 'listening');
+  const occupiedAddress = occupiedServer.address();
+  assert.ok(occupiedAddress && typeof occupiedAddress === 'object');
+  const info: string[] = [];
+  const warnings: string[] = [];
+  const proxy = new AnkiConnectProxyServer({
+    shouldAutoUpdateNewCards: () => true,
+    processNewCard: async () => undefined,
+    logInfo: (message) => info.push(message),
+    logWarn: (message, ...args) => warnings.push([message, ...args].join(' ')),
+    logError: () => undefined,
+  });
+
+  try {
+    proxy.start({
+      host: '127.0.0.1',
+      port: occupiedAddress.port,
+      upstreamUrl: 'http://127.0.0.1:8765',
+    });
+
+    await proxy.waitUntilReady();
+
+    assert.equal(proxy.isRunning, false);
+    assert.deepEqual(warnings, [
+      `[anki-proxy] Local proxy unavailable because http://127.0.0.1:${occupiedAddress.port} is already in use; continuing without it. Change ankiConnect.proxy.port or stop the process using that address.`,
+    ]);
+    proxy.stop();
+    assert.deepEqual(info, []);
+  } finally {
+    proxy.stop();
+    occupiedServer.close();
+    await once(occupiedServer, 'close');
+  }
+});
@@ -27,6 +27,7 @@ export interface AnkiConnectProxyServerDeps {
  logInfo: (message: string, ...args: unknown[]) => void;
  logWarn: (message: string, ...args: unknown[]) => void;
  logError: (message: string, ...args: unknown[]) => void;
+  notifyUnavailable?: (message: string) => void;
 }

 export class AnkiConnectProxyServer {
@@ -78,7 +79,23 @@ export class AnkiConnectProxyServer {
      void this.handleRequest(req, res, options.upstreamUrl);
    });

+    const server = this.server;
    this.server.on('error', (error) => {
+      if ((error as NodeJS.ErrnoException).code === 'EADDRINUSE') {
+        this.resolveReady?.();
+        this.resolveReady = null;
+        this.rejectReady = null;
+        if (this.server === server) {
+          this.server = null;
+        }
+        this.deps.logWarn(
+          `[anki-proxy] Local proxy unavailable because http://${options.host}:${options.port} is already in use; continuing without it. Change ankiConnect.proxy.port or stop the process using that address.`,
+        );
+        this.deps.notifyUnavailable?.(
+          `AnkiConnect proxy unavailable because http://${options.host}:${options.port} is already in use. Change ankiConnect.proxy.port or stop the process using that address.`,
+        );
+        return;
+      }
      this.rejectReady?.(error as Error);
      this.resolveReady = null;
      this.rejectReady = null;
@@ -762,7 +762,10 @@ test('KnownWordCacheManager suppresses reading-only matches when disallowed', as
    // Reading-only match stays available for kana subtitle text…
    assert.equal(manager.isKnownWord('けいこく'), true);
    // …but a kanji token's reading (渓谷/けいこく) must not borrow 警告's.
-    assert.equal(manager.isKnownWord('けいこく', undefined, { allowReadingOnlyMatch: false }), false);
+    assert.equal(
+      manager.isKnownWord('けいこく', undefined, { allowReadingOnlyMatch: false }),
+      false,
+    );
    // Mined word texts still match regardless of the flag.
    assert.equal(manager.isKnownWord('警告', undefined, { allowReadingOnlyMatch: false }), true);
  } finally {
@@ -12,19 +12,6 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
  scripts: Record<string, string>;
 };

-test('ci workflow lints changelog fragments', () => {
-  assert.match(ciWorkflow, /bun run changelog:lint/);
-});
-
-test('ci workflow checks pull requests for required changelog fragments', () => {
-  assert.match(ciWorkflow, /bun run changelog:pr-check/);
-  assert.match(ciWorkflow, /skip-changelog/);
-});
-
-test('ci workflow verifies generated config examples stay in sync', () => {
-  assert.match(ciWorkflow, /bun run verify:config-example/);
-});
-
 test('package scripts expose a sharded maintained source coverage lane with lcov output', () => {
  assert.equal(
    packageJson.scripts['test:coverage:src'],
@@ -32,11 +19,14 @@ test('package scripts expose a sharded maintained source coverage lane with lcov
  );
 });

-test('ci workflow runs the maintained source coverage lane and uploads lcov output', () => {
-  assert.match(ciWorkflow, /name: Coverage suite \(maintained source lane\)/);
-  assert.match(ciWorkflow, /run: bun run test:coverage:src/);
-  assert.match(ciWorkflow, /name: Upload coverage artifact/);
-  assert.match(ciWorkflow, /path: coverage\/test-src\/lcov\.info/);
+test('ci delegates its gate instead of duplicating quality steps', () => {
+  assert.match(
+    ciWorkflow,
+    /build-test-audit:\s*\n\s*uses: \.\/\.github\/workflows\/quality-gate\.yml/,
+  );
+  assert.doesNotMatch(ciWorkflow, /oven-sh\/setup-bun/);
+  assert.doesNotMatch(ciWorkflow, /bun run test:coverage:src/);
+  assert.doesNotMatch(ciWorkflow, /bun run test:env/);
 });

 test('main docs deploy exists, serializes deploys, and uses Cloudflare credentials', () => {
@@ -115,6 +115,7 @@ test('parseArgs captures session action forwarding flags', () => {
    '--toggle-stats-overlay',
    '--mark-watched',
    '--open-jimaku',
+    '--open-tsukihime',
    '--open-youtube-picker',
    '--open-playlist-browser',
    '--toggle-primary-subtitle-bar',
@@ -132,6 +133,7 @@ test('parseArgs captures session action forwarding flags', () => {
  assert.equal(args.toggleStatsOverlay, true);
  assert.equal(args.markWatched, true);
  assert.equal(args.openJimaku, true);
+  assert.equal(args.openTsukihime, true);
  assert.equal(args.openYoutubePicker, true);
  assert.equal(args.openPlaylistBrowser, true);
  assert.equal(args.togglePrimarySubtitleBar, true);
@@ -146,6 +148,14 @@ test('parseArgs captures session action forwarding flags', () => {
  assert.equal(shouldStartApp(args), true);
 });

+test('parseArgs keeps the legacy Animetosho open flag as a TsukiHime alias', () => {
+  const args = parseArgs(['--open-animetosho']);
+
+  assert.equal(args.openTsukihime, true);
+  assert.equal(hasExplicitCommand(args), true);
+  assert.equal(shouldStartApp(args), true);
+});
+
 test('parseArgs ignores retired subtitle delay shift flags', () => {
  const args = parseArgs(['--shift-sub-delay-prev-line', '--shift-sub-delay-next-line']);

@@ -14,6 +14,7 @@ export interface CliArgs {
  togglePrimarySubtitleBar: boolean;
  yomitan: boolean;
  settings: boolean;
+  syncWindow: boolean;
  setup: boolean;
  show: boolean;
  hide: boolean;
@@ -37,6 +38,7 @@ export interface CliArgs {
  openControllerSelect: boolean;
  openControllerDebug: boolean;
  openJimaku: boolean;
+  openTsukihime: boolean;
  openYoutubePicker: boolean;
  openPlaylistBrowser: boolean;
  replayCurrentSubtitle: boolean;
@@ -122,6 +124,7 @@ export function parseArgs(argv: string[]): CliArgs {
    togglePrimarySubtitleBar: false,
    yomitan: false,
    settings: false,
+    syncWindow: false,
    setup: false,
    show: false,
    hide: false,
@@ -145,6 +148,7 @@ export function parseArgs(argv: string[]): CliArgs {
    openControllerSelect: false,
    openControllerDebug: false,
    openJimaku: false,
+    openTsukihime: false,
    openYoutubePicker: false,
    openPlaylistBrowser: false,
    replayCurrentSubtitle: false,
@@ -269,6 +273,7 @@ export function parseArgs(argv: string[]): CliArgs {
    else if (arg === '--toggle-primary-subtitle-bar') args.togglePrimarySubtitleBar = true;
    else if (arg === '--yomitan') args.yomitan = true;
    else if (arg === '--settings') args.settings = true;
+    else if (arg === '--sync-window') args.syncWindow = true;
    else if (arg === '--setup') args.setup = true;
    else if (arg === '--show') args.show = true;
    else if (arg === '--hide') args.hide = true;
@@ -292,7 +297,9 @@ export function parseArgs(argv: string[]): CliArgs {
    else if (arg === '--open-controller-select') args.openControllerSelect = true;
    else if (arg === '--open-controller-debug') args.openControllerDebug = true;
    else if (arg === '--open-jimaku') args.openJimaku = true;
-    else if (arg === '--open-youtube-picker') args.openYoutubePicker = true;
+    else if (arg === '--open-tsukihime' || arg === '--open-animetosho') {
+      args.openTsukihime = true;
+    } else if (arg === '--open-youtube-picker') args.openYoutubePicker = true;
    else if (arg === '--open-playlist-browser') args.openPlaylistBrowser = true;
    else if (arg === '--replay-current-subtitle') args.replayCurrentSubtitle = true;
    else if (arg === '--play-next-subtitle') args.playNextSubtitle = true;
@@ -541,6 +548,7 @@ export function hasExplicitCommand(args: CliArgs): boolean {
    args.togglePrimarySubtitleBar ||
    args.yomitan ||
    args.settings ||
+    args.syncWindow ||
    args.setup ||
    args.show ||
    args.hide ||
@@ -564,6 +572,7 @@ export function hasExplicitCommand(args: CliArgs): boolean {
    args.openControllerSelect ||
    args.openControllerDebug ||
    args.openJimaku ||
+    args.openTsukihime ||
    args.openYoutubePicker ||
    args.openPlaylistBrowser ||
    args.replayCurrentSubtitle ||
@@ -618,6 +627,7 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
    !args.togglePrimarySubtitleBar &&
    !args.yomitan &&
    !args.settings &&
+    !args.syncWindow &&
    !args.setup &&
    !args.show &&
    !args.hide &&
@@ -641,6 +651,7 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
    !args.openControllerSelect &&
    !args.openControllerDebug &&
    !args.openJimaku &&
+    !args.openTsukihime &&
    !args.openYoutubePicker &&
    !args.openPlaylistBrowser &&
    !args.replayCurrentSubtitle &&
@@ -688,6 +699,7 @@ export function shouldStartApp(args: CliArgs): boolean {
    args.togglePrimarySubtitleBar ||
    args.yomitan ||
    args.settings ||
+    args.syncWindow ||
    args.setup ||
    args.copySubtitle ||
    args.copySubtitleMultiple ||
@@ -707,6 +719,7 @@ export function shouldStartApp(args: CliArgs): boolean {
    args.openControllerSelect ||
    args.openControllerDebug ||
    args.openJimaku ||
+    args.openTsukihime ||
    args.openYoutubePicker ||
    args.openPlaylistBrowser ||
    args.replayCurrentSubtitle ||
@@ -744,6 +757,7 @@ export function shouldRunYomitanOnlyStartup(args: CliArgs): boolean {
    !args.toggleVisibleOverlay &&
    !args.togglePrimarySubtitleBar &&
    !args.settings &&
+    !args.syncWindow &&
    !args.show &&
    !args.hide &&
    !args.setup &&
@@ -767,6 +781,7 @@ export function shouldRunYomitanOnlyStartup(args: CliArgs): boolean {
    !args.openControllerSelect &&
    !args.openControllerDebug &&
    !args.openJimaku &&
+    !args.openTsukihime &&
    !args.openYoutubePicker &&
    !args.openPlaylistBrowser &&
    !args.replayCurrentSubtitle &&
@@ -832,6 +847,7 @@ export function commandNeedsOverlayRuntime(args: CliArgs): boolean {
    args.openControllerSelect ||
    args.openControllerDebug ||
    args.openJimaku ||
+    args.openTsukihime ||
    args.openYoutubePicker ||
    args.openPlaylistBrowser ||
    args.replayCurrentSubtitle ||
@@ -79,6 +79,11 @@ ${B}Jellyfin${R}
  --jellyfin-audio-stream-index ${D}N${R}       Audio stream override
  --jellyfin-subtitle-stream-index ${D}N${R}    Subtitle stream override

+${B}Stats sync${R}
+  --sync-window                  Open the stats sync window
+  --sync-cli sync ${D}[host] [opts]${R}   Headless stats sync ${D}(same commands as "subminer sync";${R}
+                                 ${D}run SubMiner --sync-cli --help for details)${R}
+
 ${B}Options${R}
  --socket ${D}PATH${R}                  mpv IPC socket path
  --backend ${D}BACKEND${R}              Window tracker ${D}(auto, hyprland, sway, x11, macos, windows)${R}
@@ -112,8 +112,20 @@ function buildLegacyNPlusOneMigrationOperations(root: JsoncNode | undefined): {
      if (!key) continue;
      const valueNode = propertyValue(property);
      const value = valueNode ? getNodeValue(valueNode) : undefined;
-      if (key === 'enabled' || key === 'minSentenceWords') {
-        canonicalNPlusOneValues.set(key, value);
+      if (key === 'enabled') {
+        if (typeof value === 'boolean') {
+          canonicalNPlusOneValues.set(key, value);
+        } else {
+          canonicalNPlusOneValues.delete(key);
+        }
+        continue;
+      }
+      if (key === 'minSentenceWords') {
+        if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+          canonicalNPlusOneValues.set(key, value);
+        } else {
+          canonicalNPlusOneValues.delete(key);
+        }
        continue;
      }
      if (key in LEGACY_N_PLUS_ONE_PATH_MAP) {
@@ -2462,6 +2462,37 @@ test('resolves duplicate ankiConnect nPlusOne objects without rewriting config',
  assert.equal(fs.readFileSync(configPath, 'utf-8'), originalContent);
 });

+test('later invalid duplicate nPlusOne values supersede earlier valid values', () => {
+  const dir = makeTempDir();
+  const configPath = path.join(dir, 'config.jsonc');
+  const originalContent = `{
+      "ankiConnect": {
+        "nPlusOne": {
+          "enabled": true,
+          "minSentenceWords": 4
+        },
+        "nPlusOne": {
+          "enabled": "yes",
+          "minSentenceWords": "4"
+        }
+      }
+    }`;
+  fs.writeFileSync(configPath, originalContent, 'utf-8');
+
+  const service = new ConfigService(dir);
+  const config = service.getConfig();
+  const warnings = service.getWarnings();
+
+  assert.equal(config.ankiConnect.nPlusOne.enabled, DEFAULT_CONFIG.ankiConnect.nPlusOne.enabled);
+  assert.equal(
+    config.ankiConnect.nPlusOne.minSentenceWords,
+    DEFAULT_CONFIG.ankiConnect.nPlusOne.minSentenceWords,
+  );
+  assert.ok(warnings.some((warning) => warning.path === 'ankiConnect.nPlusOne.enabled'));
+  assert.ok(warnings.some((warning) => warning.path === 'ankiConnect.nPlusOne.minSentenceWords'));
+  assert.equal(fs.readFileSync(configPath, 'utf-8'), originalContent);
+});
+
 test('supports legacy ankiConnect.behavior N+1 settings as fallback', () => {
  const dir = makeTempDir();
  fs.writeFileSync(
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
sudacode	08c6807cb1	fix(launcher): normalize rofi prompt spacing - Add formatRofiPrompt to trim trailing whitespace and append a single space, keeping the prompt from running into the input field - Apply it across all rofi -p usages in picker.ts and history-command.ts - Add tests for formatRofiPrompt edge cases (empty/whitespace-only prompts)	2026-07-26 00:13:54 -07:00
sudacode	18c6410f24	feat(launcher): add previous episode option to history entry menu - Extract buildHistoryEntryActions to build the series action menu, now including a previous-episode option alongside replay/next/browse/quit - Update docs and changelog entry to describe the new option - Add tests covering previous/replay/next ordering and omission when last watched file is missing	2026-07-25 23:35:44 -07:00
sudacode	e223cf9b71	fix(release): restore compatible js-yaml override	2026-07-22 23:51:21 -07:00
sudacode	c718bb8b34	chore(release): prepare 0.19.0-beta.2	2026-07-22 23:34:08 -07:00
sudacode	177f7e5fd6	docs(readme): remove TsukiHime credit - Drop the TsukiHime row from the open-source credits table	2026-07-22 23:07:07 -07:00
sudacode	20b50ec4e1	feat(launcher): add post-playback history menu with previous episode (#170 )	2026-07-22 23:05:53 -07:00
sudacode	deae61b211	refactor: split anki-connect and stats-server resolvers into modules (#169 )	2026-07-17 23:05:59 -07:00
sudacode	44959ed282	fix(anki,appimage): handle proxy port conflicts and stray GPU child - AnkiConnect proxy now detects EADDRINUSE, logs a warning, and surfaces an overlay notification instead of crashing video startup - Background AppImage bootstrap runs Chromium with in-process-gpu so no GPU child survives app.exit() and outlives the FUSE mount, fixing the remaining DrKonqi "Service Crash" case - Add changelog fragment for the proxy fix; update the AppImage quit fragment with the GPU child root cause	2026-07-17 23:04:56 -07:00
sudacode	2398f5c030	refactor(main): eliminate local pass-through wrappers in main.ts (#168 )	2026-07-15 03:22:03 -07:00
sudacode	8711cf1a48	remove redundant isVerbNonIndependent and consolidate test lanes - drop always-true isVerbNonIndependent export; collapse shouldMerge branch - remove node-compat exclusion list from bun-src-full lane - simplify test:fast (drop test:runtime:compat), test:env, test:smoke:dist scripts - rename test:launcher:env:src -> test:env in docs	2026-07-14 19:57:50 -07:00
sudacode	9f4888293b	chore(release): prepare 0.19.0-beta.1	2026-07-13 23:47:50 -07:00
sudacode	29332b103e	Consolidate sync changelog fragments into one entry - Merge the five separate sync change fragments (launcher command, UI window, close/quit fixes, active-session double-count, monthly rollup timezone) into a single changes/sync.md - Fold kana-pos-content-classification.md into annotation-noise-rule-table.md - Drop the now-stale Unreleased sections from CHANGELOG.md and docs-site/changelog.md - Tweak tsukihime-english-subtitles.md wording	2026-07-13 23:40:28 -07:00
sudacode	8b2cee2c58	ci: reuse quality gate across CI and release workflows (#167 )	2026-07-13 23:14:19 -07:00
sudacode	2e2ee3f028	refactor(tsukihime): swap Animetosho backend for TsukiHime API (#165 )	2026-07-13 22:03:35 -07:00
sudacode	49b926e08c	Sync Stats & History window, headless --sync-cli, and Windows remote support (#160 )	2026-07-13 18:56:51 -07:00
sudacode	66f8ca4f80	refactor(renderer): extract modal registry for open/dismiss/active queries (#166 )	2026-07-13 18:16:39 -07:00
sudacode	6fe1e0fee4	refactor(stats): drop dead IPC handlers, unify stats types over HTTP (#164 )	2026-07-13 12:09:56 -07:00
sudacode	0ab840b362	refactor(tokenizer): extract subtitle annotation filter into rule table (#162 )	2026-07-12 23:54:13 -07:00
sudacode	21a06c12fb	refactor(tokenizer): consolidate kana/POS helpers into token-classification (#161 )	2026-07-12 23:27:25 -07:00
sudacode	14070acceb	fix(overlay): defer autoplay release for untokenized startup priming - Autoplay-ready gate now ignores untokenized subtitle payloads while tokenization warmup is pending, so playback doesn't resume before the first tokenized cue - Wire isTokenizationReady dep through main.ts and update gate/wiring tests accordingly - Drop stale release/release-notes.md, add changelog entry under changes/	2026-07-12 02:11:10 -07:00
sudacode	7d81342f0f	fix(app): keep AppImage mount alive until Chromium children finish shutdown Background AppImage launches executed directly from a FUSE mount owned by a short-lived helper's AppImage runtime. On quit, the runtime unmounted the squashfs while utility children (network service) were still mid-shutdown, SIGBUSing them and triggering KDE Service Crash notifications on every video close. Detach a POSIX-sh supervisor instead: mount via --appimage-mount, run AppRun from the mount, and release the holder only once no process still executes from the mount. Falls back to the old direct launch on any failure or with SUBMINER_NO_APPIMAGE_MOUNT_KEEPALIVE=1.	2026-07-12 02:09:42 -07:00
sudacode	4b7f750919	feat(animetosho): add English/Japanese subtitle download integration (#159 )	2026-07-12 00:48:12 -07:00
sudacode	6ab3d823a4	feat(shortcuts): make clipboard-video-append shortcut configurable (#158 )	2026-07-11 23:36:44 -07:00
sudacode	8797719a09	docs(docs-site): correct and clarify docs against current code Comprehensive accuracy pass over docs-site verifying every page against current source. Fixes wrong/stale claims (AniSkip default, YouTube track selection, Anki sentence-card requirements, immersion schema v18 + SQL column names, plugin entrypoint, launcher flags, Cloudflare deploy path, etc.) and fills gaps (watch history, mediaCache.maxHeight, youtubeSubgen, character-dictionary refresh/eviction, expanded hot-reload lists).	2026-07-11 00:53:34 -07:00
sudacode	8acc78cc1c	test(tokenizer): add golden-file regression corpus with 11 fixtures (#157 )	2026-07-11 00:50:03 -07:00
sudacode	321461c50f	feat(launcher): add `subminer sync` for cross-machine stats/history merge over SSH (#152 )	2026-07-11 00:40:15 -07:00